secboot

package
v0.0.0-...-bc60ea4 Latest Latest
Warning

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

 Go to latest Published: Dec 20, 2024 License: GPL-3.0 Imports: 32 Imported by: 70

Documentation

Index

Constants

View Source 
const (
	// Handles are in the block reserved for TPM owner objects (0x01800000 - 0x01bfffff).
	//
	// Handles are rotated during factory reset, depending on the PCR handle
	// thet was used when sealing key objects during installation (or a
	// previous factory reset).
	RunObjectPCRPolicyCounterHandle         = uint32(0x01880001)
	FallbackObjectPCRPolicyCounterHandle    = uint32(0x01880002)
	AltRunObjectPCRPolicyCounterHandle      = uint32(0x01880003)
	AltFallbackObjectPCRPolicyCounterHandle = uint32(0x01880004)
)

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 keys.EncryptionKey, rkey keys.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 CheckTPMKeySealingSupported 

func CheckTPMKeySealingSupported(mode TPMProvisionMode) error

func EncryptedPartitionName 

func EncryptedPartitionName(name string) string

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

func EnsureRecoveryKey 

func EnsureRecoveryKey(keyFile string, rkeyDevs []RecoveryKeyDevice) (keys.RecoveryKey, error)

EnsureRecoveryKey makes sure the encrypted block devices have a recovery key. It takes the path where to store the key and encrypted devices to operate on.

func FormatEncryptedDevice 

func FormatEncryptedDevice(key keys.EncryptionKey, encType EncryptionType, 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 MarkSuccessful 

func MarkSuccessful() error

MarkSuccessful marks the secure boot parts of the boot as successful.

This means that the dictionary attack (DA) lockout counter is reset.

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 PCRHandleOfSealedKey 

func PCRHandleOfSealedKey(p string) (uint32, error)

PCRHandleOfSealedKey retunrs the PCR handle which was used when sealing a given key object.

func ProvisionForCVM 

func ProvisionForCVM(initramfsUbuntuSeedDir string) error

ProvisionForCVM provisions the default TPM using a custom SRK template that is created by the encrypt tool prior to first boot of Azure CVM instances. It takes UbuntuSeedDir (ESP) and expects "tpm2-srk.tmpl" there which is deleted after successful provision.

Key differences with ProvisionTPM() - lack of TPM or if TPM is disabled is ignored. - it is fatal if TPM Provisioning requires a Lockout file - Custom SRK file is required in InitramfsUbuntuSeedDir

func ProvisionTPM 

func ProvisionTPM(mode TPMProvisionMode, lockoutAuthFile string) error

ProvisionTPM provisions the default TPM and saves the lockout authorization key to the specified file.

func ReleasePCRResourceHandles 

func ReleasePCRResourceHandles(handles ...uint32) error

ReleasePCRResourceHandles releases any TPM resources associated with given PCR handles.

func RemoveRecoveryKeys 

func RemoveRecoveryKeys(rkeyDevToKey map[RecoveryKeyDevice]string) error

RemoveRecoveryKeys removes any recovery key from all encrypted block devices. It takes a map from the recovery key device to where their recovery key is stored, mount points might share the latter.

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 seals the encryption keys according to the specified parameters. The TPM must have already been provisioned. If sealed key already exists at the PCR handle, 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 StageEncryptionKeyChange 

func StageEncryptionKeyChange(node string, key keys.EncryptionKey) error

StageEncryptionKeyChange stages a new encryption key for a given encrypted device. The new key is added into a temporary slot. To complete the encryption key change process, a call to TransitionEncryptionKeyChange is needed.

func TransitionEncryptionKeyChange 

func TransitionEncryptionKeyChange(mountpoint string, key keys.EncryptionKey) error

TransitionEncryptionKeyChange transitions the encryption key on an encrypted device corresponding to the given mount point. The change is authorized using the new key, thus a prior call to StageEncryptionKeyChange must be done.

func UnlockEncryptedVolumeWithRecoveryKey 

func UnlockEncryptedVolumeWithRecoveryKey(name, device string) error

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

Types

type EncryptionType 

type EncryptionType string

EncryptionType specifies what encryption backend should be used (if any) 

const (
	EncryptionTypeNone        EncryptionType = ""
	EncryptionTypeLUKS        EncryptionType = "cryptsetup"
	EncryptionTypeLUKSWithICE EncryptionType = "cryptsetup-with-inline-crypto-engine"
)

func (EncryptionType) IsLUKS 

func (et EncryptionType) IsLUKS() bool

TODO:ICE: all EncryptionTypes are LUKS based now so this could be removed?

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
	Classic() bool
	Grade() asserts.ModelGrade
	SignKeyID() string
}

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

type RecoveryKeyDevice 

type RecoveryKeyDevice struct {
	// Mountpoint of the device
	Mountpoint string
	// AuthorizingKeyFile is the path to the key to authorize the
	// operation, if empty, then it is assumed that the authorization key is
	// present in the user session keyring
	AuthorizingKeyFile 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 keys.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 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 keys.AuxKey
	// The path to the aux key file (if empty the key will not be
	// saved)
	AuxKeyFile string
}

type TPMProvisionMode 

type TPMProvisionMode int
const (
	TPMProvisionNone TPMProvisionMode = iota
	// TPMProvisionFull indicates a full provisioning of the TPM
	TPMProvisionFull
	// TPMPartialReprovision indicates a partial reprovisioning of the TPM
	// which was previously already provisioned by secboot. Existing lockout
	// authorization data from TPMLockoutAuthFile will be used to authorize
	// provisioning and will get overwritten in the process.
	TPMPartialReprovision
	// TPMProvisionFullWithoutLockout indicates full provisioning
	// without using lockout authorization data, as currently used
	// by Azure CVM
	TPMProvisionFullWithoutLockout
)

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.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.