File s390-tools-sles15sp1-0008-zkey-Man-page-updates... of Package s390-tools.13271

Overview Repositories Revisions Requests Users Attributes Meta

File s390-tools-sles15sp1-0008-zkey-Man-page-updates.patch of Package s390-tools.13271

Subject: zkey: Man page updates
From: Philipp Rudo <prudo@linux.ibm.com>

Summary:     zkey: Add support of protected key crypto for dm-crypt.
Description: Support the usage of protected key crypto for dm-crypt disks in
             plain format by providing a tool to manage a key repository
             allowing to associate secure keys with disk partitions or logical
             volumes.
Upstream-ID: f093d0bfd4242424515c6aa55c7b8ad94d233597
Problem-ID:  SEC1800

Upstream-Description:

zkey: Man page updates

Add documentation for the new keystore related zkey commands.

Signed-off-by: Ingo Franzki <ifranzki@linux.ibm.com>
             Reviewed-by: Hendrik Brueckner <brueckner@linux.ibm.com>
             Signed-off-by: Jan Höppner <hoeppner@linux.ibm.com>

Signed-off-by: Philipp Rudo <prudo@linux.ibm.com>
---
 zkey/zkey.1 |  870 +++++++++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 811 insertions(+), 59 deletions(-)

--- a/zkey/zkey.1
+++ b/zkey/zkey.1
@@ -1,38 +1,17 @@
-.\" Copyright 2017 IBM Corp.
+.\" Copyright IBM Corp. 2017, 2018
 .\" s390-tools is free software; you can redistribute it and/or modify
 .\" it under the terms of the MIT license. See LICENSE for details.
 .\"
-.TH ZKEY 1 "February 2017" "s390-tools"
+.TH ZKEY 1 "May 2018" "s390-tools"
 .SH NAME
-zkey \- Generates, re-enciphers, and validates secure AES keys
+zkey \- Manage secure AES keys
 .
 .
 .SH SYNOPSIS
 .B zkey
-.BR generate | gen
-.I secure\-key\-file
-.RB [ \-\-keybits | \-k
-.IB size ]
-.RB [ \-\-xts | \-x ]
-.RB [ \-\-clearkey | \-c
-.IB clear\-key\-file ]
-.RB [ \-\-verbose | \-V ]
-.
-.br
-.B zkey
-.BR validate  | val
-.I secure\-key\-file
-.RB [ \-\-verbose | \-V ]
-.
-.br
-.B zkey
-.BR reencipher | re
-.I secure\-key\-file
-.RB [ \-\-to\-new | \-n ]
-.RB [ \-\-from\-old | \-o ]
-.RB [ \-\-output | \-f
-.IB output\-file ]
-.RB [ \-\-verbose | \-V ]
+.I command
+.RI [ secure\-key\-file ]
+.RB [ OPTIONS ]
 .
 .PP
 .B zkey
@@ -44,64 +23,194 @@ zkey \- Generates, re-enciphers, and val
 .
 .
 .SH DESCRIPTION
-Use the \fBzkey\fP command to generate secure AES keys that are enciphered
-with a master key of an IBM cryptographic adapter in CCA coprocessor mode.
-You can also use the \fBzkey\fP command to validate and re-encipher secure
+Use the \fBzkey\fP tool to generate and manage secure AES keys that are
+enciphered with a master key of an IBM cryptographic adapter in CCA coprocessor
+mode. You can also use the \fBzkey\fP tool to validate and re-encipher secure
 AES keys.
 .PP
+The secure keys can either be stored in a file in the file system, or
+in the secure key repository. The default location of the secure key repository
+is \fB/etc/zkey/repository\fP. Set environment variable \fBZKEY_REPOSITORY\fP
+to point to a different location to use a different secure key repository
+location. Keys stored in a secure key repository inherit the permissions from
+the repository directory (except write access for other users, which is always
+denied). The default repository location \fB/etc/zkey/repository\fP is created
+with group \fBzkeyadm\fP as owner and mode \fB770\fP. Thus all secure keys
+created in that repository are owned by group \fBzkeyadm\fP. Anyone that
+is supposed to access secure keys in the secure key repository must be part of
+group \fBzkeyadm\fP.
+.PP
+When storing the secure key in a key repository, additional information, such as
+a textual description of the key, can be associated with a secure key.
+You can associate a secure key with one or multiple cryptographic adapters
+(APQNs) that are set up with the same CCA master key.
+You can also associate a secure key with one or multiple volumes
+(block devices), which are encrypted using dm-crypt with the secure key. The
+volume association also contains the device-mapper name, separated by a colon,
+used with dm-crypt. A specific volume can only be associated with one secure
+key.
+.PP
 The generated secure key is saved in a file with a size of 64 or 128 bytes.
-The file contains an AES key of 128, 192, or 256 bits enciphered with the
-master key of the CCA cryptographic adapter.
+The file contains an AES key with a length of 128, 192, or 256 bits. The key is
+enciphered with the master key of the CCA cryptographic adapter.
 Secure keys that are used for the XTS cipher mode can be 128 or 256 bits
-in size, because XTS requires two concatenated secure keys.
+in size.
+.
 .
 .
+.SH COMMANDS
+The \fBzkey\fP tool can operate in two modes. When argument
+.I secure\-key\-file
+is specified then it operates on the secure key contained in the specified file.
+This applies to commands \fBgenerate\fP, \fBvalidate\fP, and \fBreencipher\fP.
+When the
+.B \-\-name
+option is specified then it operates on a secure key contained in the secure
+key repository.
 .
-.SH USAGE
+.PP
 .SS "Generating secure AES keys"
+.
+.B zkey
+.BR generate | gen
+.I secure\-key\-file
+.RB [ \-\-keybits | \-k
+.IB size ]
+.RB [ \-\-xts | \-x ]
+.RB [ \-\-clearkey | \-c
+.IB clear\-key\-file ]
+.RB [ \-\-verbose | \-V ]
+.
+.PP
+.B zkey
+.BR generate | gen
+.B \-\-name | \-N
+.IB key-name
+.RB [ \-\-description | \-d
+.IB description ]
+.RB [ \-\-volumes | \-l
+.IB volume1:dmname1[,volume2:dmname2[,...]] ]
+.RB [ \-\-apqns | \-a
+.IB card1.domain1[,card2.domain2[,...]] ]
+.RB [ \-\-sector-size | \-S
+.IB bytes ]
+.RB [ \-\-keybits | \-k
+.IB size ]
+.RB [ \-\-xts | \-x ]
+.RB [ \-\-clearkey | \-c
+.IB clear\-key\-file ]
+.RB [ \-\-verbose | \-V ]
+.PP
 Use the
 .B generate
 command to generate a new secure AES key either randomly within the CCA
 cryptographic adapter, or from a clear AES key specified as input. When specifying
-a clear key as input, the clear key should be kept at a secure place, or be
+a clear key as input, the clear key should be kept in a secure place, or be
 securely erased after creation of the secure key. The secure key itself does
 not need to be kept secure, because it can only be used together with a
 CCA cryptographic adapter that contains the master key with which the secure
 key was generated.
+.PP
+The generated secure key can either be stored in a file in the file system,
+or in the secure key repository. To store the generated secure key in a
+file, specify the file name with option \fIsecure\-key\-file\fP. To store the
+secure key in the secure key repository, specify the name of the key using the
+.B --name
+option. When storing the secure key in a key repository,
+additional information can be associated with a secure key using the
+.B --description
+,
+.B --volumes
+,
+.B --apqns
+, or the
+.B --sector-size
+options.
 .
 .SS "Validating secure AES keys"
+.
+.B zkey
+.BR validate | val
+.I secure\-key\-file
+.RB [ \-\-verbose | \-V ]
+.
+.PP
+.B zkey
+.BR validate | val
+.RB [ \-\-name | \-N
+.IB key-name ]
+.RB [ \-\-verbose | \-V ]
+.PP
 Use the
 .B validate
 command to validate an existing secure key.
-It checks if the specified file contains a valid secure key.
+It checks if the specified file or repository entry contains a valid secure key.
 It also displays the attributes of the secure key, such as key sizes, whether
-it is a secure key that can be used for the XTS cipher mode, and the master key
-register with which the secure key is enciphered.
+it is a secure key that can be used for the XTS cipher mode, the master key
+register (CURRENT or OLD) with which the secure key is enciphered, and other key
+attributes. For further information about master key registers, see the
+\fBreencipher\fP command.
+.PP
+The secure key can either be contained in a file in the file system, or in a
+secure key repository. To validate a secure key contained in a file, specify
+the file name with option \fIsecure\-key\-file\fP. To validate secure keys
+contained in the secure key repository, specify the name of the key
+or a pattern containing wildcards using the
+.B --name
+option. When wildcards are used you must quote the value.
+If neither option \fIsecure\-key\-file\fP nor option
+.B --name
+are specified, then all secure keys contained in the key repository
+are validated.
 .
 .SS "Re-encipher existing AES secure keys"
+.
+.B zkey
+.BR reencipher | re
+.I secure\-key\-file
+.RB [ \-\-to\-new | \-n ]
+.RB [ \-\-from\-old | \-o ]
+.RB [ \-\-output | \-f
+.IB output\-file ]
+.RB [ \-\-verbose | \-V ]
+.PP
+.B zkey
+.BR reencipher | re
+.RB [ \-\-name | \-N
+.IB key-name ]
+.RB [ \-\-apqns | \-a
+.IB card1.domain1[,card2.domain2[,...]] ]
+.RB [ \-\-to\-new | \-n ]
+.RB [ \-\-from\-old | \-o ]
+.RB [ \-\-in-place | \-i ]
+.RB [ \-\-staged | \-s ]
+.RB [ \-\-complete | \-c ]
+.RB [ \-\-verbose | \-V ]
+.PP
 Use the
 .B reencipher
 command to re-encipher an existing secure key with a new master key.
-A secure key have to be re-enciphered, when the master key of the CCA
-cryptographic adapter is being changed.
+A secure key bust be re-enciphered when the master key of the CCA
+cryptographic adapter changes.
 .PP
-The CCA cryptographic adapter has 3 different registers to store
+The CCA cryptographic adapter has three different registers to store
 master keys:
 .RS 2
 .IP "\(bu" 2
-The \fPCURRENT\fP register contains the current master key.
+The \fBCURRENT\fP register contains the current master key.
 .
 .IP "\(bu" 2
 The \fBOLD\fP register contains the previously used master key.
 Secure keys enciphered with the master key contained in the \fBOLD\fP
-register canstill be used until the master key is changed again.
+register can still be used until the master key is changed again.
 .
 .IP "\(bu" 2
 The \fBNEW\fP register contains the new master key to be set.
 The master key in the \fBNEW\fP register cannot be used until it is made
-the current master key.  Note that a secure key can be proactively
-re-enciphered with the master key in the \fBNEW\fP register before
-the new master key is made the current one.
+the current master key. You can pro-actively re-encipher a secure key with the
+\fBNEW\fP master key before this key is made the \fBCURRENT\fP key. Use the
+.B \-\-to-new
+option to do this.
 .RE
 .PP
 Use the
@@ -110,13 +219,12 @@ option to re-encipher a secure key that
 the master key in the \fBOLD\fP register with the master key in the
 \fBCURRENT\fP register.
 .PP
-Use the
-.B \-\-to\-new
-option to proactively re-encipher a secure key that is currently
-enciphered with the master key in the \fBCURRENT\fP register with
-the master key in the \fBNEW\fP register.
 .PP
-If both options are specified, a secure key that is currently enciphered
+If both the
+.B \-\-from-old
+and
+.B \-\-to-new
+options are specified, a secure key that is currently enciphered
 with the master key in the \fBOLD\fP register is re-enciphered with the
 master key in the \fBNEW\fP register.
 .PP
@@ -127,11 +235,310 @@ If currently enciphered with the master
 it is re-enciphered with the master key in the \fBCURRENT\fP register.
 If it is currently enciphered with the master key in the \fBCURRENT\fP
 register, it is re-enciphered with the master key in the \fBNEW\fP register.
+If for this case the \fBNEW\fP register does not contain a valid master key,
+then the re-encipher operation fails.
+.PP
+The secure key can either be contained in a file in the file system, or in a
+secure key repository. To re-encipher a secure key contained in a file,
+specify the file name with option \fIsecure\-key\-file\fP. To re-encipher
+secure keys contained in the secure key repository, specify the name of the key
+or a pattern containing wildcards using the
+.B --name
+option. When wildcards are used you must quote the value.
+You can also specify the
+.B --apqns
+option to re-encipher those secure
+keys which are associated with the specified cryptographic adapters (APQNs).
+You can use wildcards for the APQN specification.
+When wildcards are used you must quote the value.
+If both option
+.B --name
+and option
+.B --apqns
+are specified then all secure keys
+contained in the key repository that match both patterns are re-enciphered.
+If all both options are omitted, then all secure keys contained in the key
+repository are re-enciphered.
+.PP
+Re-enciphering a secure key contained in the secure key repository can be
+performed \fBin-place\fP, or in \fBstaged\fP mode.
+.PP
+\fB"In-place"\fP immediately replaces the secure key in the repository with
+the re-enciphered secure key. Re-enciphering from \fBOLD\fP to \fBCURRENT\fP is
+performed in-place per default. You can use option \fB--in-place\fP to force an
+in-place re-enciphering for the \fBCURRENT\fP to \fBNEW\fP case. Be aware that
+a secure key that was re-enciphered in-place from \fBCURRENT\fP to \fBNEW\fP
+is no longer valid, until the new CCA master key has been made the current one.
+.PP
+\fBStaged\fP mode means that the re-enciphered secure key is stored in a
+separate file in the secure key repository. Thus the current secure key is still
+valid at this point. Once the new CCA master key has been set (made active), you
+must rerun the reencipher command with option \fB--complete\fP to complete the
+staged re-enciphering. Re-enciphering from \fBCURRENT\fP to \fBNEW\fP is
+performed in staged mode per default. You can use option \fB--staged\fP to force
+a staged re-enciphering for the \fBOLD\fP to \fBCURRENT\fP case.
 .PP
 .B Note:
-The \fBreencipher\fP command requires the IBM CCA Host Library (libcsulcca.so)
+The \fBreencipher\fP command requires the CCA host library (libcsulcca.so)
 to be installed.
 .
+.SS "Import existing AES secure keys into the secure key repository"
+.
+.B zkey
+.BR import | im
+.I secure\-key\-file
+.B \-\-name | \-N
+.IB key-name
+.RB [ \-\-description | \-d
+.IB description ]
+.RB [ \-\-volumes | \-l
+.IB volume1:dmname1[,volume2:dmname2[,...]] ]
+.RB [ \-\-apqns | \-a
+.IB card1.domain1[,card2.domain2[,...]] ]
+.RB [ \-\-sector-size | \-S
+.IB bytes ]
+.RB [ \-\-verbose | \-V ]
+.
+.PP
+Use the
+.B import
+command to import an existing secure key contained in a file into the the
+secure key repository. When importing a secure key in a key repository,
+additional information can be associated with a secure key using the
+.B --description
+,
+.B --volumes
+,
+.B --apqns
+, or the
+.B --sector-size
+options.
+.
+.SS "Export AES secure keys from the secure key repository"
+.
+.B zkey
+.BR export | ex
+.I secure\-key\-file
+.B \-\-name | \-N
+.IB key-name
+.RB [ \-\-verbose | \-V ]
+.
+.PP
+Use the
+.B export
+command to export an existing secure key contained in the secure key repository
+to a file in the file system. Specify the name of the key that is to be exported
+using the
+.B --name
+option. You cannot use wildcards.
+When wildcards are used you must quote the value.
+The exported secure key also remains in the secure key repository.
+.
+.SS "List AES secure keys contained in the secure key repository"
+.
+.B zkey
+.BR list | li
+.RB [ \-\-name | \-N
+.IB key-name ]
+.RB [ \-\-volumes | \-l
+.IB volume1[:dmname1][,volume2[:dmname2][,...]] ]
+.RB [ \-\-apqns | \-a
+.IB card1.domain1[,card2.domain2[,...]] ]
+.RB [ \-\-verbose | \-V ]
+.
+.PP
+Use the
+.B list
+command to display a list of secure keys contained in the secure key repository.
+You can filter the displayed list by key name, associated volumes, and
+associated cryptographic adapters (APQNs). You can use wildcards for the key
+name, associated APQNs, and associated volumes. The device-mapper name of an
+associated volume can be omitted; if it is specified then only those keys are
+listed that are associated with the specified volume and device-mapper name.
+.PP
+The
+.B list
+command displays the attributes of the secure keys, such as key sizes,
+whether it is a secure key that can be used for the XTS cipher mode, the textual
+description, associated cryptographic adapters (APQNs) and volumes, the
+sector size, and timestamps for key creation, last modification and last
+re-encipherment.
+.
+.SS "Remove existing AES secure keys from the secure key repository"
+.
+.B zkey
+.BR remove | rem
+.B \-\-name | \-N
+.IB key-name
+.RB [ \-\-force | \-F ]
+.RB [ \-\-verbose | \-V ]
+.
+.PP
+Use the
+.B remove
+command to remove an existing secure key from the secure key repository.
+Specify the name of the key that is to be removed using the
+.B --name
+option. You cannot use wildcards. The remove command prompts for
+a confirmation, unless you specify the
+.B --force
+option.
+.PP
+.B Note:
+When removing a secure key that is associated with one or multiple volumes,
+a message informs you about the associated volumes. When the secure key is
+removed, these volumes can no longer be used, unless you have a backup of the
+secure key.
+.
+.SS "Change existing AES secure keys contained the secure key repository"
+.
+.B zkey
+.BR change | ch
+.B \-\-name | \-N
+.IB key-name
+.RB [ \-\-description | \-d
+.IB description ]
+.RB [ \-\-volumes | \-l
+.IB [+|-]volume1:dmname1[,volume2:dmname2[,...]] ]
+.RB [ \-\-apqns | \-a
+.IB [+|-]card1.domain1[,card2.domain2[,...]] ]
+.RB [ \-\-sector-size | \-S
+.IB bytes ]
+.RB [ \-\-verbose | \-V ]
+.
+.PP
+Use the
+.B change
+command to change the description, the associated volumes, the associated
+cryptographic adapters (APQNs), and the sector size of a secure key contained
+in the secure key repository. Specify the name of the key that is to be changed
+using the
+.B --name
+option. You cannot use wildcards.
+.PP
+You can set (replace), add, or
+remove volume and cryptographic adapters (APQN) associations. To set
+(replace) an association, specify the association with the
+.B --volumes
+or the
+.B --apqns
+options. To add an association,
+specify the new association prefixed with a \fI+\fP with the
+.B --volumes
+or the
+.B --apqns
+options. To remove an association,
+specify the association to remove prefixed with a \fI-\fP with the
+.B --volumes
+or the
+.B --apqns
+options. You cannot mix \fI+\fP and
+\fI-\fP in one specification. You can either add or remove (or set) the
+associations with one command.
+.PP
+.B Note:
+The secure key itself cannot be changed, only information about the secure
+key is changed. To rename a secure key, use the \fBrename\fP command.
+To re-encipher a secure key with a new CCA master key, use the \fBreencipher\fP
+command.
+.
+.SS "Rename existing AES secure keys in the secure key repository"
+.
+.B zkey
+.BR rename | ren
+.B \-\-name | \-N
+.IB key-name
+.B \-\-new-name | \-w
+.IB new-key-name
+.RB [ \-\-verbose | \-V ]
+.
+.PP
+Use the
+.B rename
+command to rename an existing secure key in the secure key repository.
+Specify the name of the key that is to be renamed using the
+.B --name
+option and the new name using the
+.B --new-name
+option. You cannot use wildcards.
+.
+.SS "Copy (duplicate) existing AES secure keys in the secure key repository"
+.
+.B zkey
+.B copy | co
+.RB \-\-name | \-N
+.IB key-name
+.B \-\-new-key-name | \-w
+.IB new-name
+.RB [ \-\-volumes | \-l
+.IB volume1:dmname1[,volume2:dmname2[,...]] ]
+.RB [ \-\-verbose | \-V ]
+.
+.PP
+Use the
+.B copy
+command to copy (duplicate) an existing secure key in the secure key repository.
+Specify the name of the key that is to be copied using the
+.B --name
+option and the name of the copied key using the
+.B --new-name
+option. You cannot use wildcards.
+.PP
+.B Note:
+When copying a secure key, the volume associations are not copied, because
+a specific volume can only be associated with a single secure key. Specify the
+.B --volumes
+option to associate different
+volumes with the copied secure key, or use the \fBchange\fP command to associate
+volumes afterwards.
+.
+.SS "Generate crypttab entries for volumes associated with secure AES keys"
+.
+.B zkey
+.BR crypttab | cryptt
+.RB [ \-\-volumes | \-l
+.IB volume1[:dmname1][,volume2[:dmname2][,...]] ]
+.RB [ \-\-verbose | \-V ]
+.
+.PP
+Use the
+.B crypttab
+command to generate crypttab entries using the \fBplain\fP dm-crypt mode
+for volumes that are associated with secure keys contained in the secure key
+repository. Specify the
+.B --volumes
+option to limit the list
+of volumes where crypttab entries are generated for. You can use wildcards.
+When wildcards are used you must quote the value.
+The device-mapper name of an associated volume can be omitted; if it is
+specified then only those volumes with the specified volume and device-mapper
+name are selected.
+.
+.SS "Generate cryptsetup commands for volumes associated with secure AES keys"
+.
+.B zkey
+.BR cryptsetup | crypts
+.RB [ \-\-volumes | \-l
+.IB volume1[:dmname1][,volume2[:dmname2][,...]] ]
+.RB [ \-\-run | \-r ]
+.RB [ \-\-verbose | \-V ]
+.
+.PP
+Use the
+.B cryptsetup
+command to generate \fBcryptsetup plainOpen\fP commands for volumes that are
+associated with secure keys contained in the secure key repository. Specify the
+.B --volumes
+option to limit the list
+of volumes where cryptsetup commands are generated for. You can use wildcards.
+When wildcards are used you must quote the value.
+The device-mapper name of an associated volume can be omitted; if it is
+specified then only those volumes with the specified volume and device-mapper
+name are selected. Specify the
+.B --run
+option to run the generated cryptsetup commands.
+.
+.
 .
 .
 .SH OPTIONS
@@ -139,13 +546,13 @@ to be installed.
 .TP
 .BR \-k ", " \-\-keybits\~\fIsize\fP
 Specifies the size of the AES key to be generated in bits.
-Valid sizes are 128, 192, and 256 bits. Secure keys for use with the
+Valid values are 128, 192, and 256. Secure keys for use with the
 XTS cipher mode can only use keys of 128 or 256 bits.
 The default is 256 bits.
 .TP
 .BR \-x ", " \-\-xts
-Generates a secure AES key for the XTS cipher mode. A secure AES key for
-the XTS cipher mode consist of two concatenated secure keys.
+Generates a secure AES key for the XTS cipher mode that consist of two
+concatenated secure keys.
 .TP
 .BR \-c ", " \-\-clearkey\~\fIclear\-key\-file\fP
 Specifies a file path that contains the clear AES key in binary form.
@@ -154,6 +561,49 @@ determines the size of the AES key.  If
 is specified, the size of the specified file must match the specified
 key size.  Valid file sizes are of 16, 24, or 32 bytes, and of 32 or 64
 bytes for keys to be used with the XTS cipher mode.
+.TP
+.BR \-N ", " \-\-name\~\fIkey-name\fP
+Specifies the name of the secure key in the secure key repository.
+This option is only used for secure keys contained in the secure key repository.
+.TP
+.BR \-d ", " \-\-description\~\fIdescription\fP
+Specifies a textual description for the secure key in the secure key repository.
+This option is only used for secure keys contained in the secure key repository.
+.TP
+.BR \-l ", " \-\-volumes\~\fIvolume1:dmname1[,volume2:dmname2[,...]]\fP
+Specifies a comma-separated list of volumes (block devices) that are
+associated with the secure AES key in the repository. These volumes are to be
+encrypted using dm-crypt with the secure AES key. The volume association also
+contains the device-mapper name, separated by a colon, used with dm-crypt.
+A specific volume can only be associated with a single secure key.
+This option is only used for secure keys contained in the secure key repository.
+.TP
+.BR \-a ", " \-\-apqns\~\fIcard1.domain1[,card2.domain2[,...]]\fP
+Specifies a comma-separated list of cryptographic adapters in CCA
+coprocessor mode (APQN) which are associated with the secure AES key in the
+repository. Each APQN association specifies a card and domain number separated
+by a period (like lszcrypt displays it). When at least one APQN is specified,
+then the first one is used to generate the key. If no APQNs are specified,
+then an APQN is selected automatically. All specified APQNs must be online.
+This option is only used for secure keys contained in the secure key repository.
+.TP
+.BR \-S ", " \-\-sector-size\~\fIbytes\fP
+Specifies the sector size in bytes used with dm-crypt. It must be a power of two
+and in the range 512 - 4096 bytes. If omitted, the system default sector size
+is used.
+This option is only used for secure keys contained in the secure key repository.
+.
+.
+.
+.SS "Options for the validate command"
+.TP
+.BR \-N ", " \-\-name\~\fIkey-name\fP
+Specifies the name of the secure key in the secure key repository. You can
+use wildcards to select multiple secure keys in the secure key repository.
+When wildcards are used you must quote the value.
+This option is only used for secure keys contained in the secure key repository.
+.
+.
 .
 .SS "Options for the reencipher command"
 .TP
@@ -168,7 +618,256 @@ master key in the OLD register with the
 .BR \-f ", " \-\-output\~\fIoutput\-file\fP
 Specifies the name of the output file to which the re-enciphered secure key
 is written. If this option is omitted, the re-enciphered secure key
-is replaced in the file that currently contains the secure key.
+is replaced in the file that currently contains the secure key. This option is
+only used for secure keys stored in a file in the file system. It is not valid
+for keys contained in the secure key repository.
+.TP
+.BR \-N ", " \-\-name\~\fIkey-name\fP
+Specifies the name of the secure key in the secure key repository. You can
+use wildcards to select multiple secure keys in the secure key repository.
+When wildcards are used you must quote the value.
+This option is only used for secure keys contained in the secure key repository.
+.TP
+.BR \-a ", " \-\-apqns\~\fIcard1.domain1[,card2.domain2[,...]]\fP
+Specifies a comma-separated list of cryptographic adapters in CCA
+coprocessor mode (APQNs). You can use wildcards in the APQN specification.
+All secure keys contained in the secure key repository
+which are associated with the specified APQNs are re-enciphered.
+Each APQN specifies a card and domain number separated by a period (like
+lszcrypt displays it).
+This option is only used for secure keys contained in the secure key repository.
+.TP
+.BR \-i ", " \-\-in-place
+Forces an in-place re-enciphering of a secure AES key contained in the secure
+key repository. "In-place" immediately replaces the secure key in the repository
+with the re-enciphered secure key.
+Re-enciphering from OLD to CURRENT is performed in-place per default.
+This option is only used for secure keys contained in the secure key repository.
+.TP
+.BR \-s ", " \-\-staged
+Forces that the re-enciphering of a secure AES key contained in the secure key
+repository is performed in staged mode. Staged mode means that the re-enciphered
+secure key is stored in a separate file in the secure key repository. Thus the
+current secure key is still valid at this point. Once the new CCA master key has
+been set (made active), you must rerun the reencipher command with option
+\fB--complete\fP to complete the staged re-enciphering.
+Re-enciphering from CURRENT to NEW is performed in staged mode per default.
+This option is only used for secure keys contained in the secure key repository.
+.TP
+.BR \-p ", " \-\-complete
+Completes a staged re-enciphering. Use this option after the new CCA master key
+has been set (made active). This option replaces the secure key by its
+re-enciphered version in the secure key repository.
+This option is only used for secure keys contained in the secure key repository.
+.
+.
+.
+.
+.SS "Options for the import command"
+.TP
+.BR \-N ", " \-\-name\~\fIkey-name\fP
+Specifies the name of the secure key in the secure key repository.
+This option is only used for secure keys contained in the secure key repository.
+.TP
+.BR \-d ", " \-\-description\~\fIdescription\fP
+Specifies a textual description for the secure key in the secure key repository.
+This option is only used for secure keys contained in the secure key repository.
+.TP
+.BR \-l ", " \-\-volumes\~\fIvolume1:dmname1[,volume2:dmname2[,...]]\fP
+Specifies a comma-separated list of volumes (block devices) which are
+associated with the secure AES key in the repository. These volumes are to be
+encrypted using dm-crypt with the secure AES key. The volume association also
+contains the device-mapper name, separated by a colon, used with dm-crypt.
+A specific volume can only be associated with a single secure key.
+This option is only used for secure keys contained in the secure key repository.
+.TP
+.BR \-a ", " \-\-apqns\~\fIcard1.domain1[,card2.domain2[,...]]\fP
+Specifies a comma-separated list of cryptographic adapters in CCA
+coprocessor mode (APQN) which are associated with the secure AES key in the
+repository. Each APQN association specifies a card and domain number separated
+by a period (like lszcrypt displays it). All specified APQNs must be online.
+This option is only used for secure keys contained in the secure key repository.
+.TP
+.BR \-S ", " \-\-sector-size\~\fIbytes\fP
+Specifies the sector size in bytes used with dm-crypt. It must be a power of two
+and in the range 512 - 4096 bytes. If omitted, the system default sector size
+is used.
+This option is only used for secure keys contained in the secure key repository.
+.
+.
+.
+.SS "Options for the export command"
+.TP
+.BR \-N ", " \-\-name\~\fIkey-name\fP
+Specifies the name of the secure key in the secure key repository. You cannot
+use wildcards.
+This option is only used for secure keys contained in the secure key repository.
+.
+.
+.
+.SS "Options for the list command"
+.TP
+.BR \-N ", " \-\-name\~\fIkey-name\fP
+Specifies the name of the secure key in the secure key repository. You can
+use wildcards to select multiple secure keys in the secure key repository.
+When wildcards are used you must quote the value.
+Only keys with names that match the pattern are listed.
+This option is only used for secure keys contained in the secure key repository.
+.TP
+.BR \-l ", " \-\-volumes\~\fIvolume1[:dmname1][,volume2[:dmname2][,...]]\fP
+Specifies a comma-separated list of volumes (block devices) which are
+associated with the secure AES key in the repository. Only those keys are
+listed, which are associated with the specified volumes.
+The volume association also contains the device-mapper name, separated by a
+colon, used with dm-crypt. You can omit the device-mapper name; if it is
+specified then only those keys are listed that are associated with the
+specified volume and device-mapper name. You can use wildcards to specify
+the volumes and device-mapper names.
+When wildcards are used you must quote the value.
+This option is only used for secure keys contained in the secure key repository.
+.TP
+.BR \-a ", " \-\-apqns\~\fIcard1.domain1[,card2.domain2[,...]]\fP
+Specifies a comma-separated list of cryptographic adapters in CCA
+coprocessor mode (APQN) which are associated with the secure AES key in the
+repository. Only those keys are listed, which are associated with the specified
+APQNs. Each APQN association specifies a card and domain number separated
+by a period (like lszcrypt displays it). You can use wildcards in the APQN
+specification.
+This option is only used for secure keys contained in the secure key repository.
+.
+.
+.
+.SS "Options for the remove command"
+.TP
+.BR \-N ", " \-\-name\~\fIkey-name\fP
+Specifies the name of the secure key in the secure key repository. You cannot
+use wildcards.
+This option is only used for secure keys contained in the secure key repository.
+.TP
+.BR \-F ", " \-\-force\fP
+The user is prompted to confirm the removal of a secure key from the secure
+key repository. Use this option to remove a secure key without prompting for
+a confirmation.
+This option is only used for secure keys contained in the secure key repository.
+.
+.
+.
+.SS "Options for the change command"
+.TP
+.BR \-N ", " \-\-name\~\fIkey-name\fP
+Specifies the name of the secure key in the secure key repository. You cannot
+use wildcards.
+This option is only used for secure keys contained in the secure key repository.
+.TP
+.BR \-d ", " \-\-description\~\fIdescription\fP
+Specifies a textual description for the secure key in the secure key repository.
+This option is only used for secure keys contained in the secure key repository.
+.TP
+.BR \-l ", " \-\-volumes\~\fI[+|-]volume1:dmname1[,volume2:dmname2[,...]]\fP
+Specifies a comma-separated list of volumes (block devices) which are
+associated with the secure AES key in the repository. These volumes are to be
+encrypted using dm-crypt with the secure AES key. The volume association also
+contains the device-mapper name, separated by a colon, used with dm-crypt.
+To add a volume to the associated volumes, prefix the volume with a \fI+\fP.
+To remove a volume from the associated volumes, prefix the volume with a \fI-\fP.
+To set (replace) the volume association do not specify a prefix.
+You cannot mix \fI+\fP and \fI-\fP in one specification. You can either add or
+remove (or set) the associations with one command.
+A specific volume can only be associated with a single secure key.
+This option is only used for secure keys contained in the secure key repository.
+.TP
+.BR \-a ", " \-\-apqns\~\fI[+|-]card1.domain1[,card2.domain2[,...]]\fP
+Specifies a comma-separated list of cryptographic adapters in CCA
+coprocessor mode (APQN) which are associated with the secure AES key in the
+repository. Each APQN association specifies a card and domain number separated
+by a period (like lszcrypt displays it).
+To add an APQN to the associated APQNs, prefix the APQN with a \fI+\fP.
+To remove an APQN from the associated APQNs, prefix the APQN with a \fI-\fP.
+To set (replace) the APQN association do not specify a prefix.
+You cannot mix \fI+\fP and \fI-\fP in one specification. You can either add or
+remove (or set) the associations with one command.
+All APQNs being added or set (replaced) must be online.
+This option is only used for secure keys contained in the secure key repository.
+.TP
+.BR \-S ", " \-\-sector-size\~\fIbytes\fP
+Specifies the sector size in bytes used with dm-crypt. It must be a power of two
+and in the range 512 - 4096 bytes. If omitted, the system default sector size
+is used. Specify \fI0\fP to un-set the sector size so that the system default
+is used.
+This option is only used for secure keys contained in the secure key repository.
+.
+.
+.
+.SS "Options for the rename command"
+.TP
+.BR \-N ", " \-\-name\~\fIkey-name\fP
+Specifies the name of the secure key in the secure key repository. You cannot
+use wildcards.
+This option is only used for secure keys contained in the secure key repository.
+.TP
+.BR \-w ", " \-\-new-name\~\fInew-key-name\fP
+Specifies the new name of the secure key in the secure key repository.
+This option is only used for secure keys contained in the secure key repository.
+.
+.
+.
+.SS "Options for the copy command"
+.TP
+.BR \-N ", " \-\-name\~\fIkey-name\fP
+Specifies the name of the secure key to be copied in the secure key repository.
+You cannot use wildcards.
+This option is only used for secure keys contained in the secure key repository.
+.TP
+.BR \-w ", " \-\-new-name\~\fInew-key-name\fP
+Specifies the new name of the secure key in the secure key repository.
+This option is only used for secure keys contained in the secure key repository.
+.TP
+.BR \-l ", " \-\-volumes\~\fIvolume1:dmname1,volume2:dmname2[,...]]\fP
+Volume associations are not copied, because a volume can only be associated
+with a single secure key. To associate different volumes with the copied
+secure AES key, specify a comma-separated list of volumes (block devices).
+These volumes are to be encrypted using dm-crypt with the secure AES key. The
+volume association also contains the device-mapper name, separated by a colon,
+used with dm-crypt.
+This option is only used for secure keys contained in the secure key repository.
+.
+.
+.
+.SS "Options for the crypttab command"
+.TP
+.BR \-l ", " \-\-volumes\~\fIvolume1[:dmname1][,volume2[:dmname2][,...]]\fP
+Specifies a comma-separated list of volumes (block devices) which are
+associated with secure AES keys in the repository.
+The volume association also contains the device-mapper name, separated by a
+colon, used with dm-crypt. You can omit the device-mapper name; if it is
+specified then only those keys are selected that are associated with the
+specified volume and device-mapper name. You can use wildcards to specify
+the volumes and device-mapper names.
+When wildcards are used you must quote the value.
+This option is only used for secure keys contained in the secure key repository.
+.
+.
+.
+.SS "Options for the cryptsetup command"
+.TP
+.BR \-l ", " \-\-volumes\~\fIvolume1[:dmname1][,volume2[:dmname2][,...]]\fP
+Specifies a comma-separated list of volumes (block devices) which are
+associated with secure AES keys in the repository.
+The volume association also contains the device-mapper name, separated by a
+colon, used with dm-crypt. You can omit the device-mapper name; if it is
+specified then only those keys are selected that are associated with the
+specified volume and device-mapper name. You can use wildcards to specify
+the volumes and device-mapper names.
+When wildcards are used you must quote the value.
+This option is only used for secure keys contained in the secure key repository.
+.TP
+.BR \-r ", " \-\-run\fP
+Runs the generated cryptsetup commands. When an execution of a cryptsetup
+command fails, no further cryptsetup commands are executed, and zkey ends
+with an error.
+This option is only used for secure keys contained in the secure key repository.
+.
+.
 .
 .SS "General options"
 .TP
@@ -186,16 +885,25 @@ Displays version information and exits.
 .SH EXAMPLES
 .TP
 .B zkey generate seckey.bin
-Generates a 256-bit secure AES key and stores it in file 'seckey.bin'.
+Generates a random 256-bit secure AES key and stores it in file 'seckey.bin'.
 .TP
 .B zkey generate seckey.bin \-\-keybits 128 \-\-xts
-Generates a 128-bit secure AES key for the XTS cipher mode and stores it
+Generates a random 128-bit secure AES key for the XTS cipher mode and stores it
 in file 'seckey.bin'.
 .TP
 .B zkey generate seckey.bin \-\-clearkey clearkey.bin
 Generates a secure AES key from the clear key in file 'clearkey.bin' and
 stores it in file 'seckey.bin'.
 .TP
+.B zkey generate --name seckey
+Generates a random 256-bit secure AES key and stores it in the secure key
+repository under the name 'seckey'.
+.TP
+.B zkey generate --name seckey --volumes /dev/dasdc1:encvol --apqns 03.004c
+Generates a random 256-bit secure AES key and stores it in the secure key
+repository under the name 'seckey' and associates it with block
+device '/dev/dasdc1' and device-mapper name 'encvol', and APQN '03.004c'.
+.TP
 .B zkey reencipher seckey.bin \-\-from\-old
 Re-enciphers the secure key in file 'seckey.bin' which is currently enciphered
 with the master key in the OLD register with the master key in the CURRENT
@@ -207,5 +915,49 @@ Re-enciphers the secure key in file 'sec
 with the master key in the CURRENT register with the master key in the NEW
 register, and saves the re-enciphered secure key to file 'seckey2.bin'.
 .TP
+.B zkey reencipher --name seckey
+Re-enciphers the secure key 'seckey' in the secure key repository.
+.TP
+.B zkey reencipher --apqns 03.004c
+Re-enciphers all secure keys contained in the secure key repository that are
+associated with APQN '03.004c'.
+.TP
 .B zkey validate seckey.bin
 Validates the secure key in file 'seckey.bin' and displays its attributes.
+.TP
+.B zkey validate --name seckey
+Validates the secure key 'seckey' in the secure key repository and displays its
+attributes.
+.TP
+.B zkey list
+Lists all secure keys in the secure key repository and displays its
+attributes.
+.TP
+.B zkey list --name '*key'
+Lists all secure keys in the secure key repository with names ending with 'key'
+and displays its attributes.
+.TP
+.B zkey change --name seckey --volumes +/dev/dasdc2:encvol2
+Changes the secure key 'seckey' in the secure key repository and adds
+volume '/dev/dasdc2' with device-mapper name 'encvol2' to the list of associated
+volumes of this secure key.
+.TP
+.B zkey change --name seckey --apqns -03.004c
+Changes the secure key 'seckey' in the secure key repository and removes
+APQN '03.004c' from the list of associated APQNs of this secure key.
+.TP
+.B zkey crypttab --volumes '/dev/dasdc*'
+Generates crypttab entries for all volumes that match the pattern '/dev/dasdc*'.
+.TP
+.B zkey cryptsetup --volumes '*:enc_dasd'
+Generates cryptsetup commands for the volumes that uses the device-mapper
+name 'enc_dasd'.
+.
+.SH ENVIRONMENT
+.TP
+.BR ZKEY_REPOSITORY
+If
+.B $ZKEY_REPOSITORY
+is set, it specifies the location of the secure key repository.
+If it is not set, then the the default location of the secure key
+repository is \fB/etc/zkey/repository\fP.
\ No newline at end of file

Places

File s390-tools-sles15sp1-0008-zkey-Man-page-updates.patch of Package s390-tools.13271

Places