doc: add tls-key --revoke documentation

Add the --revoke option to the tls-key documentation.

While at it, add examples how to use it.

Signed-off-by: Daniel Wagner <dwagner@suse.de>

diff --git a/Documentation/meson.build b/Documentation/meson.build
index f800aabbc6df1bffd60bc83f3fb071741d567565..12abe8940c3849bb41cbfbb3087914d5444f66ea 100644 (file)
--- a/Documentation/meson.build
+++ b/Documentation/meson.build
@@ -144,6 +144,7 @@ adoc_sources = [
   'nvme-subsystem-reset',
   'nvme-supported-log-pages',
   'nvme-telemetry-log',
+  'nvme-tls-key',
   'nvme-toshiba-clear-pcie-correctable-errors',
   'nvme-toshiba-vs-internal-log',
   'nvme-toshiba-vs-smart-add-log',

diff --git a/Documentation/nvme-tls-key.txt b/Documentation/nvme-tls-key.txt
index 9f170a648bc0f676c0009cc2f3c54a1d6e122178..e1819c74b264b0419299d539e020ce40e120ef28 100644 (file)
--- a/Documentation/nvme-tls-key.txt
+++ b/Documentation/nvme-tls-key.txt
@@ -1,5 +1,5 @@
 nvme-tls-key(1)
-======================
+===============
 
 NAME
 ----
@@ -12,13 +12,14 @@ SYNOPSIS
                        [--keytype=<type> | -t <type>]
                        [--keyfile=<file> | -f <file>]
                        [--import | -i] [--export | -e]
+                       [--revoke=<description>| -r <description>]
                        [--verbose | -v]
 
 DESCRIPTION
 -----------
-Import or export NVMe TLS pre-shared keys (PSKs) from the
-system keystore. When the '--export' option is given, all
-NVMe TLS PSKs are exported in the form
+Import, export or remove NVMe TLS pre-shared keys (PSKs) from the system
+keystore. When the '--export' option is given, all NVMe TLS PSKs are
+exported in the form
 
 <descriptions> <psk>
 
@@ -54,7 +55,11 @@ OPTIONS
 -e::
 --export::
        Write the key data to the file specified by '--keyfile'
-       or stdou if not present.
+       or stdout if not present.
+
+-r <description>::
+--revoke=<description>::
+       Revoke a key from a keyring.
 
 -v::
 --verbose::
@@ -62,7 +67,61 @@ OPTIONS
 
 EXAMPLES
 --------
-No Examples
+
+* Create a new TLS key and insert it directly into the .nvme keyring:
++
+------------
+# nvme gen-tls-key -i -n hostnqn0 -c subsys0
+NVMeTLSkey-1:01:/b9tVz2OXJVISnoFgrPAygyS86XYJWkAapQeULns6PMpM8wv:
+Inserted TLS key 26b3260e
+------------
+
+* Export previously created key from the kernel keyring and store it into a file
++
+------------
+# nvme tls-key -e -f nvme-tls-keys.txt
+------------
+
+* Export/list all keys from the .nvme keyring using nvme and keyctl
++
+------------
+# nvme tls-key --export
+NVMe0R01 hostnqn0 subsys0 NVMeTLSkey-1:01:/b9tVz2OXJVISnoFgrPAygyS86XYJWkAapQeULns6PMpM8wv:
+
+# keyctl show
+Session Keyring
+ 573249525 --alswrv      0     0  keyring: _ses
+ 353599402 --alswrv      0 65534   \_ keyring: _uid.0
+ 475911922 ---lswrv      0     0   \_ keyring: .nvme
+ 649274894 --als-rv      0     0       \_ psk: NVMe0R01 hostnqn0 subsys0
+------------
+
+* Revoke a key using the description and verifying with
+keyctl the operation
++
+------------
+# nvme tls-key --revoke="NVMe0R01 hostnqn0 subsys0"
+
+# keyctl show
+Session Keyring
+ 573249525 --alswrv      0     0  keyring: _ses
+ 353599402 --alswrv      0 65534   \_ keyring: _uid.0
+ 475911922 ---lswrv      0     0   \_ keyring: .nvme
+649274894: key inaccessible (Key has been revoked)
+------------
+
+* Import back previously generated key from file and verify with keyctl
++
+------------
+# nvme tls-key --import -f nvme-tls-keys.txt
+
+# keyctl show
+Session Keyring
+ 573249525 --alswrv      0     0  keyring: _ses
+ 353599402 --alswrv      0 65534   \_ keyring: _uid.0
+ 475911922 ---lswrv      0     0   \_ keyring: .nvme
+ 734343968 --als-rv      0     0       \_ psk: NVMe0R01 hostnqn0 subsys0
+------------
 
 NVME
 ----