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>

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',

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,15 +55,73 @@ 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::
 	Increase the information detail in the output.
 
 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
 ----