secboot

package
Version: v0.0.0-...-c7fba9c Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 25, 2021 License: GPL-3.0 Imports: 23 Imported by: 0

Documentation

Index

Constants

View Source
const (
	// Handles are in the block reserved for TPM owner objects (0x01800000 - 0x01bfffff)
	RunObjectPCRPolicyCounterHandle      = 0x01880001
	FallbackObjectPCRPolicyCounterHandle = 0x01880002
)

Variables

View Source
var WithSecbootSupport = false

WithSecbootSupport is true if this package was built with githbu.com/snapcore/secboot.

Functions

func AddRecoveryKey

func AddRecoveryKey(key EncryptionKey, rkey RecoveryKey, node string) error

AddRecoveryKey adds a fallback recovery key rkey to the existing encrypted volume created with FormatEncryptedDevice on the block device given by node. The existing key to the encrypted volume is provided in the key argument.

A heuristic memory cost is used.

func CheckTPMKeySealingSupported

func CheckTPMKeySealingSupported() error

func EncryptedPartitionName

func EncryptedPartitionName(name string) string

EncryptedPartitionName returns the name/label used by an encrypted partition corresponding to a given name.

func FormatEncryptedDevice

func FormatEncryptedDevice(key EncryptionKey, label, node string) error

FormatEncryptedDevice initializes an encrypted volume on the block device given by node, setting the specified label. The key used to unlock the volume is provided using the key argument.

func LockSealedKeys

func LockSealedKeys() error

LockSealedKeys manually locks access to the sealed keys. Meant to be called in place of passing lockKeysOnFinish as true to UnlockVolumeUsingSealedKeyIfEncrypted for cases where we don't know if a given call is the last one to unlock a volume like in degraded recover mode.

func MeasureSnapModelWhenPossible

func MeasureSnapModelWhenPossible(findModel func() (*asserts.Model, error)) error

MeasureSnapModelWhenPossible measures the snap model only if the TPM device is available. If there's no TPM device success is returned.

func MeasureSnapSystemEpochWhenPossible

func MeasureSnapSystemEpochWhenPossible() error

MeasureSnapSystemEpochWhenPossible measures the snap system epoch only if the TPM device is available. If there's no TPM device success is returned.

func ResealKeys

func ResealKeys(params *ResealKeysParams) error

ResealKeys updates the PCR protection policy for the sealed encryption keys according to the specified parameters.

func SealKeys

func SealKeys(keys []SealKeyRequest, params *SealKeysParams) error

SealKeys provisions the TPM and seals the encryption keys according to the specified parameters. If the TPM is already provisioned, or a sealed key already exists, SealKeys will fail and return an error.

func SealKeysWithFDESetupHook

func SealKeysWithFDESetupHook(runHook fde.RunSetupHookFunc, keys []SealKeyRequest, params *SealKeysWithFDESetupHookParams) error

SealKeysWithFDESetupHook protects the given keys through using the fde-setup hook and saves each protected key to the KeyFile indicated in the key SealKeyRequest.

func UnlockEncryptedVolumeWithRecoveryKey

func UnlockEncryptedVolumeWithRecoveryKey(name, device string) error

UnlockEncryptedVolumeWithRecoveryKey prompts for the recovery key and uses it to open an encrypted device.

Types

type AuxKey

type AuxKey [auxKeySize]byte

AuxKey is the key to bind models to keys.

func NewAuxKey

func NewAuxKey() (AuxKey, error)

type EncryptionKey

type EncryptionKey []byte

EncryptionKey is the key used to encrypt the data partition.

func NewEncryptionKey

func NewEncryptionKey() (EncryptionKey, error)

func (EncryptionKey) Save

func (key EncryptionKey) Save(filename string) error

Save writes the key in the location specified by filename.

type LoadChain

type LoadChain struct {
	*bootloader.BootFile
	// Next is a list of alternative chains that can be loaded
	// following the boot file.
	Next []*LoadChain
}

func NewLoadChain

func NewLoadChain(bf bootloader.BootFile, next ...*LoadChain) *LoadChain

NewLoadChain returns a LoadChain corresponding to loading the given BootFile before any of the given next chains.

type ModelForSealing

type ModelForSealing interface {
	Series() string
	BrandID() string
	Model() string
	Grade() asserts.ModelGrade
	SignKeyID() string
}

ModelForSealing provides information about the model for use in the context of (re)sealing the encryption keys.

type RecoveryKey

type RecoveryKey [recoveryKeySize]byte

RecoveryKey is a key used to unlock the encrypted partition when the encryption key can't be used, for example when unseal fails.

func NewRecoveryKey

func NewRecoveryKey() (RecoveryKey, error)

func RecoveryKeyFromFile

func RecoveryKeyFromFile(recoveryKeyFile string) (*RecoveryKey, error)

func (RecoveryKey) Save

func (key RecoveryKey) Save(filename string) error

Save writes the recovery key in the location specified by filename.

func (RecoveryKey) String

func (k RecoveryKey) String() string

type ResealKeysParams

type ResealKeysParams struct {
	// The snap model parameters
	ModelParams []*SealKeyModelParams
	// The path to the sealed key files
	KeyFiles []string
	// The path to the authorization policy update key file (only relevant for TPM)
	TPMPolicyAuthKeyFile string
}

type SealKeyModelParams

type SealKeyModelParams struct {
	// The snap model
	Model ModelForSealing
	// The set of EFI binary load chains for the current device
	// configuration
	EFILoadChains []*LoadChain
	// The kernel command line
	KernelCmdlines []string
}

type SealKeyRequest

type SealKeyRequest struct {
	// The key to seal
	Key EncryptionKey
	// The key name; identical keys should have identical names
	KeyName string
	// The path to store the sealed key file. The same Key/KeyName
	// can be stored under multiple KeyFile names for safety.
	KeyFile string
}

type SealKeysParams

type SealKeysParams struct {
	// The parameters we're sealing the key to
	ModelParams []*SealKeyModelParams
	// The authorization policy update key file (only relevant for TPM)
	TPMPolicyAuthKey *ecdsa.PrivateKey
	// The path to the authorization policy update key file (only relevant for TPM,
	// if empty the key will not be saved)
	TPMPolicyAuthKeyFile string
	// The path to the lockout authorization file (only relevant for TPM and only
	// used if TPMProvision is set to true)
	TPMLockoutAuthFile string
	// Whether we should provision the TPM
	TPMProvision bool
	// The handle at which to create a NV index for dynamic authorization policy revocation support
	PCRPolicyCounterHandle uint32
}

type SealKeysWithFDESetupHookParams

type SealKeysWithFDESetupHookParams struct {
	// Initial model to bind sealed keys to.
	Model ModelForSealing
	// AuxKey is the auxiliary key used to bind models.
	AuxKey AuxKey
	// The path to the aux key file (if empty the key will not be
	// saved)
	AuxKeyFile string
}

type UnlockMethod

type UnlockMethod int

UnlockMethod is the method that was used to unlock a volume.

const (
	// NotUnlocked indicates that the device was either not unlocked or is not
	// an encrypted device.
	NotUnlocked UnlockMethod = iota
	// UnlockedWithSealedKey indicates that the device was unlocked with the
	// provided sealed key object.
	UnlockedWithSealedKey
	// UnlockedWithRecoveryKey indicates that the device was unlocked by the
	// user providing the recovery key at the prompt.
	UnlockedWithRecoveryKey
	// UnlockedWithKey indicates that the device was unlocked with the provided
	// key, which is not sealed.
	UnlockedWithKey
	// UnlockStatusUnknown indicates that the unlock status of the device is not clear.
	UnlockStatusUnknown
)

type UnlockResult

type UnlockResult struct {
	// FsDevice is the device with filesystem ready to mount.
	// It is the activated device if encrypted or just
	// the underlying device (same as PartDevice) if non-encrypted.
	// FsDevice can be empty when none was found.
	FsDevice string
	// PartDevice is the underlying partition device.
	// PartDevice can be empty when no device was found.
	PartDevice string
	// IsEncrypted indicates that PartDevice is encrypted.
	IsEncrypted bool
	// UnlockMethod is the method used to unlock the device. Valid values are
	// - NotUnlocked
	// - UnlockedWithRecoveryKey
	// - UnlockedWithSealedKey
	// - UnlockedWithKey
	UnlockMethod UnlockMethod
}

UnlockResult is the result of trying to unlock a volume.

func UnlockEncryptedVolumeUsingKey

func UnlockEncryptedVolumeUsingKey(disk disks.Disk, name string, key []byte) (UnlockResult, error)

UnlockEncryptedVolumeUsingKey unlocks an existing volume using the provided key.

func UnlockVolumeUsingSealedKeyIfEncrypted

func UnlockVolumeUsingSealedKeyIfEncrypted(disk disks.Disk, name string, sealedEncryptionKeyFile string, opts *UnlockVolumeUsingSealedKeyOptions) (UnlockResult, error)

UnlockVolumeUsingSealedKeyIfEncrypted verifies whether an encrypted volume with the specified name exists and unlocks it using a sealed key in a file with a corresponding name. The options control activation with the recovery key will be attempted if a prior activation attempt with the sealed key fails.

Note that if the function proceeds to the point where it knows definitely whether there is an encrypted device or not, IsEncrypted on the return value will be true, even if error is non-nil. This is so that callers can be robust and try unlocking using another method for example.

type UnlockVolumeUsingSealedKeyOptions

type UnlockVolumeUsingSealedKeyOptions struct {
	// AllowRecoveryKey when true indicates activation with the recovery key
	// will be attempted if activation with the sealed key failed.
	AllowRecoveryKey bool
	// WhichModel if invoked should return the device model
	// assertion for which the disk is being unlocked.
	WhichModel func() (*asserts.Model, error)
}

UnlockVolumeUsingSealedKeyOptions contains options for unlocking encrypted volumes using keys sealed to the TPM.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
t or T : Toggle theme light dark auto
y or Y : Canonical URL