Documentation
¶
Index ¶
- Constants
- Variables
- func AddRecoveryKey(key EncryptionKey, rkey RecoveryKey, node string) error
- func CheckTPMKeySealingSupported() 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 SealKeysWithFDESetupHook(runHook fde.RunSetupHookFunc, keys []SealKeyRequest, ...) error
- func UnlockEncryptedVolumeWithRecoveryKey(name, device string) error
- type AuxKey
- type EncryptionKey
- type LoadChain
- type ModelForSealing
- type RecoveryKey
- type ResealKeysParams
- type SealKeyModelParams
- type SealKeyRequest
- type SealKeysParams
- type SealKeysWithFDESetupHookParams
- type UnlockMethod
- type UnlockResult
- type UnlockVolumeUsingSealedKeyOptions
Constants ¶
const ( // Handles are in the block reserved for TPM owner objects (0x01800000 - 0x01bfffff) RunObjectPCRPolicyCounterHandle = 0x01880001 FallbackObjectPCRPolicyCounterHandle = 0x01880002 )
Variables ¶
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 ¶
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 ¶
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 ¶
UnlockEncryptedVolumeWithRecoveryKey prompts for the recovery key and uses it to open an encrypted device.
Types ¶
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 ¶
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.
Source Files