NVME-KEYS-INSERT-(1)

NAME
nvme-keys-insert-tls-psk - Insert a NVMe TLS PSK into a keyring

SYNOPSIS

nvme [<global-options>] keys insert-tls-psk [--keyring=<name> | -k <name>]
                        [--keytype=<type> | -t <type>]
                        [--hostnqn=<nqn> | -n <nqn>]
                        [--subsysnqn=<nqn> | -c <nqn>]
                        [--keydata=<key> | -d <key>]
                        [--identity=<id-vers> | -I <id-vers>]
                        [--compat | -C]
                        [--keyfile=<keyfile> | -f <keyfile>]

DESCRIPTION

Takes a NVMe TLS configured PSK in the PSK interchange format NVMeTLSkey-1:<hmac>:<base64-encoded data>:, derives a retained PSK from it and the given host NQN using the HKDF-Expand-Label algorithm from RFC 8446, derives the TLS PSK from that, and stores the result into the specified keyring. The TLS PSK is stored with the identity NVMe0R<hmac> <host NQN> <subsystem NQN> (for identity version 0) or NVMe1R<hmac> <host NQN> <subsystem NQN> <PSK digest> (for identity version 1). Once the TLS PSK is stored in the keyring the configured PSK it was derived from cannot be retrieved from the keyring.

Both NQNs are inputs to the TLS PSK itself, not just to the identity it is stored under: the host NQN through the retained PSK derivation, and both NQNs again through the identity (identity version 0) or the PSK digest it embeds (identity version 1), which is the context of the TLS PSK derivation.

This command is for deriving a new TLS PSK from a configured PSK; it always needs a subsystem NQN (and, if not given, will look up the host NQN) to derive the TLS PSK and compute the identity to store it under. If both the key to store and the identity to store it under are already known — for example a line previously written by nvme-keys-export(1), or a KX-HMAC-CHAP secret — use nvme-keys-import(1) instead, which stores the key as given under an explicit identity, deriving neither.

If --keydata is not given the configured PSK is read from stdin, which also allows reading it from a file, e.g. nvme keys insert-tls-psk -c <subsysnqn> < keyfile.

To check whether a key is already loaded without inserting it, use nvme-keys-check-tls-psk(1).

OPTIONS

-k <name>, --keyring=<name>
    Name of the keyring into which the TLS PSK should be stored. Default is .nvme.

-t <type>, --keytype=<type>
    Type of the key under which the TLS PSK is stored. Default is psk.

-n <nqn>, --hostnqn=<nqn>
    Host NVMe Qualified Name (NQN) to be used for the retained PSK derivation and for the identity the TLS PSK is stored under. Defaults to the host NQN of the system, read from /etc/nvme/hostnqn or, if that file does not exist, generated from the host ID.

-c <nqn>, --subsysnqn=<nqn>
    Subsystem NVMe Qualified Name (NQN) to be used for the identity the TLS PSK is stored under. Required.

-d <key>, --keydata=<key>
    Configured PSK to derive the TLS PSK from. If not given, it is read from stdin.

-I <id-vers>, --identity=<id-vers>
    TLS PSK identity version to be used; 0 (the default) is obsolete and defined in the NVMe TCP Transport Specification 1.0, 1 is TLS 1.3 with the PSK digest in the TLS PSK identity.

-C, --compat
    Use the original non-RFC 8446 compliant algorithm when deriving the retained PSK and the TLS PSK for compatibility with older implementations.

-f <keyfile>, --keyfile=<keyfile>
    Append the identity of the TLS PSK, and the TLS PSK itself in PSK interchange format, to keyfile.

GLOBAL OPTIONS

The following options are defined at the top-level nvme command and are available to this subcommand:

--dry-run
    Print the command that would be executed, but do not actually execute it.

--no-ioctl-probing
    Disable probing for 64-bit IOCTL support.

--no-retries
    Disable retry logic on transient errors.

-o <fmt>, --output-format=<fmt>
    Set the reporting format to normal, tabular, 'json, or binary. Only one output format may be used at a time.

--output-format-version=<version>
    Select the output format version. Version 1 uses the original field naming, while version 2 (default) provides more consistent and script-friendly field names.

--timeout=<ms>
    Set the timeout for the command in milliseconds.

-v, --verbose
    Increase the level of detail in the output. May be specified multiple times to further increase verbosity.

These options can also be set as machine-wide defaults in nvme-cli.conf(5). A command-line flag always overrides the file.

EXAMPLES

No Examples

NVME

Part of the nvme-user suite