keyring

Documentation

Overview

Package keyring manages adding, removing, and getting the status of encryption policy keys to/from the kernel. Most public functions are in keyring.go, and they delegate to either user_keyring.go or fs_keyring.go, depending on whether a user keyring or a filesystem keyring is being used.

v2 encryption policies always use the filesystem keyring. v1 policies use the user keyring by default, but can be configured to use the filesystem keyring instead (requires root and kernel v5.4+).

Index

• Constants
• Variables
• func AddEncryptionKey(key *crypto.Key, descriptor string, options *Options) error
• func IsFsKeyringSupported(mount *filesystem.Mount) bool
• func RemoveEncryptionKey(descriptor string, options *Options, allUsers bool) error
• func UserKeyringID(targetUser *user.User, checkSession bool) (int, error)
• type ErrAccessUserKeyring
  • func (err *ErrAccessUserKeyring) Error() string
• type ErrSessionUserKeyring
  • func (err *ErrSessionUserKeyring) Error() string
• type KeyStatus
  • func GetEncryptionKeyStatus(descriptor string, options *Options) (KeyStatus, error)
  • func (status KeyStatus) String() string
• type Options

Constants

const (
	KeyStatusUnknown = 0 + iota
	KeyAbsent
	KeyAbsentButFilesBusy
	KeyPresent
	KeyPresentButOnlyOtherUsers
)

The possible values of KeyStatus.

const KeyType = "logon"

KeyType is always logon as required by filesystem encryption.

Variables

var (
	ErrKeyAddedByOtherUsers  = errors.New("other users have added the key too")
	ErrKeyFilesOpen          = errors.New("some files using the key are still open")
	ErrKeyNotPresent         = errors.New("key not present or already removed")
	ErrV2PoliciesUnsupported = errors.New("kernel is too old to support v2 encryption policies")
)

Keyring error values

Functions

func AddEncryptionKey

func AddEncryptionKey(key *crypto.Key, descriptor string, options *Options) error

AddEncryptionKey adds an encryption policy key to a kernel keyring. It uses either the filesystem keyring for the target Mount or the user keyring for the target User.

func IsFsKeyringSupported

func IsFsKeyringSupported(mount *filesystem.Mount) bool

IsFsKeyringSupported returns true if the kernel supports the ioctls to add/remove fscrypt keys directly to/from the filesystem. For support to be detected, the given Mount must be for a filesystem that supports fscrypt.

func RemoveEncryptionKey

func RemoveEncryptionKey(descriptor string, options *Options, allUsers bool) error

RemoveEncryptionKey removes an encryption policy key from a kernel keyring. It uses either the filesystem keyring for the target Mount or the user keyring for the target User.

func UserKeyringID

func UserKeyringID(targetUser *user.User, checkSession bool) (int, error)

UserKeyringID returns the key id of the target user's user keyring. We also ensure that the keyring will be accessible by linking it into the thread keyring and linking it into the root user keyring (permissions allowing). If checkSession is true, an error is returned if a normal user requests their user keyring, but it is not in the current session keyring.

Types

type ErrAccessUserKeyring

type ErrAccessUserKeyring struct {
	TargetUser      *user.User
	UnderlyingError error
}

ErrAccessUserKeyring indicates that a user's keyring cannot be accessed.

func (*ErrAccessUserKeyring) Error

func (err *ErrAccessUserKeyring) Error() string

type ErrSessionUserKeyring

type ErrSessionUserKeyring struct {
	TargetUser *user.User
}

ErrSessionUserKeyring indicates that a user's keyring is not linked into the session keyring.

func (*ErrSessionUserKeyring) Error

func (err *ErrSessionUserKeyring) Error() string

type KeyStatus

type KeyStatus int

KeyStatus is an enum that represents the status of a key in a kernel keyring.

func GetEncryptionKeyStatus

func GetEncryptionKeyStatus(descriptor string, options *Options) (KeyStatus, error)

GetEncryptionKeyStatus gets the status of an encryption policy key in a kernel keyring. It uses either the filesystem keyring for the target Mount or the user keyring for the target User.

func (KeyStatus) String

func (status KeyStatus) String() string

type Options

type Options struct {
	// Mount is the filesystem to which the key should be
	// added/removed/gotten.
	Mount *filesystem.Mount
	// User is the user for whom the key should be added/removed/gotten.
	User *user.User
	// UseFsKeyringForV1Policies is true if keys for v1 encryption policies
	// should be put in the filesystem's keyring (if supported) rather than
	// in the user's keyring.  Note that this makes AddEncryptionKey and
	// RemoveEncryptionKey require root privileges.
	UseFsKeyringForV1Policies bool
}

Options are the options which specify *which* keyring the key should be added/removed/gotten to, and how.