Debian Codegraph @

src/nvme/linux.h

raw
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 */