From c662bc3e81d6cc7c9265ea9c58b8d1dbf66245ea Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 5 May 2024 13:06:50 +0200 Subject: Adding upstream version 1.9. Signed-off-by: Daniel Baumann --- doc/rst/linux.rst | 229 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 229 insertions(+) (limited to 'doc/rst/linux.rst') diff --git a/doc/rst/linux.rst b/doc/rst/linux.rst index 819ee68..cf49851 100644 --- a/doc/rst/linux.rst +++ b/doc/rst/linux.rst @@ -463,6 +463,127 @@ its keys are available for further key lookups. with errno set. +.. c:function:: unsigned char * nvme_read_key (long keyring_id, long key_id, int *len) + + Read key raw data + +**Parameters** + +``long keyring_id`` + Id of the keyring holding ``key_id`` + +``long key_id`` + Key id + +``int *len`` + Length of the returned data + +**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** + +Pointer to the payload on success, +or NULL with errno set otherwise. + + +.. c:function:: long nvme_update_key (long keyring_id, const char *key_type, const char *identity, unsigned char *key_data, int key_len) + + Update key raw data + +**Parameters** + +``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** + +**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** + +Key id of the new key or 0 with errno set otherwise. + + +.. c:macro:: nvme_scan_tls_keys_cb_t + + **Typedef**: Callback for iterating TLS keys + + +**Syntax** + + ``void nvme_scan_tls_keys_cb_t (long keyring, long key, char *desc, int desc_len, void *data)`` + +**Parameters** + +``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 nvme_scan_tls_keys (const char *keyring, nvme_scan_tls_keys_cb_t cb, void *data) + + Iterate over TLS keys in a keyring + +**Parameters** + +``const char *keyring`` + Keyring holding TLS keys + +``nvme_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 -1 with errno set +on error. + + .. c:function:: long nvme_insert_tls_key (const char *keyring, const char *key_type, const char *hostnqn, const char *subsysnqn, int hmac, unsigned char *configured_key, int key_len) Derive and insert TLS key @@ -578,3 +699,111 @@ The string containing the TLS identity. It is the responsibility of the caller to free the returned string. +.. c:function:: char * nvme_export_tls_key (const unsigned char *key_data, int key_len) + + Export a TLS key + +**Parameters** + +``const unsigned char *key_data`` + Raw data of the key + +``int key_len`` + Length of **key_data** + +**Description** + +Returns **key_data** in the PSK Interchange format as defined in section +3.6.1.5 of the NVMe TCP Transport specification. + +**Return** + +The string containing the TLS identity or NULL with errno set +on error. It is the responsibility of the caller to free the returned +string. + + +.. c:function:: unsigned char * nvme_import_tls_key (const char *encoded_key, int *key_len, unsigned int *hmac) + + Import a TLS key + +**Parameters** + +``const char *encoded_key`` + TLS key in PSK interchange format + +``int *key_len`` + Length of the resulting key data + +``unsigned int *hmac`` + HMAC algorithm + +**Description** + +Imports **key_data** in the PSK Interchange format as defined in section +3.6.1.5 of the NVMe TCP Transport specification. + +**Return** + +The raw data of the PSK or NULL with errno set on error. It is +the responsibility of the caller to free the returned string. + + +.. c:function:: int nvme_submit_passthru (int fd, unsigned long ioctl_cmd, struct nvme_passthru_cmd *cmd, __u32 *result) + + Low level ioctl wrapper for passthru commands + +**Parameters** + +``int fd`` + File descriptor of the nvme device + +``unsigned long ioctl_cmd`` + IOCTL command id + +``struct nvme_passthru_cmd *cmd`` + Passhtru command + +``__u32 *result`` + Optional field to return the result + +**Description** + +This is a low level library function which should not be used directly. It is +exposed as weak symbol so that the user application is able to provide their own +implementation of this function with additional debugging or logging code. + +**Return** + +The value from the ioctl system call (see ioctl documentation) + + +.. c:function:: int nvme_submit_passthru64 (int fd, unsigned long ioctl_cmd, struct nvme_passthru_cmd64 *cmd, __u64 *result) + + Low level ioctl wrapper for passthru commands + +**Parameters** + +``int fd`` + File descriptor of the nvme device + +``unsigned long ioctl_cmd`` + IOCTL command id + +``struct nvme_passthru_cmd64 *cmd`` + Passhtru command + +``__u64 *result`` + Optional field to return the result + +**Description** + +This is a low level library function which should not be used directly. It is +exposed as weak symbol so that the user application is able to provide their own +implementation of this function with additional debugging or logging code. + +**Return** + +The value from the ioctl system call (see ioctl documentation) + + -- cgit v1.2.3