nvme-keys-insert-tls-psk(1)
===========================

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

SYNOPSIS
--------
[verse]
'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
linknvme:nvme-keys-export[1], or a KX-HMAC-CHAP secret -- use
linknvme: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
linknvme: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.

include::global-options.txt[]

EXAMPLES
--------
No Examples

NVME
----
Part of the nvme-user suite
