secboot

Documentation

Index

• Constants
• Variables
• func AddRecoveryKey(key EncryptionKey, rkey RecoveryKey, node string) error
• func CheckKeySealingSupported() error
• func EncryptedPartitionName(name string) string
• func FormatEncryptedDevice(key EncryptionKey, label, node string) error
• func LockSealedKeys() error
• func MeasureSnapModelWhenPossible(findModel func() (*asserts.Model, error)) error
• func MeasureSnapSystemEpochWhenPossible() error
• func ResealKeys(params *ResealKeysParams) error
• func SealKeys(keys []SealKeyRequest, params *SealKeysParams) error
• func UnlockEncryptedVolumeWithRecoveryKey(name, device string) error
• type EncryptionKey
  • func NewEncryptionKey() (EncryptionKey, error)
  • func (key EncryptionKey) Save(filename string) error
• type FDERevealKeyRequest
• type LoadChain
  • func NewLoadChain(bf bootloader.BootFile, next ...*LoadChain) *LoadChain
• type RecoveryKey
  • func NewRecoveryKey() (RecoveryKey, error)
  • func RecoveryKeyFromFile(recoveryKeyFile string) (*RecoveryKey, error)
  • func (key RecoveryKey) Save(filename string) error
  • func (k RecoveryKey) String() string
• type ResealKeysParams
• type SealKeyModelParams
• type SealKeyRequest
• type SealKeysParams
• type UnlockMethod
• type UnlockResult
  • func UnlockEncryptedVolumeUsingKey(disk disks.Disk, name string, key []byte) (UnlockResult, error)
  • func UnlockVolumeUsingSealedKeyIfEncrypted(disk disks.Disk, name string, sealedEncryptionKeyFile string, ...) (UnlockResult, error)
• type UnlockVolumeUsingSealedKeyOptions

Constants

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

Variables

var FDEHasRevealKey = func() bool { return false }

FDEHasReveal is setup by devicestate/fde to support device-specific full disk encryption implementations.

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.

func CheckKeySealingSupported

func CheckKeySealingSupported() 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 UnlockEncryptedVolumeWithRecoveryKey

func UnlockEncryptedVolumeWithRecoveryKey(name, device string) error

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

Types

type EncryptionKey

type EncryptionKey [encryptionKeySize]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 FDERevealKeyRequest

type FDERevealKeyRequest struct {
	Op string `json:"op"`

	SealedKey []byte `json:"sealed-key,omitempty"`
	KeyName   string `json:"key-name,omitempty"`
}

FDERevealKeyRequest carries the operation and parameters for the fde-reveal-key binary to support unsealing keys that were sealed with the "fde-setup" hook.

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 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 *asserts.Model
	// 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 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
}

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