secboot

package module
v0.0.6 Latest Latest
Warning

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

 Go to latest Published: Nov 11, 2022 License: GPL-3.0 Imports: 35 Imported by: 3

README

secboot

介绍

securely boot

软件架构

软件架构说明

安装教程
  1. xxxx
  2. xxxx
  3. xxxx
使用说明
  1. xxxx
  2. xxxx
  3. xxxx
参与贡献
  1. Fork 本仓库
  2. 新建 Feat_xxx 分支
  3. 提交代码
  4. 新建 Pull Request
特技
  1. 使用 Readme_XXX.md 来支持不同的语言，例如 Readme_en.md, Readme_zh.md
  2. Gitee 官方博客 blog.gitee.com
  3. 你可以 https://gitee.com/explore 这个地址来了解 Gitee 上的优秀开源项目
  4. GVP 全称是 Gitee 最有价值开源项目，是综合评定出的优秀开源项目
  5. Gitee 官方提供的使用手册 https://gitee.com/help
  6. Gitee 封面人物是一档用来展示 Gitee 会员风采的栏目 https://gitee.com/gitee-stars/

Documentation

Index

Constants

View Source 
const ClassicModelGradeMask uint32 = 0x80000000

ClassicModelGradeMask is ORed with the model grade code when measuring a classic snap model.

Variables

View Source 
var ErrInvalidPassphrase = errors.New("the supplied passphrase is incorrect")

ErrInvalidPassphrase is returned from KeyData methods that require knowledge of a passphrase is the supplied passphrase is incorrect.

View Source 
var ErrKernelKeyNotFound = errors.New("cannot find key in kernel keyring")
View Source 
var (
	// ErrMissingCryptsetupFeature is returned from some functions that make
	// use of the system's cryptsetup binary, if that binary is missing some
	// required features.
	ErrMissingCryptsetupFeature = luks2.ErrMissingCryptsetupFeature
)
View Source 
var ErrNoPlatformHandlerRegistered = errors.New("no appropriate platform handler is registered")

ErrNoPlatformHandlerRegistered is returned from KeyData methods if no appropriate platform handler is registered using the RegisterPlatformKeyDataHandler API.

View Source 
var ErrRecoveryKeyUsed = errors.New("cannot activate with platform protected keys but activation with the recovery key was successful")

ErrRecoveryKeyUsed is returned from ActivateVolumeWithKeyData and ActivateVolumeWithMultipleKeyData if the volume could not be activated with any platform protected keys but activation with the recovery key was successful.

Functions

func ActivateVolumeWithKey 

func ActivateVolumeWithKey(volumeName, sourceDevicePath string, key []byte, options *ActivateVolumeOptions) error

ActivateVolumeWithKey attempts to activate the LUKS encrypted volume at sourceDevicePath and create a mapping with the name volumeName, using the provided key. This makes use of systemd-cryptsetup.

func ActivateVolumeWithKeyData 

func ActivateVolumeWithKeyData(volumeName, sourceDevicePath string, key *KeyData, authRequestor AuthRequestor, kdf KDF, options *ActivateVolumeOptions) error

ActivateVolumeWithKeyData attempts to activate the LUKS encrypted container at sourceDevicePath and create a mapping with the name volumeName, using the supplied KeyData to recover the disk unlock key from the platform's secure device. This makes use of systemd-cryptsetup.

If activation with the supplied KeyData fails, this function will attempt to activate it with the fallback recovery key instead. The fallback recovery key is requested via the supplied authRequestor. If an AuthRequestor is not supplied, an error will be returned if the fallback recovery key is required. The RecoveryKeyTries field of options specifies how many attemps to request and use the recovery key will be made before failing. If it is set to 0, then no attempts will be made to request and use the fallback recovery key.

If either the PassphraseTries or RecoveryKeyTries fields of options are less than zero, an error will be returned. If the Model field of options is nil, an error will be returned.

If the fallback recovery key is used for successfully for activation, an ErrRecoveryKeyUsed error will be returned.

If activation fails, an error will be returned.

If activation with the supplied KeyData object succeeds (ie, no error is returned), then the supplied SnapModel is authorized to access the data on this volume.

func ActivateVolumeWithMultipleKeyData 

func ActivateVolumeWithMultipleKeyData(volumeName, sourceDevicePath string, keys []*KeyData, authRequestor AuthRequestor, kdf KDF, options *ActivateVolumeOptions) error

ActivateVolumeWithKeyData attempts to activate the LUKS encrypted container at sourceDevicePath and create a mapping with the name volumeName, using the supplied KeyData objects to recover the disk unlock key from the platform's secure device. This makes use of systemd-cryptsetup.

If activation with the supplied KeyData objects fails, this function will attempt to activate it with the fallback recovery key instead. The fallback recovery key is requested via the supplied authRequestor. If an AuthRequestor is not supplied, an error will be returned if the fallback recovery key is required. The RecoveryKeyTries field of options specifies how many attemps to request and use the recovery key will be made before failing. If it is set to 0, then no attempts will be made to request and use the fallback recovery key.

If either the PassphraseTries or RecoveryKeyTries fields of options are less than zero, an error will be returned. If the Model field of options is nil, an error will be returned.

If the fallback recovery key is used for successfully for activation, an ErrRecoveryKeyUsed error will be returned.

If activation fails, an error will be returned.

If activation with one of the supplied KeyData objects succeeds (ie, no error is returned), then the supplied SnapModel is authorized to access the data on this volume.

func ActivateVolumeWithRecoveryKey 

func ActivateVolumeWithRecoveryKey(volumeName, sourceDevicePath string, authRequestor AuthRequestor, options *ActivateVolumeOptions) error

ActivateVolumeWithRecoveryKey attempts to activate the LUKS encrypted volume at sourceDevicePath and create a mapping with the name volumeName, using the fallback recovery key. This makes use of systemd-cryptsetup.

The recovery key is requested via the supplied AuthRequestor. If an AuthRequestor is not supplied, an error will be returned. The RecoveryKeyTries field of options specifies how many attempts to request and use the recovery key will be made before failing.

If the RecoveryKeyTries field of options is less than zero, an error will be returned.

func AddLUKS2ContainerRecoveryKey 

func AddLUKS2ContainerRecoveryKey(devicePath, keyslotName string, existingKey DiskUnlockKey, recoveryKey RecoveryKey, options *KDFOptions) error

AddLUKS2ContainerRecoveryKey creates a fallback recovery keyslot with the specified name on the LUKS2 container at the specified path and uses it to protect the LUKS master key with the supplied recovery key. The keyslot can be used to unlock the container in scenarios where it cannot be unlocked using a platform protected key.

If the specified name is empty, the name "default-recovery" will be used.

The recovery key must be generated by a cryptographically strong random number source.

If a keyslot with the supplied name already exists, an error will be returned. The keyslot must first be deleted with DeleteLUKS2ContainerKey or renamed with RenameLUKS2ContainerKey.

In order to perform this action, an existing key must be supplied.

func AddLUKS2ContainerUnlockKey 

func AddLUKS2ContainerUnlockKey(devicePath, keyslotName string, existingKey, newKey DiskUnlockKey, options *KDFOptions) error

AddLUKS2ContainerUnlockKey creates a keyslot with the specified name on the LUKS2 container at the specified path, and uses it to protect the master key with the supplied key. The created keyslot is one that will normally be used for unlocking the specified LUKS2 container.

If the specified name is empty, the name "default" will be used.

The new key should be a cryptographically strong random number of at least 32-bytes.

If a keyslot with the supplied name already exists, an error will be returned. The keyslot must first be deleted with DeleteLUKS2ContainerKey or renamed with RenameLUKS2ContainerKey.

In order to perform this action, an existing key must be supplied.

The new key should be protected by some platform-specific mechanism in order to create a KeyData object. The KeyData object can be saved to the keyslot using LUKS2KeyDataWriter.

func DeactivateVolume 

func DeactivateVolume(volumeName string) error

DeactivateVolume attempts to deactivate the LUKS encrypted volumeName. This makes use of systemd-cryptsetup.

func DeleteLUKS2ContainerKey 

func DeleteLUKS2ContainerKey(devicePath, keyslotName string, existingKey DiskUnlockKey) error

DeleteLUKS2ContainerKey deletes the keyslot with the specified name from the LUKS2 container at the specified path. An existing key associated with a different keyslot must be supplied. This will return an error if the container only has a single keyslot remaining.

func InitializeLUKS2Container 

func InitializeLUKS2Container(devicePath, label string, key DiskUnlockKey, options *InitializeLUKS2ContainerOptions) error

InitializeLUKS2Container will initialize the partition at the specified devicePath as a new LUKS2 container. This can only be called on a partition that isn't mapped. The label for the new LUKS2 container is provided via the label argument.

The container will be configured to encrypt data with AES-256 and XTS block cipher mode.

The initial key used for unlocking the container is provided via the key argument, and must be a cryptographically secure random number of at least 32-bytes.

The initial keyslot will be created with the name specified in the InitialKeyslotName field of options. If this is empty, "default" will be used.

The initial key should be protected by some platform-specific mechanism in order to create a KeyData object. The KeyData object can be saved to the keyslot using LUKS2KeyDataWriter.

On failure, this will return an error containing the output of the cryptsetup command.

WARNING: This function is destructive. Calling this on an existing LUKS container will make the data contained inside of it irretrievable.

func ListLUKS2ContainerRecoveryKeyNames 

func ListLUKS2ContainerRecoveryKeyNames(devicePath string) ([]string, error)

ListLUKS2ContainerRecoveryKeyNames lists the names of keyslots on the specified LUKS2 container configured as recovery slots.

func ListLUKS2ContainerUnlockKeyNames 

func ListLUKS2ContainerUnlockKeyNames(devicePath string) ([]string, error)

ListLUKS2ContainerUnlockKeyNames lists the names of keyslots on the specified LUKS2 container configured as normal unlock slots (the keys associated with these should be protected by the platform's secure device).

func RegisterPlatformKeyDataHandler 

func RegisterPlatformKeyDataHandler(name string, handler PlatformKeyDataHandler)

RegisterPlatformKeyDataHandler registers a handler for the specified platform name.

func RenameLUKS2ContainerKey 

func RenameLUKS2ContainerKey(devicePath, oldName, newName string) error

RenameLUKS2Container key renames the keyslot with the specified oldName on the LUKS2 container at the specified path.

Types

type ActivateVolumeOptions 

type ActivateVolumeOptions struct {
	// PassphraseTries specifies the maximum number of times
	// that activation with a user passphrase should be attempted
	// before failing with an error and falling back to activating
	// with the recovery key (see RecoveryKeyTries).
	//
	// Setting this to zero disables activation with a user
	// passphrase - in this case, any protected keys that require
	// a passphrase are ignored and activation will fall back to
	// requesting a recovery key.
	//
	// For each passphrase attempt, the supplied passphrase is
	// tested against every protected key that requires a passphrase.
	//
	// The actual number of available passphrase attempts may be
	// limited by the platform to a number that is lower than this
	// value (eg, in the TPM case because of the current auth fail
	// counter value which means the dictionary attack protection
	// might be triggered first).
	//
	// It is ignored by ActivateVolumeWithRecoveryKey.
	PassphraseTries int

	// RecoveryKeyTries specifies the maximum number of times that
	// activation with the fallback recovery key should be
	// attempted.
	//
	// It is used directly by ActivateVolumeWithRecoveryKey and
	// indirectly with other methods upon failure, for example
	// in the case where no other keys can be recovered.
	//
	// Setting this to zero will disable attempts to activate with
	// the fallback recovery key.
	RecoveryKeyTries int

	// KeyringPrefix is the prefix used for the description of any
	// kernel keys created during activation.
	KeyringPrefix string

	// Model is the snap device model that will access the data
	// on the encrypted container. The ActivateVolumeWith* functions
	// will check that this model is authorized via the KeyData
	// binding before unlocking the encrypted container.
	//
	// The caller of the ActivateVolumeWith* API is responsible for
	// validating the associated model assertion and snaps.
	//
	// Set this to SkipSnapModelCheck to skip the check. It cannot
	// be left set as nil.
	//
	// It is ignored by ActivateVolumeWithRecoveryKey, and it is
	// ok to leave it set as nil in this case.
	Model SnapModel
}

ActivateVolumeOptions provides options to the ActivateVolumeWith* family of functions.

type AuthMode 

type AuthMode uint32

AuthMode corresponds to a set of authentication mechanisms. 

const (
	AuthModeNone       AuthMode = 0
	AuthModePassphrase AuthMode = 1 << iota
)

type AuthRequestor 

type AuthRequestor interface {
	// RequestPassphrase is used to request the passphrase for a platform
	// protected key that is being used to unlock the container at the
	// specified sourceDevicePath.
	RequestPassphrase(volumeName, sourceDevicePath string) (string, error)

	// RequestRecoveryKey is used to request the recovery key to unlock the
	// container at the specified sourceDevicePath.
	RequestRecoveryKey(volumeName, sourceDevicePath string) (RecoveryKey, error)
}

AuthRequestor is an interface for requesting credentials.

func NewSystemdAuthRequestor 

func NewSystemdAuthRequestor(passphraseTmpl, recoveryKeyTmpl string) (AuthRequestor, error)

NewSystemdAuthRequestor creates an implementation of AuthRequestor that delegates to the systemd-ask-password binary. The supplied templates are used to compose the messages that will be displayed when requesting a credential. The template will be executed with the following parameters: - .VolumeName: The name that the LUKS container will be mapped to. - .SourceDevicePath: The device path of the LUKS container.

type AuxiliaryKey 

type AuxiliaryKey []byte

AuxiliaryKey is an additional key used to modify properties of a KeyData object without having to create a new object.

func GetAuxiliaryKeyFromKernel 

func GetAuxiliaryKeyFromKernel(prefix, devicePath string, remove bool) (AuxiliaryKey, error)

GetAuxiliaryKeyFromKernel retrieves the auxiliary key associated with the KeyData that was used to unlock the encrypted container at the specified path. The value of prefix must match the prefix that was supplied via ActivateVolumeOptions during unlocking.

If remove is true, the key will be removed from the kernel keyring prior to returning.

If no key is found, a ErrKernelKeyNotFound error will be returned.

type DiskUnlockKey 

type DiskUnlockKey []byte

DiskUnlockKey is the key used to unlock a LUKS volume.

func GetDiskUnlockKeyFromKernel 

func GetDiskUnlockKeyFromKernel(prefix, devicePath string, remove bool) (DiskUnlockKey, error)

GetDiskUnlockKeyFromKernel retrieves the key that was used to unlock the encrypted container at the specified path. The value of prefix must match the prefix that was supplied via ActivateVolumeOptions during unlocking.

If remove is true, the key will be removed from the kernel keyring prior to returning.

If no key is found, a ErrKernelKeyNotFound error will be returned.

type FileKeyDataReader 

type FileKeyDataReader struct {
	*bytes.Reader
	// contains filtered or unexported fields
}

FileKeyDataReader provides a mechanism to read a KeyData from a file.

func NewFileKeyDataReader 

func NewFileKeyDataReader(path string) (*FileKeyDataReader, error)

NewFileKeyDataReader is used to read a file containing key data at the specified path.

func (*FileKeyDataReader) ReadableName 

func (r *FileKeyDataReader) ReadableName() string

type FileKeyDataWriter 

type FileKeyDataWriter struct {
	*bytes.Buffer
	// contains filtered or unexported fields
}

FileKeyDataWriter provides a mechanism to write a KeyData to a file.

func NewFileKeyDataWriter 

func NewFileKeyDataWriter(path string) *FileKeyDataWriter

NewFileKeyDataWriter creates a new FileKeyDataWriter for atomically writing a KeyData to a file.

func (*FileKeyDataWriter) Commit 

func (w *FileKeyDataWriter) Commit() error

type InitializeLUKS2ContainerOptions 

type InitializeLUKS2ContainerOptions struct {
	// MetadataKiBSize sets the size of the metadata area in KiB. This
	//
	// MetadataKiBSize sets the size of the metadata area in KiB. 4KiB of
	// this is used for the fixed-size binary header, with the remaining
	// space being used for the JSON area. Setting this to zero causes
	// the container to be initialized with the default metadata area size.
	// If set to a non zero value, it must be a power of 2 between 16KiB
	// and 4MiB.
	MetadataKiBSize int

	// KeyslotsAreaKiBSize sets the size of the binary keyslot area in KiB.
	// Setting this to zero causes the container to be initialized with
	// the default keyslots area size. If set to a non-zero value, the
	// value must be a multiple of 4KiB up to a maximum of 128MiB.
	KeyslotsAreaKiBSize int

	// KDFOptions sets the KDF options for the initial keyslot. If this
	// is nil then the default settings defined by this package are used
	// (4 iterations and a memory cost of 32KiB).
	KDFOptions *KDFOptions

	// InitialKeyslotName sets the name that will be used to identify
	// the initial keyslot. If this is empty, then the name will be
	// set to "default".
	InitialKeyslotName string
}

InitializeLUKS2ContainerOptions carries options for initializing LUKS2 containers.

type InvalidKeyDataError 

type InvalidKeyDataError struct {
	// contains filtered or unexported fields
}

InvalidKeyDataError is returned from KeyData methods if the key data is invalid in some way.

func (*InvalidKeyDataError) Error 

func (e *InvalidKeyDataError) Error() string

func (*InvalidKeyDataError) Unwrap 

func (e *InvalidKeyDataError) Unwrap() error

type KDF 

type KDF interface {
	// Derive derives a key of the specified length in bytes, from the supplied
	// passphrase and salt and using the supplied cost parameters.
	Derive(passphrase string, salt []byte, params *KDFCostParams, keyLen uint32) ([]byte, error)

	// Time measures the amount of time the KDF takes to execute with the
	// specified cost parameters and key length in bytes.
	Time(params *KDFCostParams, keyLen uint32) (time.Duration, error)
}

KDF is an interface to abstract use of the Argon2 KDF to make it possible to delegate execution to a short-lived utility process where required.

func Argon2iKDF 

func Argon2iKDF() KDF

Argon2iKDF returns the in-process Argon2i implementation of KDF. This shouldn't be used in long-lived system processes - these processes should instead provide their own KDF implementation which delegates to a short-lived utility process which will use the in-process implementation.

type KDFCostParams 

type KDFCostParams struct {
	// Time corresponds to the number of iterations of the algorithm
	// that the key derivation will use.
	Time uint32

	// MemoryKiB is the amount of memory in KiB that the key derivation
	// will use.
	MemoryKiB uint32

	// Threads is the number of parallel threads that will be used
	// for the key derivation.
	Threads uint8
}

KDFCostParams defines the cost parameters for key derivation using Argon2.

type KDFOptions 

type KDFOptions struct {
	// MemoryKiB specifies the maximum memory cost in KiB when ForceIterations
	// is zero. If ForceIterations is not zero, then this is used as the
	// memory cost.
	MemoryKiB int

	// TargetDuration specifies the target duration for the KDF which
	// is used to benchmark the time and memory cost parameters. If it
	// is zero then the default is used. If ForceIterations is not zero
	// then this field is ignored.
	TargetDuration time.Duration

	// ForceIterations can be used to turn off KDF benchmarking by
	// setting the time cost directly. If this is zero then the cost
	// parameters are benchmarked based on the value of TargetDuration.
	ForceIterations int

	// Parallel sets the maximum number of parallel threads for the
	// KDF (up to 4). This will be adjusted downwards based on the
	// actual number of CPUs.
	Parallel int
}

KDFOptions specifies parameters for the Argon2 KDF used by cryptsetup and for passphrase support.

type KeyCreationData 

type KeyCreationData struct {
	// Handle contains metadata required by the platform in order to recover
	// this key. It is opaque to this go package. It should be a value that can
	// be encoded to JSON using go's encoding/json package, which could be
	// something as simple as binary data stored in a byte slice or a more complex
	// JSON object, depending on the requirements of the implementation. A handle
	// already encoded to JSON can be supplied using the json.RawMessage type.
	Handle interface{}

	EncryptedPayload []byte // The encrypted payload
	PlatformName     string // Name of the platform that produced this data

	// AuxiliaryKey is a key used to authorize changes to the key data.
	// It must match the key protected inside PlatformKeyData.EncryptedPayload.
	AuxiliaryKey AuxiliaryKey

	// SnapModelAuthHash is the digest algorithm used for HMACs of Snap
	// device models, and also the digest algorithm used to produce the
	// key digest.
	SnapModelAuthHash crypto.Hash
}

KeyCreationData is the data required to create a new KeyData object. It should be produced by a platform implementation.

type KeyData 

type KeyData struct {
	// contains filtered or unexported fields
}

KeyData represents a disk unlock key and auxiliary key protected by a platform's secure device.

func NewKeyData 

func NewKeyData(creationData *KeyCreationData) (*KeyData, error)

NewKeyData creates a new KeyData object using the supplied KeyCreationData, which should be created by a platform-specific package, containing a payload encrypted by the platform's secure device and the associated handle required for subsequent recovery of the keys.

func ReadKeyData 

func ReadKeyData(r KeyDataReader) (*KeyData, error)

ReadKeyData reads the key data from the supplied KeyDataReader, returning a new KeyData object.

func (*KeyData) AuthMode 

func (d *KeyData) AuthMode() (out AuthMode)

AuthMode indicates the authentication mechanisms enabled for this key data.

func (*KeyData) ChangePassphrase 

func (d *KeyData) ChangePassphrase(oldPassphrase, newPassphrase string, kdfOptions *KDFOptions, kdf KDF) error

ChangePassphrase updates the passphrase used to recover the keys from this key data via the KeyData.RecoverKeysWithPassphraseAPI. This can only be called if a passhphrase has been set previously (KeyData.AuthMode returns AuthModePassphrase).

The current passphrase must be supplied via the oldPassphrase argument.

The kdfOptions argument configures the Argon2 KDF settings. The kdf argument provides the Argon2 KDF implementation that will be used - this should ultimately execute the implementation returned by the Argon2iKDF function, but the caller can choose to execute this in a short-lived utility process.

func (*KeyData) ClearPassphraseWithPassphrase 

func (d *KeyData) ClearPassphraseWithPassphrase(passphrase string, kdf KDF) error

ClearPassphraseWithPassphrase clears the passphrase from this key data so that the keys can be recovered via the KeyData.RecoverKeys API. This can only be called if a passhphrase has been set previously (KeyData.AuthMode returns AuthModePassphrase).

The current passphrase must be supplied.

The kdf argument provides the Argon2 KDF implementation that will be used - this should ultimately execute the implementation returned by the Argon2iKDF function, but the caller can choose to execute this in a short-lived utility process.

func (*KeyData) IsSnapModelAuthorized 

func (d *KeyData) IsSnapModelAuthorized(auxKey AuxiliaryKey, model SnapModel) (bool, error)

IsSnapModelAuthorized indicates whether the supplied Snap device model is trusted to access the data on the encrypted volume protected by this key data.

The supplied auxKey is obtained using one of the RecoverKeys* functions.

func (*KeyData) MarshalAndUpdatePlatformHandle 

func (d *KeyData) MarshalAndUpdatePlatformHandle(handle interface{}) error

MarshalAndUpdatePlatformHandle marshals the supplied platform handle to JSON and updates this KeyData object. The changes will need to persisted afterwards using WriteAtomic.

func (*KeyData) ReadableName 

func (d *KeyData) ReadableName() string

ReadableName returns a human-readable name for this key data, useful for including in errors.

func (*KeyData) RecoverKeys 

func (d *KeyData) RecoverKeys() (DiskUnlockKey, AuxiliaryKey, error)

RecoverKeys recovers the disk unlock key and auxiliary key associated with this key data from the platform's secure device, for key data that doesn't have any additional authentication modes enabled (AuthMode returns AuthModeNone).

If AuthMode returns anything other than AuthModeNone, then this will return an error.

If no platform handler has been registered for this key data, an ErrNoPlatformHandlerRegistered error will be returned.

If the keys cannot be recovered because the key data is invalid, a *InvalidKeyDataError error will be returned.

If the keys cannot be recovered because the platform's secure device is not properly initialized, a *PlatformUninitializedError error will be returned.

If the keys cannot be recovered because the platform's secure device is not available, a *PlatformDeviceUnavailableError error will be returned.

func (*KeyData) RecoverKeysWithPassphrase 

func (d *KeyData) RecoverKeysWithPassphrase(passphrase string, kdf KDF) (DiskUnlockKey, AuxiliaryKey, error)

func (*KeyData) SetAuthorizedSnapModels 

func (d *KeyData) SetAuthorizedSnapModels(auxKey AuxiliaryKey, models ...SnapModel) error

SetAuthorizedSnapModels marks the supplied Snap device models as trusted to access the data on the encrypted volume protected by this key data. This function replaces all previously trusted models.

This makes changes to the key data, which will need to persisted afterwards using WriteAtomic.

The supplied auxKey is obtained using one of the RecoverKeys* functions. If the supplied auxKey is incorrect, then an error will be returned.

func (*KeyData) SetPassphrase 

func (d *KeyData) SetPassphrase(passphrase string, kdfOptions *KDFOptions, kdf KDF) error

SetPassphrase sets a passphrase on this key data, which can be used to recover the keys via the KeyData.RecoverKeysWithPassphrase API. This can only be called when KeyData.AuthMode returns AuthModeNone. Once a passphrase has been set, the KeyData.RecoverKeys API can no longer be used.

The kdfOptions argument configures the Argon2 KDF settings. The kdf argument provides the Argon2 KDF implementation that will be used - this should ultimately execute the implementation returned by the Argon2iKDF function, but the caller can choose to execute this in a short-lived utility process.

func (*KeyData) UniqueID 

func (d *KeyData) UniqueID() (KeyID, error)

UniqueID returns the unique ID for this key data.

func (*KeyData) UnmarshalPlatformHandle 

func (d *KeyData) UnmarshalPlatformHandle(handle interface{}) error

UnmarshalPlatformHandle unmarshals the JSON platform handle payload into the supplied handle, which must be a non-nil pointer.

func (*KeyData) WriteAtomic 

func (d *KeyData) WriteAtomic(w KeyDataWriter) error

WriteAtomic saves this key data to the supplied KeyDataWriter.

type KeyDataReader 

type KeyDataReader interface {
	io.Reader
	ReadableName() string
}

KeyDataReader is an interface used to read and decode a KeyData from persistent storage.

type KeyDataWriter 

type KeyDataWriter interface {
	io.Writer
	Commit() error
}

KeyDataWriter is an interface used by KeyData to write the data to persistent storage in an atomic way.

type KeyID 

type KeyID []byte

KeyID is the unique ID for a KeyData object. It is used to facilitate the sharing of state between the early boot environment and OS runtime.

type KeyPayload 

type KeyPayload []byte

KeyPayload is the payload that should be encrypted by a platform's secure device.

func MarshalKeys 

func MarshalKeys(key DiskUnlockKey, auxKey AuxiliaryKey) KeyPayload

MarshalKeys serializes the supplied disk unlock key and auxiliary key in to a format that is ready to be encrypted by a platform's secure device.

func (KeyPayload) Unmarshal 

func (c KeyPayload) Unmarshal() (key DiskUnlockKey, auxKey AuxiliaryKey, err error)

Unmarshal obtains the keys from this payload.

type LUKS2KeyDataReader 

type LUKS2KeyDataReader struct {
	*bytes.Reader
	// contains filtered or unexported fields
}

LUKS2KeyDataReader provides a mechanism to read a KeyData from a LUKS2 token.

func NewLUKS2KeyDataReader 

func NewLUKS2KeyDataReader(devicePath, name string) (*LUKS2KeyDataReader, error)

NewLUKS2KeyDataReader is used to read a LUKS2 token containing key data with the specified name on the specified LUKS2 container.

func (*LUKS2KeyDataReader) KeyslotID 

func (r *LUKS2KeyDataReader) KeyslotID() int

KeyslotID indicates the keyslot ID associated with the token from which this KeyData is read.

func (*LUKS2KeyDataReader) Priority 

func (r *LUKS2KeyDataReader) Priority() int

Priority indicates the priority of the keyslot associated with the token from which this KeyData is read. The default priority is 0 with higher numbers indicating a higher priority.

func (*LUKS2KeyDataReader) ReadableName 

func (r *LUKS2KeyDataReader) ReadableName() string

type LUKS2KeyDataWriter 

type LUKS2KeyDataWriter struct {
	*bytes.Buffer
	// contains filtered or unexported fields
}

LUKS2KeyDataWriter provides a mechanism to write a KeyData to a LUKS2 token.

func NewLUKS2KeyDataWriter 

func NewLUKS2KeyDataWriter(devicePath, name string) (*LUKS2KeyDataWriter, error)

NewLUKS2KeyDataWriter creates a new LUKS2KeyDataWriter for atomically writing a KeyData to a LUKS2 token with the specicied name and priority on the specified LUKS2 container.

The container must already contain a token of the correct type with the supplied name. The initial token is bootstrapped by InitializeLUKS2Container or SetLUKS2ContainerUnlockKey.

func (*LUKS2KeyDataWriter) Commit 

func (w *LUKS2KeyDataWriter) Commit() error

func (*LUKS2KeyDataWriter) SetPriority 

func (w *LUKS2KeyDataWriter) SetPriority(priority int)

SetPriority sets the priority for the updated KeyData that is written using this writer. It must be called before Commit.

Zero is the default priority, with higher numbers indicating a higher priority. A negative priority indicates that the KeyData shouldn't be used for activation unless referred to explicitly.

type PlatformDeviceUnavailableError 

type PlatformDeviceUnavailableError struct {
	// contains filtered or unexported fields
}

PlatformDeviceUnavailableError is returned from KeyData methods if the platform's secure device is currently unavailable.

func (*PlatformDeviceUnavailableError) Error 

func (e *PlatformDeviceUnavailableError) Error() string

func (*PlatformDeviceUnavailableError) Unwrap 

func (e *PlatformDeviceUnavailableError) Unwrap() error

type PlatformHandlerError 

type PlatformHandlerError struct {
	Type PlatformHandlerErrorType // type of the error
	Err  error                    // underlying error
}

PlatformHandlerError is returned from a PlatformKeyDataHandler implementation when the type of error can be categorized as one of the types supported by PlatformHandlerErrorType.

func (*PlatformHandlerError) Error 

func (e *PlatformHandlerError) Error() string

func (*PlatformHandlerError) Unwrap 

func (e *PlatformHandlerError) Unwrap() error

type PlatformHandlerErrorType 

type PlatformHandlerErrorType int

PlatformHandlerErrorType indicates the type of error that PlatformHandlerError is associated with. 

const (
	// PlatformHandlerErrorInvalidData indicates that an action could not be
	// performed by PlatformKeyDataHandler because the supplied key data is
	// invalid.
	PlatformHandlerErrorInvalidData PlatformHandlerErrorType = iota + 1

	// PlatformHandlerErrorUninitialized indicates that an action could not
	// be performed by PlatformKeyDataHandler because the platform's secure
	// device is not properly initialized.
	PlatformHandlerErrorUninitialized

	// PlatformHandlerErrorUnavailable indicates that an action could not be
	// be performed by PlatformKeyDataHandler because the platform's secure
	// device is unavailable.
	PlatformHandlerErrorUnavailable

	// PlatformHandlerErrorInvalidAuthKey indicates that an action could not
	// be performed by PlatformKeyDataHandler because the supplied
	// authorization key was incorrect.
	PlatformHandlerErrorInvalidAuthKey
)

type PlatformKeyData 

type PlatformKeyData struct {
	EncodedHandle    []byte // The JSON encoded platform handle
	EncryptedPayload []byte // The encrypted payload
}

PlatformKeyData represents the data exchanged between this package and platform implementations via the PlatformKeyDataHandler.

type PlatformKeyDataHandler 

type PlatformKeyDataHandler interface {
	// RecoverKeys attempts to recover the cleartext keys from the supplied key
	// data using this platform's secure device.
	RecoverKeys(data *PlatformKeyData) (KeyPayload, error)

	// RecoverKeysWithAuthKey attempts to recover the cleartext keys from the
	// supplied data using this platform's secure device. The key parameter
	// is a passphrase derived key to enable passphrase support to be integrated
	// with the secure device. The platform implementation doesn't provide the primary
	// mechanism of protecting keys with a passphrase - this is done in the platform
	// agnostic API. Some devices (such as TPMs) support this integration natively. For
	// other devices, the integration should provide a way of validating the key in
	// a way that requires the use of the secure device (eg, such as computing a HMAC of
	// it using a hardware backed key).
	RecoverKeysWithAuthKey(data *PlatformKeyData, key []byte) (KeyPayload, error)

	// ChangeAuthKey is called to notify the platform implementation that the
	// passphrase is being changed. The old and new parameters are passphrase derived
	// keys. Either value can be nil if passphrase authentication is being enabled (
	// where old will be nil) or disabled (where new will be nil).
	//
	// On success, it should return an updated handle.
	ChangeAuthKey(handle, old, new []byte) ([]byte, error)
}

PlatormKeyDataHandler is the interface that this go package uses to interact with a platform's secure device for the purpose of recovering keys.

type PlatformUninitializedError 

type PlatformUninitializedError struct {
	// contains filtered or unexported fields
}

PlatformUninitializedError is returned from KeyData methods if the platform's secure device has not been initialized properly.

func (*PlatformUninitializedError) Error 

func (e *PlatformUninitializedError) Error() string

func (*PlatformUninitializedError) Unwrap 

func (e *PlatformUninitializedError) Unwrap() error

type RecoveryKey 

type RecoveryKey [16]byte

RecoveryKey corresponds to a 16-byte recovery key in its binary form.

func ParseRecoveryKey 

func ParseRecoveryKey(s string) (out RecoveryKey, err error)

ParseRecoveryKey interprets the supplied string and returns the corresponding RecoveryKey. The recovery key is a 16-byte number, and the formatted version of this is represented as 8 5-digit zero-extended base-10 numbers (each with a range of 00000-65535) which may be separated by an optional '-', eg:

"61665-00531-54469-09783-47273-19035-40077-28287"

The formatted version of the recovery key is designed to be able to be inputted on a numeric keypad.

func (RecoveryKey) String 

func (k RecoveryKey) String() string

type SnapModel 

type SnapModel interface {
	Series() string
	BrandID() string
	Model() string
	Classic() bool
	Grade() asserts.ModelGrade
	SignKeyID() string
}

SnapModel exposes the details of a snap device model that are bound to an encrypted container. 

var SkipSnapModelCheck SnapModel = nullSnapModel{}

SkipSnapModelCheck provides a mechanism to skip the snap device model check when calling one of the ActivateVolumeWith* functions.

Source Files

View all Source files

Directories

Path Synopsis
internal
argon2
compattest
keyring
luks2
luks2/luks2test
luksview
paths
paths/pathstest
pe1.14
Package pe implements access to PE (Microsoft Windows Portable Executable) files.
 Package pe implements access to PE (Microsoft Windows Portable Executable) files.
tcg
tcti
testutil
tpm2test
truststore
tools
gen-certdata
gen-compattest-data
make-efi-testdata

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.