libnvme

linux.h

linux-specific utility functions

enum libnvme_hmac_alg: HMAC algorithm

Constants

LIBNVME_HMAC_ALG_NONE: No HMAC algorithm
LIBNVME_HMAC_ALG_SHA2_256: SHA2-256
LIBNVME_HMAC_ALG_SHA2_384: SHA2-384
LIBNVME_HMAC_ALG_SHA2_512: SHA2-512

int libnvme_gen_dhchap_key(struct libnvme_global_ctx *ctx, char *hostnqn, enum libnvme_hmac_alg hmac, unsigned int key_len, unsigned char *secret, unsigned char *key): DH-HMAC-CHAP key generation

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object
char *hostnqn: Host NVMe Qualified Name
enum libnvme_hmac_alg hmac: HMAC algorithm
unsigned int key_len: Output key length
unsigned char *secret: Secret to used for digest
unsigned char *key: Generated DH-HMAC-CHAP key

Return

If key generation was successful the function returns 0 or a negative error code otherwise.

int libnvme_lookup_keyring(struct libnvme_global_ctx *ctx, const char *keyring, long *key): Lookup keyring serial number

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object
const char *keyring: Keyring name
long *key: Key serial number to return

Description

Looks up the serial number of the keyring keyring.

Return

0 on success, negative error code otherwise.

char *libnvme_describe_key_serial(struct libnvme_global_ctx *ctx, long key_id): Return key description

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object
long key_id: Key serial number

Description

Fetches the description of the key or keyring identified by the serial number key_id.

Return

The description of key_id or NULL on failure. The returned string needs to be freed by the caller.

int libnvme_lookup_key(struct libnvme_global_ctx *ctx, const char *type, const char *identity, long *key): Lookup key serial number

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object
const char *type: Key type
const char *identity: Key description
long *key: Key serial number to return

Description

Looks up the serial number of the key identity with type type in the current session keyring.

Return

0 on success, negative error code otherwise.

int libnvme_set_keyring(struct libnvme_global_ctx *ctx, long keyring_id): Link keyring for lookup

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object
long keyring_id: Keyring id

Description

Links keyring_id into the session keyring such that its keys are available for further key lookups.

Return

0 on success, negative error code otherwise.

int libnvme_create_raw_secret(struct libnvme_global_ctx *ctx, const char *secret, size_t key_len, unsigned char **raw_secret): Generate a raw secret buffer from input data

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object
const char *secret: Input secret data
size_t key_len: The length of the raw_secret in bytes
unsigned char **raw_secret: Return buffer with the generated raw secret

Description

Transforms the provided secret into a raw secret buffer suitable for use with NVMe key management operations.

The generated raw secret can subsequently be passed to libnvme_read_key() or libnvme_update_key().

Return

0 on success, negative error code otherwise.

int libnvme_read_key(struct libnvme_global_ctx *ctx, long keyring_id, long key_id, int *len, unsigned char **key): Read key raw data

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object
long keyring_id: Id of the keyring holding key_id
long key_id: Key id
int *len: Length of the returned data
unsigned char **key: Key serial to return

Description

Links the keyring specified by keyring_id into the session keyring and reads the payload of the key specified by key_id. len holds the size of the returned buffer. If keyring is 0 the default keyring ‘.nvme’ is used.

Return

0 on success, negative error code otherwise.

int libnvme_update_key(struct libnvme_global_ctx *ctx, long keyring_id, const char *key_type, const char *identity, unsigned char *key_data, int key_len, long *key): Update key raw data

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object
long keyring_id: Id of the keyring holding key_id
const char *key_type: Type of the key to insert
const char *identity: Key identity string
unsigned char *key_data: Raw data of the key
int key_len: Length of key_data
long *key: Key serial to return

Description

Links the keyring specified by keyring_id into the session keyring and updates the key reference by identity with key_data. The old key with identity identity will be revoked to make it inaccessible.

Return

0 on success, negative error code otherwise.

libnvme_scan_tls_keys_cb_t: Typedef: Callback for iterating TLS keys

Syntax

void libnvme_scan_tls_keys_cb_t (struct libnvme_global_ctx *ctx, long keyring, long key, char *desc, int desc_len, void *data)

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object
long keyring: Keyring which has been iterated
long key: Key for which the callback has been invoked
char *desc: Description of the key
int desc_len: Length of desc
void *data: Pointer for caller data

Description

Called for each TLS PSK in the keyring.

int libnvme_scan_tls_keys(struct libnvme_global_ctx *ctx, const char *keyring, libnvme_scan_tls_keys_cb_t cb, void *data): Iterate over TLS keys in a keyring

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object
const char *keyring: Keyring holding TLS keys
libnvme_scan_tls_keys_cb_t cb: Callback function
void *data: Pointer for data to be passed to cb

Description

Iterates keyring and call cb for each TLS key. When keyring is NULL the default ‘.nvme’ keyring is used. A TLS key must be of type ‘psk’ and the description must be of the form ‘NVMe<0|1><R|G>0<1|2> <identity>’, otherwise it will be skipped during iteration.

Return

Number of keys for which cb was called, or negative error code

int libnvme_insert_tls_key(struct libnvme_global_ctx *ctx, const char *keyring, const char *key_type, const char *hostnqn, const char *subsysnqn, int hmac, unsigned char *configured_key, int key_len, long *key): Derive and insert TLS key

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object
const char *keyring: Keyring to use
const char *key_type: Type of the resulting key
const char *hostnqn: Host NVMe Qualified Name
const char *subsysnqn: Subsystem NVMe Qualified Name
int hmac: HMAC algorithm
unsigned char *configured_key: Configured key data to derive the key from
int key_len: Length of configured_key
long *key: Key serial to return

Description

Derives a ‘retained’ TLS key as specified in NVMe TCP 1.0a and stores it as type key_type in the keyring specified by keyring.

Return

0 on success, negative error code otherwise.

int libnvme_insert_tls_key_versioned(struct libnvme_global_ctx *ctx, const char *keyring, const char *key_type, const char *hostnqn, const char *subsysnqn, int version, int hmac, unsigned char *configured_key, int key_len, long *key): Derive and insert TLS key

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object
const char *keyring: Keyring to use
const char *key_type: Type of the resulting key
const char *hostnqn: Host NVMe Qualified Name
const char *subsysnqn: Subsystem NVMe Qualified Name
int version: Key version to use
int hmac: HMAC algorithm
unsigned char *configured_key: Configured key data to derive the key from
int key_len: Length of configured_key
long *key: Key serial to return

Description

Derives a ‘retained’ TLS key as specified in NVMe TCP 1.0a (if version s set to ‘0’) or NVMe TP8028 (if version is set to ‘1) and stores it as type key_type in the keyring specified by keyring.

Return

0 on success, negative error code otherwise.

int libnvme_insert_tls_key_compat(struct libnvme_global_ctx *ctx, const char *keyring, const char *key_type, const char *hostnqn, const char *subsysnqn, int version, int hmac, unsigned char *configured_key, int key_len, long *key): Derive and insert TLS key

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object
const char *keyring: Keyring to use
const char *key_type: Type of the resulting key
const char *hostnqn: Host NVMe Qualified Name
const char *subsysnqn: Subsystem NVMe Qualified Name
int version: Key version to use
int hmac: HMAC algorithm
unsigned char *configured_key: Configured key data to derive the key from
int key_len: Length of configured_key
long *key: Key serial to return

Description

Derives a ‘retained’ TLS key as specified in NVMe TCP 1.0a (if version s set to ‘0’) or NVMe TP8028 (if version is set to ‘1) and stores it as type key_type in the keyring specified by keyring. This version differs from libnvme_insert_tls_key_versioned() in that it uses the original implementation for HKDF Expand-Label which does not prefix the ‘info’ and ‘label’ strings with the length.

Return

The key serial number if the key could be inserted into the keyring or 0 with errno otherwise.

int libnvme_generate_tls_key_identity(struct libnvme_global_ctx *ctx, const char *hostnqn, const char *subsysnqn, int version, int hmac, unsigned char *configured_key, int key_len, char **identity): Generate the TLS key identity

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object
const char *hostnqn: Host NVMe Qualified Name
const char *subsysnqn: Subsystem NVMe Qualified Name
int version: Key version to use
int hmac: HMAC algorithm
unsigned char *configured_key: Configured key data to derive the key from
int key_len: Length of configured_key
char **identity: TLS identity to return

Description

Derives a ‘retained’ TLS key as specified in NVMe TCP and generate the corresponding TLs identity.

It is the responsibility of the caller to free the returned string.

Return

0 on success, negative error code otherwise.

int libnvme_generate_tls_key_identity_compat(struct libnvme_global_ctx *ctx, const char *hostnqn, const char *subsysnqn, int version, int hmac, unsigned char *configured_key, int key_len, char **identity): Generate the TLS key identity

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object
const char *hostnqn: Host NVMe Qualified Name
const char *subsysnqn: Subsystem NVMe Qualified Name
int version: Key version to use
int hmac: HMAC algorithm
unsigned char *configured_key: Configured key data to derive the key from
int key_len: Length of configured_key
char **identity: TLS identity to return

Description

Derives a ‘retained’ TLS key as specified in NVMe TCP and generate the corresponding TLs identity. This version differs from libnvme_generate_tls_key_identity() in that it uses the original implementation for HKDF-Expand-Label which does not prefix the ‘info’ and ‘label’ string with the length.

It is the responsibility of the caller to free the returned string.

Return

0 on success, negative error code otherwise.

int libnvme_revoke_tls_key(struct libnvme_global_ctx *ctx, const char *keyring, const char *key_type, const char *identity): Revoke TLS key from keyring

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object
const char *keyring: Keyring to use
const char *key_type: Type of the key to revoke
const char *identity: Key identity string

Return

0 on success, negative error code otherwise.

int libnvme_export_tls_key(struct libnvme_global_ctx *ctx, const unsigned char *key_data, int key_len, char **identity): Export a TLS key

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object
const unsigned char *key_data: Raw data of the key
int key_len: Length of key_data
char **identity: TLS identity

Description

Returns key_data in the PSK Interchange format as defined in section 3.6.1.5 of the NVMe TCP Transport specification.

It is the responsibility of the caller to free the returned string.

Return

0 on success, negative error code otherwise.

int libnvme_export_tls_key_versioned(struct libnvme_global_ctx *ctx, unsigned char version, unsigned char hmac, const unsigned char *key_data, size_t key_len, char **identity): Export a TLS pre-shared key

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object
unsigned char version: Indicated the representation of the TLS PSK
unsigned char hmac: HMAC algorithm used to transfor the configured PSK in a retained PSK
const unsigned char *key_data: Raw data of the key
size_t key_len: Length of key_data
char **identity: TLS identity to return

Description

Returns key_data in the PSK Interchange format as defined in section 3.6.1.5 of the NVMe TCP Transport specification.

It is the responsibility of the caller to free the returned string.

Return

0 on success, negative error code otherwise.

int libnvme_import_tls_key(struct libnvme_global_ctx *ctx, const char *encoded_key, int *key_len, unsigned int *hmac, unsigned char **key): Import a TLS key

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object
const char *encoded_key: TLS key in PSK interchange format
int *key_len: Length of the resulting key data
unsigned int *hmac: HMAC algorithm
unsigned char **key: Key serial to return

Description

Imports key_data in the PSK Interchange format as defined in section 3.6.1.5 of the NVMe TCP Transport specification.

It is the responsibility of the caller to free the returned string.

Return

0 on success, negative error code otherwise.

int libnvme_import_tls_key_versioned(struct libnvme_global_ctx *ctx, const char *encoded_key, unsigned char *version, unsigned char *hmac, size_t *key_len, unsigned char **key): Import a TLS key

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object
const char *encoded_key: TLS key in PSK interchange format
unsigned char *version: Indicated the representation of the TLS PSK
unsigned char *hmac: HMAC algorithm used to transfor the configured PSK in a retained PSK
size_t *key_len: Length of the resulting key data
unsigned char **key: Key serial to return

Description

Imports key_data in the PSK Interchange format as defined in section 3.6.1.5 of the NVMe TCP Transport specification.

It is the responsibility of the caller to free the returned string.

Return

0 on success, negative error code otherwise.

char *libnvme_generate_hostnqn(void): Generate a machine specific host nqn

Parameters

void: no arguments

Return

An nvm namespace qualified name string based on the machine identifier, or NULL if not successful.

char *libnvme_generate_hostnqn_from_hostid(char *hostid): Generate a host nqn from host identifier

Parameters

char *hostid: Host identifier

Description

If hostid is NULL, the function generates it based on the machine identifier.

Return

On success, an NVMe Qualified Name for host identification. This name is based on the given host identifier. On failure, NULL.

char *libnvme_generate_hostid(void): Generate a machine specific host identifier

Parameters

void: no arguments

Return

On success, an identifier string based on the machine identifier to be used as NVMe Host Identifier, or NULL on failure.

char *libnvme_read_hostnqn(void): Reads the host nvm qualified name from the config default location

Parameters

void: no arguments

Description

Retrieve the qualified name from the config file located in $SYSCONFDIR/nvme. $SYSCONFDIR is usually /etc.

Return

The host nqn, or NULL if unsuccessful. If found, the caller is responsible to free the string.

char *libnvme_read_hostid(void): Reads the host identifier from the config default location

Parameters

void: no arguments

Description

Retrieve the host idenditifer from the config file located in $SYSCONFDIR/nvme/. $SYSCONFDIR is usually /etc.

Return

The host identifier, or NULL if unsuccessful. If found, the caller: is responsible to free the string.

libnvme

Navigation

Related Topics