| 1 |
// SPDX-License-Identifier: LGPL-2.1-or-later |
| 2 |
/* |
| 3 |
* This file is part of libnvme. |
| 4 |
* Copyright (c) 2020 Western Digital Corporation or its affiliates. |
| 5 |
* |
| 6 |
* Authors: Keith Busch <[email protected]> |
| 7 |
* Chaitanya Kulkarni <[email protected]> |
| 8 |
*/ |
| 9 |
#ifndef _LIBNVME_LINUX_H |
| 10 |
#define _LIBNVME_LINUX_H |
| 11 |
|
| 12 |
#include <stddef.h> |
| 13 |
|
| 14 |
#include <nvme/ioctl.h> |
| 15 |
#include <nvme/types.h> |
| 16 |
|
| 17 |
/** |
| 18 |
* DOC: linux.h |
| 19 |
* |
| 20 |
* linux-specific utility functions |
| 21 |
*/ |
| 22 |
|
| 23 |
/** |
| 24 |
* nvme_fw_download_seq() - Firmware download sequence |
| 25 |
* @fd: File descriptor of nvme device |
| 26 |
* @size: Total size of the firmware image to transfer |
| 27 |
* @xfer: Maximum size to send with each partial transfer |
| 28 |
* @offset: Starting offset to send with this firmware download |
| 29 |
* @buf: Address of buffer containing all or part of the firmware image. |
| 30 |
* |
| 31 |
* Return: The nvme command status if a response was received (see |
| 32 |
* &enum nvme_status_field) or -1 with errno set otherwise. |
| 33 |
*/ |
| 34 |
int nvme_fw_download_seq(int fd, __u32 size, __u32 xfer, __u32 offset, |
| 35 |
void *buf); |
| 36 |
|
| 37 |
/** |
| 38 |
* nvme_set_etdas() - Set the Extended Telemetry Data Area 4 Supported bit |
| 39 |
* @fd: File descriptor of nvme device |
| 40 |
* @changed: boolean to indicate whether or not the host |
| 41 |
* behavior support feature had been changed |
| 42 |
* |
| 43 |
* Return: The nvme command status if a response was received (see |
| 44 |
* &enum nvme_status_field) or -1 with errno set otherwise. |
| 45 |
*/ |
| 46 |
int nvme_set_etdas(int fd, bool *changed); |
| 47 |
|
| 48 |
/** |
| 49 |
* nvme_clear_etdas() - Clear the Extended Telemetry Data Area 4 Supported bit |
| 50 |
* @fd: File descriptor of nvme device |
| 51 |
* @changed: boolean to indicate whether or not the host |
| 52 |
* behavior support feature had been changed |
| 53 |
* |
| 54 |
* Return: The nvme command status if a response was received (see |
| 55 |
* &enum nvme_status_field) or -1 with errno set otherwise. |
| 56 |
*/ |
| 57 |
int nvme_clear_etdas(int fd, bool *changed); |
| 58 |
|
| 59 |
/** |
| 60 |
* nvme_get_uuid_list - Returns the uuid list (if supported) |
| 61 |
* @fd: File descriptor of nvme device |
| 62 |
* @uuid_list: UUID list returned by identify UUID |
| 63 |
* |
| 64 |
* Return: The nvme command status if a response was received (see |
| 65 |
* &enum nvme_status_field) or -1 with errno set otherwise. |
| 66 |
*/ |
| 67 |
int nvme_get_uuid_list(int fd, |
| 68 |
struct nvme_id_uuid_list *uuid_list); |
| 69 |
|
| 70 |
/** |
| 71 |
* nvme_get_telemetry_max() - Get telemetry limits |
| 72 |
* @fd: File descriptor of nvme device |
| 73 |
* @da: On success return max supported data area |
| 74 |
* @max_data_tx: On success set to max transfer chunk supported by the controller |
| 75 |
* |
| 76 |
* Return: The nvme command status if a response was received (see |
| 77 |
* &enum nvme_status_field) or -1 with errno set otherwise. |
| 78 |
*/ |
| 79 |
int nvme_get_telemetry_max(int fd, enum nvme_telemetry_da *da, size_t *max_data_tx); |
| 80 |
|
| 81 |
/** |
| 82 |
* nvme_get_telemetry_log() - Get specified telemetry log |
| 83 |
* @fd: File descriptor of nvme device |
| 84 |
* @create: Generate new host initated telemetry capture |
| 85 |
* @ctrl: Get controller Initiated log |
| 86 |
* @rae: Retain asynchronous events |
| 87 |
* @max_data_tx: Set the max data transfer size to be used retrieving telemetry. |
| 88 |
* @da: Log page data area, valid values: &enum nvme_telemetry_da. |
| 89 |
* @log: On success, set to the value of the allocated and retrieved log. |
| 90 |
* @size: Ptr to the telemetry log size, so it can be returned |
| 91 |
* |
| 92 |
* The total size allocated can be calculated as: |
| 93 |
* (nvme_telemetry_log da size + 1) * NVME_LOG_TELEM_BLOCK_SIZE. |
| 94 |
* |
| 95 |
* Return: The nvme command status if a response was received (see |
| 96 |
* &enum nvme_status_field) or -1 with errno set otherwise. |
| 97 |
*/ |
| 98 |
int nvme_get_telemetry_log(int fd, bool create, bool ctrl, bool rae, size_t max_data_tx, |
| 99 |
enum nvme_telemetry_da da, struct nvme_telemetry_log **log, |
| 100 |
size_t *size); |
| 101 |
/** |
| 102 |
* nvme_get_ctrl_telemetry() - Get controller telemetry log |
| 103 |
* @fd: File descriptor of nvme device |
| 104 |
* @rae: Retain asynchronous events |
| 105 |
* @log: On success, set to the value of the allocated and retrieved log. |
| 106 |
* @da: Log page data area, valid values: &enum nvme_telemetry_da |
| 107 |
* @size: Ptr to the telemetry log size, so it can be returned |
| 108 |
* |
| 109 |
* The total size allocated can be calculated as: |
| 110 |
* (nvme_telemetry_log da size + 1) * NVME_LOG_TELEM_BLOCK_SIZE. |
| 111 |
* |
| 112 |
* Return: The nvme command status if a response was received (see |
| 113 |
* &enum nvme_status_field) or -1 with errno set otherwise. |
| 114 |
*/ |
| 115 |
int nvme_get_ctrl_telemetry(int fd, bool rae, struct nvme_telemetry_log **log, |
| 116 |
enum nvme_telemetry_da da, size_t *size); |
| 117 |
|
| 118 |
/** |
| 119 |
* nvme_get_host_telemetry() - Get host telemetry log |
| 120 |
* @fd: File descriptor of nvme device |
| 121 |
* @log: On success, set to the value of the allocated and retrieved log. |
| 122 |
* @da: Log page data area, valid values: &enum nvme_telemetry_da |
| 123 |
* @size: Ptr to the telemetry log size, so it can be returned |
| 124 |
* |
| 125 |
* The total size allocated can be calculated as: |
| 126 |
* (nvme_telemetry_log da size + 1) * NVME_LOG_TELEM_BLOCK_SIZE. |
| 127 |
* |
| 128 |
* Return: The nvme command status if a response was received (see |
| 129 |
* &enum nvme_status_field) or -1 with errno set otherwise. |
| 130 |
*/ |
| 131 |
int nvme_get_host_telemetry(int fd, struct nvme_telemetry_log **log, |
| 132 |
enum nvme_telemetry_da da, size_t *size); |
| 133 |
|
| 134 |
/** |
| 135 |
* nvme_get_new_host_telemetry() - Get new host telemetry log |
| 136 |
* @fd: File descriptor of nvme device |
| 137 |
* @log: On success, set to the value of the allocated and retrieved log. |
| 138 |
* @da: Log page data area, valid values: &enum nvme_telemetry_da |
| 139 |
* @size: Ptr to the telemetry log size, so it can be returned |
| 140 |
* |
| 141 |
* The total size allocated can be calculated as: |
| 142 |
* (nvme_telemetry_log da size + 1) * NVME_LOG_TELEM_BLOCK_SIZE. |
| 143 |
* |
| 144 |
* Return: The nvme command status if a response was received (see |
| 145 |
* &enum nvme_status_field) or -1 with errno set otherwise. |
| 146 |
*/ |
| 147 |
int nvme_get_new_host_telemetry(int fd, struct nvme_telemetry_log **log, |
| 148 |
enum nvme_telemetry_da da, size_t *size); |
| 149 |
|
| 150 |
/** |
| 151 |
* nvme_get_ana_log_len_from_id_ctrl() - Retrieve maximum possible ANA log size |
| 152 |
* @id_ctrl: Controller identify data |
| 153 |
* @rgo: If true, return maximum log page size without NSIDs |
| 154 |
* |
| 155 |
* Return: A byte limit on the size of the controller's ANA log page |
| 156 |
*/ |
| 157 |
size_t nvme_get_ana_log_len_from_id_ctrl(const struct nvme_id_ctrl *id_ctrl, |
| 158 |
bool rgo); |
| 159 |
|
| 160 |
/** |
| 161 |
* nvme_get_ana_log_len() - Retrieve size of the current ANA log |
| 162 |
* @fd: File descriptor of nvme device |
| 163 |
* @analen: Pointer to where the length will be set on success |
| 164 |
* |
| 165 |
* Return: The nvme command status if a response was received (see |
| 166 |
* &enum nvme_status_field) or -1 with errno set otherwise. |
| 167 |
*/ |
| 168 |
int nvme_get_ana_log_len(int fd, size_t *analen); |
| 169 |
|
| 170 |
/** |
| 171 |
* nvme_get_logical_block_size() - Retrieve block size |
| 172 |
* @fd: File descriptor of nvme device |
| 173 |
* @nsid: Namespace id |
| 174 |
* @blksize: Pointer to where the block size will be set on success |
| 175 |
* |
| 176 |
* Return: The nvme command status if a response was received (see |
| 177 |
* &enum nvme_status_field) or -1 with errno set otherwise. |
| 178 |
*/ |
| 179 |
int nvme_get_logical_block_size(int fd, __u32 nsid, int *blksize); |
| 180 |
|
| 181 |
/** |
| 182 |
* nvme_get_lba_status_log() - Retrieve the LBA Status log page |
| 183 |
* @fd: File descriptor of the nvme device |
| 184 |
* @rae: Retain asynchronous events |
| 185 |
* @log: On success, set to the value of the allocated and retrieved log. |
| 186 |
* |
| 187 |
* Return: The nvme command status if a response was received (see |
| 188 |
* &enum nvme_status_field) or -1 with errno set otherwise. |
| 189 |
*/ |
| 190 |
int nvme_get_lba_status_log(int fd, bool rae, struct nvme_lba_status_log **log); |
| 191 |
|
| 192 |
/** |
| 193 |
* nvme_namespace_attach_ctrls() - Attach namespace to controller(s) |
| 194 |
* @fd: File descriptor of nvme device |
| 195 |
* @nsid: Namespace ID to attach |
| 196 |
* @num_ctrls: Number of controllers in ctrlist |
| 197 |
* @ctrlist: List of controller IDs to perform the attach action |
| 198 |
* |
| 199 |
* Return: The nvme command status if a response was received (see |
| 200 |
* &enum nvme_status_field) or -1 with errno set otherwise. |
| 201 |
*/ |
| 202 |
int nvme_namespace_attach_ctrls(int fd, __u32 nsid, __u16 num_ctrls, __u16 *ctrlist); |
| 203 |
|
| 204 |
/** |
| 205 |
* nvme_namespace_detach_ctrls() - Detach namespace from controller(s) |
| 206 |
* @fd: File descriptor of nvme device |
| 207 |
* @nsid: Namespace ID to detach |
| 208 |
* @num_ctrls: Number of controllers in ctrlist |
| 209 |
* @ctrlist: List of controller IDs to perform the detach action |
| 210 |
* |
| 211 |
* Return: The nvme command status if a response was received (see |
| 212 |
* &enum nvme_status_field) or -1 with errno set otherwise. |
| 213 |
*/ |
| 214 |
int nvme_namespace_detach_ctrls(int fd, __u32 nsid, __u16 num_ctrls, __u16 *ctrlist); |
| 215 |
|
| 216 |
/** |
| 217 |
* nvme_open() - Open an nvme controller or namespace device |
| 218 |
* @name: The basename of the device to open |
| 219 |
* |
| 220 |
* This will look for the handle in /dev/ and validate the name and filetype |
| 221 |
* match linux conventions. |
| 222 |
* |
| 223 |
* Return: A file descriptor for the device on a successful open, or -1 with |
| 224 |
* errno set otherwise. |
| 225 |
*/ |
| 226 |
int nvme_open(const char *name); |
| 227 |
|
| 228 |
/** |
| 229 |
* enum nvme_hmac_alg - HMAC algorithm |
| 230 |
* @NVME_HMAC_ALG_NONE: No HMAC algorithm |
| 231 |
* @NVME_HMAC_ALG_SHA2_256: SHA2-256 |
| 232 |
* @NVME_HMAC_ALG_SHA2_384: SHA2-384 |
| 233 |
* @NVME_HMAC_ALG_SHA2_512: SHA2-512 |
| 234 |
*/ |
| 235 |
enum nvme_hmac_alg { |
| 236 |
NVME_HMAC_ALG_NONE = 0, |
| 237 |
NVME_HMAC_ALG_SHA2_256 = 1, |
| 238 |
NVME_HMAC_ALG_SHA2_384 = 2, |
| 239 |
NVME_HMAC_ALG_SHA2_512 = 3, |
| 240 |
}; |
| 241 |
|
| 242 |
/** |
| 243 |
* nvme_gen_dhchap_key() - DH-HMAC-CHAP key generation |
| 244 |
* @hostnqn: Host NVMe Qualified Name |
| 245 |
* @hmac: HMAC algorithm |
| 246 |
* @key_len: Output key length |
| 247 |
* @secret: Secret to used for digest |
| 248 |
* @key: Generated DH-HMAC-CHAP key |
| 249 |
* |
| 250 |
* Return: If key generation was successful the function returns 0 or |
| 251 |
* -1 with errno set otherwise. |
| 252 |
*/ |
| 253 |
int nvme_gen_dhchap_key(char *hostnqn, enum nvme_hmac_alg hmac, |
| 254 |
unsigned int key_len, unsigned char *secret, |
| 255 |
unsigned char *key); |
| 256 |
|
| 257 |
/** |
| 258 |
* nvme_lookup_keyring() - Lookup keyring serial number |
| 259 |
* @keyring: Keyring name |
| 260 |
* |
| 261 |
* Looks up the serial number of the keyring @keyring. |
| 262 |
* |
| 263 |
* Return: The key serial number of the keyring |
| 264 |
* or 0 with errno set otherwise. |
| 265 |
*/ |
| 266 |
long nvme_lookup_keyring(const char *keyring); |
| 267 |
|
| 268 |
/** |
| 269 |
* nvme_describe_key_serial() - Return key description |
| 270 |
* @key_id: Key serial number |
| 271 |
* |
| 272 |
* Fetches the description of the key or keyring identified |
| 273 |
* by the serial number @key_id. |
| 274 |
* |
| 275 |
* Return: The description of @key_id or NULL on failure. |
| 276 |
* The returned string needs to be freed by the caller. |
| 277 |
*/ |
| 278 |
char *nvme_describe_key_serial(long key_id); |
| 279 |
|
| 280 |
/** |
| 281 |
* nvme_lookup_key() - Lookup key serial number |
| 282 |
* @type: Key type |
| 283 |
* @identity: Key description |
| 284 |
* |
| 285 |
* Looks up the serial number of the key @identity |
| 286 |
* with type %type in the current session keyring. |
| 287 |
* |
| 288 |
* Return: The key serial number of the key |
| 289 |
* or 0 with errno set otherwise. |
| 290 |
*/ |
| 291 |
long nvme_lookup_key(const char *type, const char *identity); |
| 292 |
|
| 293 |
/** |
| 294 |
* nvme_set_keyring() - Link keyring for lookup |
| 295 |
* @keyring_id: Keyring id |
| 296 |
* |
| 297 |
* Links @keyring_id into the session keyring such that |
| 298 |
* its keys are available for further key lookups. |
| 299 |
* |
| 300 |
* Return: 0 on success, a negative number on error |
| 301 |
* with errno set. |
| 302 |
*/ |
| 303 |
int nvme_set_keyring(long keyring_id); |
| 304 |
|
| 305 |
/** |
| 306 |
* nvme_read_key() - Read key raw data |
| 307 |
* @keyring_id: Id of the keyring holding %key_id |
| 308 |
* @key_id: Key id |
| 309 |
* @len: Length of the returned data |
| 310 |
* |
| 311 |
* Links the keyring specified by @keyring_id into the session |
| 312 |
* keyring and reads the payload of the key specified by @key_id. |
| 313 |
* @len holds the size of the returned buffer. |
| 314 |
* If @keyring is 0 the default keyring '.nvme' is used. |
| 315 |
* |
| 316 |
* Return: Pointer to the payload on success, |
| 317 |
* or NULL with errno set otherwise. |
| 318 |
*/ |
| 319 |
unsigned char *nvme_read_key(long keyring_id, long key_id, int *len); |
| 320 |
|
| 321 |
/** |
| 322 |
* nvme_update_key() - Update key raw data |
| 323 |
* @keyring_id: Id of the keyring holding %key_id |
| 324 |
* @key_type: Type of the key to insert |
| 325 |
* @identity: Key identity string |
| 326 |
* @key_data: Raw data of the key |
| 327 |
* @key_len: Length of @key_data |
| 328 |
* |
| 329 |
* Links the keyring specified by @keyring_id into the session |
| 330 |
* keyring and updates the key reference by @identity with @key_data. |
| 331 |
* The old key with identity @identity will be revoked to make it |
| 332 |
* inaccessible. |
| 333 |
* |
| 334 |
* Return: Key id of the new key or 0 with errno set otherwise. |
| 335 |
*/ |
| 336 |
long nvme_update_key(long keyring_id, const char *key_type, |
| 337 |
const char *identity, unsigned char *key_data, |
| 338 |
int key_len); |
| 339 |
|
| 340 |
/** |
| 341 |
* typedef nvme_scan_tls_keys_cb_t - Callback for iterating TLS keys |
| 342 |
* @keyring: Keyring which has been iterated |
| 343 |
* @key: Key for which the callback has been invoked |
| 344 |
* @desc: Description of the key |
| 345 |
* @desc_len: Length of @desc |
| 346 |
* @data: Pointer for caller data |
| 347 |
* |
| 348 |
* Called for each TLS PSK in the keyring. |
| 349 |
*/ |
| 350 |
typedef void (*nvme_scan_tls_keys_cb_t)(long keyring, long key, |
| 351 |
char *desc, int desc_len, void *data); |
| 352 |
|
| 353 |
/** |
| 354 |
* nvme_scan_tls_keys() - Iterate over TLS keys in a keyring |
| 355 |
* @keyring: Keyring holding TLS keys |
| 356 |
* @cb: Callback function |
| 357 |
* @data: Pointer for data to be passed to @cb |
| 358 |
* |
| 359 |
* Iterates @keyring and call @cb for each TLS key. When @keyring is NULL |
| 360 |
* the default '.nvme' keyring is used. |
| 361 |
* A TLS key must be of type 'psk' and the description must be of the |
| 362 |
* form 'NVMe<0|1><R|G>0<1|2> <identity>', otherwise it will be skipped |
| 363 |
* during iteration. |
| 364 |
* |
| 365 |
* Return: Number of keys for which @cb was called, or -1 with errno set |
| 366 |
* on error. |
| 367 |
*/ |
| 368 |
int nvme_scan_tls_keys(const char *keyring, nvme_scan_tls_keys_cb_t cb, |
| 369 |
void *data); |
| 370 |
|
| 371 |
/** |
| 372 |
* nvme_insert_tls_key() - Derive and insert TLS key |
| 373 |
* @keyring: Keyring to use |
| 374 |
* @key_type: Type of the resulting key |
| 375 |
* @hostnqn: Host NVMe Qualified Name |
| 376 |
* @subsysnqn: Subsystem NVMe Qualified Name |
| 377 |
* @hmac: HMAC algorithm |
| 378 |
* @configured_key: Configured key data to derive the key from |
| 379 |
* @key_len: Length of @configured_key |
| 380 |
* |
| 381 |
* Derives a 'retained' TLS key as specified in NVMe TCP 1.0a and |
| 382 |
* stores it as type @key_type in the keyring specified by @keyring. |
| 383 |
* |
| 384 |
* Return: The key serial number if the key could be inserted into |
| 385 |
* the keyring or 0 with errno otherwise. |
| 386 |
*/ |
| 387 |
long nvme_insert_tls_key(const char *keyring, const char *key_type, |
| 388 |
const char *hostnqn, const char *subsysnqn, int hmac, |
| 389 |
unsigned char *configured_key, int key_len); |
| 390 |
|
| 391 |
/** |
| 392 |
* nvme_insert_tls_key_versioned() - Derive and insert TLS key |
| 393 |
* @keyring: Keyring to use |
| 394 |
* @key_type: Type of the resulting key |
| 395 |
* @hostnqn: Host NVMe Qualified Name |
| 396 |
* @subsysnqn: Subsystem NVMe Qualified Name |
| 397 |
* @version: Key version to use |
| 398 |
* @hmac: HMAC algorithm |
| 399 |
* @configured_key: Configured key data to derive the key from |
| 400 |
* @key_len: Length of @configured_key |
| 401 |
* |
| 402 |
* Derives a 'retained' TLS key as specified in NVMe TCP 1.0a (if |
| 403 |
* @version s set to '0') or NVMe TP8028 (if @version is set to '1) and |
| 404 |
* stores it as type @key_type in the keyring specified by @keyring. |
| 405 |
* |
| 406 |
* Return: The key serial number if the key could be inserted into |
| 407 |
* the keyring or 0 with errno otherwise. |
| 408 |
*/ |
| 409 |
long nvme_insert_tls_key_versioned(const char *keyring, const char *key_type, |
| 410 |
const char *hostnqn, const char *subsysnqn, |
| 411 |
int version, int hmac, |
| 412 |
unsigned char *configured_key, int key_len); |
| 413 |
|
| 414 |
/** |
| 415 |
* nvme_insert_tls_key_compat() - Derive and insert TLS key |
| 416 |
* @keyring: Keyring to use |
| 417 |
* @key_type: Type of the resulting key |
| 418 |
* @hostnqn: Host NVMe Qualified Name |
| 419 |
* @subsysnqn: Subsystem NVMe Qualified Name |
| 420 |
* @version: Key version to use |
| 421 |
* @hmac: HMAC algorithm |
| 422 |
* @configured_key: Configured key data to derive the key from |
| 423 |
* @key_len: Length of @configured_key |
| 424 |
* |
| 425 |
* Derives a 'retained' TLS key as specified in NVMe TCP 1.0a (if |
| 426 |
* @version s set to '0') or NVMe TP8028 (if @version is set to '1) and |
| 427 |
* stores it as type @key_type in the keyring specified by @keyring. |
| 428 |
* This version differs from @nvme_insert_tls_key_versioned() in that it |
| 429 |
* uses the original implementation for HKDF Expand-Label which does not |
| 430 |
* prefix the 'info' and 'label' strings with the length. |
| 431 |
* |
| 432 |
* Return: The key serial number if the key could be inserted into |
| 433 |
* the keyring or 0 with errno otherwise. |
| 434 |
*/ |
| 435 |
long nvme_insert_tls_key_compat(const char *keyring, const char *key_type, |
| 436 |
const char *hostnqn, const char *subsysnqn, |
| 437 |
int version, int hmac, |
| 438 |
unsigned char *configured_key, int key_len); |
| 439 |
|
| 440 |
/** |
| 441 |
* nvme_generate_tls_key_identity() - Generate the TLS key identity |
| 442 |
* @hostnqn: Host NVMe Qualified Name |
| 443 |
* @subsysnqn: Subsystem NVMe Qualified Name |
| 444 |
* @version: Key version to use |
| 445 |
* @hmac: HMAC algorithm |
| 446 |
* @configured_key: Configured key data to derive the key from |
| 447 |
* @key_len: Length of @configured_key |
| 448 |
* |
| 449 |
* Derives a 'retained' TLS key as specified in NVMe TCP and |
| 450 |
* generate the corresponding TLs identity. |
| 451 |
* |
| 452 |
* Return: The string containing the TLS identity. It is the responsibility |
| 453 |
* of the caller to free the returned string. On error NULL is returned with |
| 454 |
* errno set. |
| 455 |
*/ |
| 456 |
char *nvme_generate_tls_key_identity(const char *hostnqn, const char *subsysnqn, |
| 457 |
int version, int hmac, |
| 458 |
unsigned char *configured_key, int key_len); |
| 459 |
|
| 460 |
/** |
| 461 |
* nvme_generate_tls_key_identity_compat() - Generate the TLS key identity |
| 462 |
* @hostnqn: Host NVMe Qualified Name |
| 463 |
* @subsysnqn: Subsystem NVMe Qualified Name |
| 464 |
* @version: Key version to use |
| 465 |
* @hmac: HMAC algorithm |
| 466 |
* @configured_key: Configured key data to derive the key from |
| 467 |
* @key_len: Length of @configured_key |
| 468 |
* |
| 469 |
* Derives a 'retained' TLS key as specified in NVMe TCP and |
| 470 |
* generate the corresponding TLs identity. This version differs |
| 471 |
* from @nvme_generate_tls_key_identity() in that it uses the original |
| 472 |
* implementation for HKDF-Expand-Label which does not prefix the 'info' |
| 473 |
* and 'label' string with the length. |
| 474 |
* |
| 475 |
* Return: The string containing the TLS identity. It is the responsibility |
| 476 |
* of the caller to free the returned string. |
| 477 |
*/ |
| 478 |
char *nvme_generate_tls_key_identity_compat(const char *hostnqn, |
| 479 |
const char *subsysnqn, |
| 480 |
int version, int hmac, |
| 481 |
unsigned char *configured_key, |
| 482 |
int key_len); |
| 483 |
|
| 484 |
/** |
| 485 |
* nvme_revoke_tls_key() - Revoke TLS key from keyring |
| 486 |
* @keyring: Keyring to use |
| 487 |
* @key_type: Type of the key to revoke |
| 488 |
* @identity: Key identity string |
| 489 |
* |
| 490 |
* Return: 0 on success or on failure -1 with errno set. |
| 491 |
*/ |
| 492 |
long nvme_revoke_tls_key(const char *keyring, const char *key_type, |
| 493 |
const char *identity); |
| 494 |
|
| 495 |
/** |
| 496 |
* nvme_export_tls_key() - Export a TLS key |
| 497 |
* @key_data: Raw data of the key |
| 498 |
* @key_len: Length of @key_data |
| 499 |
* |
| 500 |
* Returns @key_data in the PSK Interchange format as defined in section |
| 501 |
* 3.6.1.5 of the NVMe TCP Transport specification. |
| 502 |
* |
| 503 |
* Return: The string containing the TLS identity or NULL with errno set |
| 504 |
* on error. It is the responsibility of the caller to free the returned |
| 505 |
* string. |
| 506 |
*/ |
| 507 |
char *nvme_export_tls_key(const unsigned char *key_data, int key_len); |
| 508 |
|
| 509 |
/** |
| 510 |
* nvme_export_tls_key_versioned() - Export a TLS pre-shared key |
| 511 |
* @version: Indicated the representation of the TLS PSK |
| 512 |
* @hmac: HMAC algorithm used to transfor the configured PSK |
| 513 |
* in a retained PSK |
| 514 |
* @key_data: Raw data of the key |
| 515 |
* @key_len: Length of @key_data |
| 516 |
* |
| 517 |
* Returns @key_data in the PSK Interchange format as defined in section |
| 518 |
* 3.6.1.5 of the NVMe TCP Transport specification. |
| 519 |
* |
| 520 |
* Return: The string containing the TLS identity or NULL with errno set |
| 521 |
* on error. It is the responsibility of the caller to free the returned |
| 522 |
* string. |
| 523 |
*/ |
| 524 |
char *nvme_export_tls_key_versioned(unsigned char version, unsigned char hmac, |
| 525 |
const unsigned char *key_data, |
| 526 |
size_t key_len); |
| 527 |
|
| 528 |
/** |
| 529 |
* nvme_import_tls_key() - Import a TLS key |
| 530 |
* @encoded_key: TLS key in PSK interchange format |
| 531 |
* @key_len: Length of the resulting key data |
| 532 |
* @hmac: HMAC algorithm |
| 533 |
* |
| 534 |
* Imports @key_data in the PSK Interchange format as defined in section |
| 535 |
* 3.6.1.5 of the NVMe TCP Transport specification. |
| 536 |
* |
| 537 |
* Return: The raw data of the PSK or NULL with errno set on error. It is |
| 538 |
* the responsibility of the caller to free the returned string. |
| 539 |
*/ |
| 540 |
unsigned char *nvme_import_tls_key(const char *encoded_key, int *key_len, |
| 541 |
unsigned int *hmac); |
| 542 |
|
| 543 |
/** |
| 544 |
* nvme_import_tls_key_versioned() - Import a TLS key |
| 545 |
* @encoded_key: TLS key in PSK interchange format |
| 546 |
* @version: Indicated the representation of the TLS PSK |
| 547 |
* @hmac: HMAC algorithm used to transfor the configured |
| 548 |
* PSK in a retained PSK |
| 549 |
* @key_len: Length of the resulting key data |
| 550 |
* |
| 551 |
* Imports @key_data in the PSK Interchange format as defined in section |
| 552 |
* 3.6.1.5 of the NVMe TCP Transport specification. |
| 553 |
* |
| 554 |
* Return: The raw data of the PSK or NULL with errno set on error. It is |
| 555 |
* the responsibility of the caller to free the returned string. |
| 556 |
*/ |
| 557 |
unsigned char *nvme_import_tls_key_versioned(const char *encoded_key, |
| 558 |
unsigned char *version, |
| 559 |
unsigned char *hmac, |
| 560 |
size_t *key_len); |
| 561 |
/** |
| 562 |
* nvme_submit_passthru - Low level ioctl wrapper for passthru commands |
| 563 |
* @fd: File descriptor of the nvme device |
| 564 |
* @ioctl_cmd: IOCTL command id |
| 565 |
* @cmd: Passhtru command |
| 566 |
* @result: Optional field to return the result |
| 567 |
* |
| 568 |
* This is a low level library function which should not be used directly. It is |
| 569 |
* exposed as weak symbol so that the user application is able to provide their own |
| 570 |
* implementation of this function with additional debugging or logging code. |
| 571 |
* |
| 572 |
* Return: The value from the ioctl system call (see ioctl documentation) |
| 573 |
*/ |
| 574 |
__attribute__((weak)) |
| 575 |
int nvme_submit_passthru(int fd, unsigned long ioctl_cmd, |
| 576 |
struct nvme_passthru_cmd *cmd, __u32 *result); |
| 577 |
|
| 578 |
/** |
| 579 |
* nvme_submit_passthru64 - Low level ioctl wrapper for passthru commands |
| 580 |
* @fd: File descriptor of the nvme device |
| 581 |
* @ioctl_cmd: IOCTL command id |
| 582 |
* @cmd: Passhtru command |
| 583 |
* @result: Optional field to return the result |
| 584 |
* |
| 585 |
* This is a low level library function which should not be used directly. It is |
| 586 |
* exposed as weak symbol so that the user application is able to provide their own |
| 587 |
* implementation of this function with additional debugging or logging code. |
| 588 |
* |
| 589 |
* Return: The value from the ioctl system call (see ioctl documentation) |
| 590 |
*/ |
| 591 |
__attribute__((weak)) |
| 592 |
int nvme_submit_passthru64(int fd, unsigned long ioctl_cmd, |
| 593 |
struct nvme_passthru_cmd64 *cmd, |
| 594 |
__u64 *result); |
| 595 |
|
| 596 |
#endif /* _LIBNVME_LINUX_H */ |