Crypt keyslot context

Modules
	Crypt keyslot context types

Functions
void	crypt_keyslot_context_free (struct crypt_keyslot_context *kc)
int	crypt_keyslot_context_init_by_passphrase (struct crypt_device *cd, const char *passphrase, size_t passphrase_size, struct crypt_keyslot_context **kc)
int	crypt_keyslot_context_init_by_keyfile (struct crypt_device *cd, const char *keyfile, size_t keyfile_size, uint64_t keyfile_offset, struct crypt_keyslot_context **kc)
int	crypt_keyslot_context_init_by_token (struct crypt_device *cd, int token, const char *type, const char *pin, size_t pin_size, void *usrptr, struct crypt_keyslot_context **kc)
int	crypt_keyslot_context_init_by_volume_key (struct crypt_device *cd, const char *volume_key, size_t volume_key_size, struct crypt_keyslot_context **kc)
int	crypt_keyslot_context_init_by_signed_key (struct crypt_device *cd, const char *volume_key, size_t volume_key_size, const char *signature, size_t signature_size, struct crypt_keyslot_context **kc)
int	crypt_keyslot_context_init_by_keyring (struct crypt_device *cd, const char *key_description, struct crypt_keyslot_context **kc)
int	crypt_keyslot_context_init_by_vk_in_keyring (struct crypt_device *cd, const char *key_description, struct crypt_keyslot_context **kc)
int	crypt_keyslot_context_get_error (struct crypt_keyslot_context *kc)
int	crypt_keyslot_context_set_pin (struct crypt_device *cd, const char *pin, size_t pin_size, struct crypt_keyslot_context *kc)
int	crypt_keyslot_context_get_type (const struct crypt_keyslot_context *kc)

Detailed Description

Function Documentation

crypt_keyslot_context_free()

void crypt_keyslot_context_free

(

struct crypt_keyslot_context *

kc

)

Release crypt keyslot context and used memory.

Parameters

kc	crypt keyslot context

crypt_keyslot_context_get_error()

int crypt_keyslot_context_get_error

(

struct crypt_keyslot_context *

kc

)

Get error code per keyslot context from last failed call.

Note

If crypt_keyslot_add_by_keyslot_context passed with no negative return code. The return value of this function is undefined.

Parameters

kc	keyslot context involved in failed crypt_keyslot_add_by_keyslot_context

Returns

Negative errno if keyslot context caused a failure, zero otherwise.

crypt_keyslot_context_get_type()

int crypt_keyslot_context_get_type

(

const struct crypt_keyslot_context *

kc

)

Get type identifier for crypt keyslot context.

Parameters

kc	keyslot context

Returns

crypt keyslot context type id (see crypt-keyslot-context-types) or negative errno otherwise.

crypt_keyslot_context_init_by_keyfile()

int crypt_keyslot_context_init_by_keyfile	(	struct crypt_device *	cd,
		const char *	keyfile,
		size_t	keyfile_size,
		uint64_t	keyfile_offset,
		struct crypt_keyslot_context **	kc
	)

Initialize keyslot context via key file path.

Parameters

cd	crypt device handle initialized to LUKS device context
keyfile	key file with passphrase for a keyslot
keyfile_size	number of bytes to read from keyfile, 0 is unlimited
keyfile_offset	number of bytes to skip at start of keyfile
kc	returns crypt keyslot context handle type CRYPT_KC_TYPE_KEYFILE

Returns

zero on success or negative errno otherwise.

crypt_keyslot_context_init_by_keyring()

int crypt_keyslot_context_init_by_keyring	(	struct crypt_device *	cd,
		const char *	key_description,
		struct crypt_keyslot_context **	kc
	)

Initialize keyslot context via passphrase stored in a keyring.

Parameters

cd	crypt device handle initialized to LUKS device context
key_description	kernel keyring key description library should look for passphrase in
kc	returns crypt keyslot context handle type CRYPT_KC_TYPE_KEYRING

Returns

zero on success or negative errno otherwise.

crypt_keyslot_context_init_by_passphrase()

int crypt_keyslot_context_init_by_passphrase	(	struct crypt_device *	cd,
		const char *	passphrase,
		size_t	passphrase_size,
		struct crypt_keyslot_context **	kc
	)

Initialize keyslot context via passphrase.

Parameters

cd	crypt device handle initialized to LUKS device context
passphrase	passphrase for a keyslot
passphrase_size	size of passphrase
kc	returns crypt keyslot context handle type CRYPT_KC_TYPE_PASSPHRASE

Returns

zero on success or negative errno otherwise.

Note

The original buffer containing passphrase passed in parameters does not have to be valid after context initialization. The context contains copy of the original before freed with crypt_keyslot_context_free.

crypt_keyslot_context_init_by_signed_key()

int crypt_keyslot_context_init_by_signed_key	(	struct crypt_device *	cd,
		const char *	volume_key,
		size_t	volume_key_size,
		const char *	signature,
		size_t	signature_size,
		struct crypt_keyslot_context **	kc
	)

Initialize keyslot context via signed key.

Parameters

cd	crypt device handle initialized to device context
volume_key	provided volume key
volume_key_size	size of volume_key
signature	buffer with signature for the key
signature_size	bsize of signature buffer
kc	returns crypt keyslot context handle type CRYPT_KC_TYPE_SIGNED_KEY

Returns

zero on success or negative errno otherwise.

Note

currently supported only with VERITY devices.

crypt_keyslot_context_init_by_token()

int crypt_keyslot_context_init_by_token	(	struct crypt_device *	cd,
		int	token,
		const char *	type,
		const char *	pin,
		size_t	pin_size,
		void *	usrptr,
		struct crypt_keyslot_context **	kc
	)

Initialize keyslot context via LUKS2 token.

Parameters

cd	crypt device handle initialized to LUKS2 device context
token	token providing passphrase for a keyslot or CRYPT_ANY_TOKEN
type	restrict type of token, if NULL all types are allowed
pin	passphrase (or PIN) to unlock token (may be binary data)
pin_size	size of pin
usrptr	provided identification in callback
kc	returns crypt keyslot context handle type CRYPT_KC_TYPE_TOKEN

Returns

zero on success or negative errno otherwise.

crypt_keyslot_context_init_by_vk_in_keyring()

int crypt_keyslot_context_init_by_vk_in_keyring	(	struct crypt_device *	cd,
		const char *	key_description,
		struct crypt_keyslot_context **	kc
	)

Initialize keyslot context via volume key stored in a keyring.

Parameters

cd	crypt device handle initialized to LUKS device context
key_description	kernel keyring key description library should look for passphrase in. The key can be passed either as number in ASCII, or a text representation in the form "%<key_type>:<key_name>"
kc	returns crypt keyslot context handle type CRYPT_KC_TYPE_KEYRING

Returns

zero on success or negative errno otherwise.

crypt_keyslot_context_init_by_volume_key()

int crypt_keyslot_context_init_by_volume_key	(	struct crypt_device *	cd,
		const char *	volume_key,
		size_t	volume_key_size,
		struct crypt_keyslot_context **	kc
	)

Initialize keyslot context via key.

Parameters

cd	crypt device handle initialized to LUKS device context
volume_key	provided volume key or NULL if used after crypt_format or with CRYPT_VOLUME_KEY_NO_SEGMENT flag
volume_key_size	size of volume_key
kc	returns crypt keyslot context handle type CRYPT_KC_TYPE_KEY

Returns

zero on success or negative errno otherwise.

crypt_keyslot_context_set_pin()

int crypt_keyslot_context_set_pin	(	struct crypt_device *	cd,
		const char *	pin,
		size_t	pin_size,
		struct crypt_keyslot_context *	kc
	)

Set new pin to token based keyslot context.

Note

Use when crypt_keyslot_add_by_keyslot_context failed and token keyslot context returned -ENOANO error code via crypt_keyslot_context_get_error.

Parameters

cd	crypt device handle initialized to LUKS2 device context
pin	passphrase (or PIN) to unlock token (may be binary data)
pin_size	size of pin
kc	LUKS2 keyslot context (only CRYPT_KC_TYPE_TOKEN is allowed)

Returns

zero on success or negative errno otherwise