.. _linux.h: **linux.h** linux-specific utility functions .. c: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 .. c:function:: 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. .. c:function:: 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. .. c:function:: 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. .. c:function:: 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. .. c:function:: 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. .. c:function:: 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. .. c:function:: 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. .. c:function:: 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. .. c:macro:: 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. .. c:function:: 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>0<1|2> ', otherwise it will be skipped during iteration. **Return** Number of keys for which **cb** was called, or negative error code .. c:function:: 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. .. c:function:: 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. .. c:function:: 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. .. c:function:: 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. .. c:function:: 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. .. c:function:: 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. .. c:function:: 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. .. c:function:: 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. .. c:function:: 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. .. c:function:: 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. .. c:function:: 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. .. c:function:: 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. .. c:function:: 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. .. c:function:: 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. .. c:function:: 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.