Kernel keyring manipulation

Functions
int	crypt_set_keyring_to_link (struct crypt_device *cd, const char *key_description, const char *old_key_description, const char *key_type_desc, const char *keyring_to_link_vk)

Detailed Description

Function Documentation

crypt_set_keyring_to_link()

int crypt_set_keyring_to_link	(	struct crypt_device *	cd,
		const char *	key_description,
		const char *	old_key_description,
		const char *	key_type_desc,
		const char *	keyring_to_link_vk
	)

Link the volume key to the specified kernel keyring.

The volume can have one or two keys. Normally, the device has one key. However if reencryption was started and not finished yet, the volume will have two volume keys (the new VK for the already reencrypted segment and old VK for the not yet reencrypted segment).

The old_key_description argument is required only for devices that are in re-encryption and have two volume keys at the same time (old and new). You can set the old_key_description to NULL, but if you supply number of keys less than required, the function will return -ESRCH. In that case you need to call the function again and set the missing key description. When supplying just one key description, make sure to supply it in the key_description.

Parameters

cd	crypt device handle
key_description	the key description of the volume key linked in desired keyring.
old_key_description	the key description of the old volume key linked in desired keyring (for devices in re-encryption).
key_type_desc	the key type used for the volume key. Currently only "user" and "logon" types are supported. if NULL is specified the default "user" type is applied.
keyring_to_link_vk	the keyring description of the keyring in which volume key should be linked, if NULL is specified, linking will be disabled.

Note

keyring_to_link_vk may be passed in various string formats: It can be kernel key numeric id of existing keyring written as a string, keyring name prefixed optionally be either "%:" or "%keyring:" substrings or keyctl special values for keyrings "@t", "@p", "@s" and so on. See keyctl(1) man page, section KEY IDENTIFIERS for more information. All other prefixes starting "%<type>:" are ignored.

key_description "%<type>:" prefixes are ignored. Type is applied based on key_type parameter value.