s390-tools/zkey/zkey.1

.\" Copyright IBM Corp. 2017, 2024
.\" 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 2024" "s390-tools"
.SH NAME
zkey \- Manage secure AES keys
.
.
.SH SYNOPSIS
.B zkey
.I command
.RI [ secure\-key\-file ]
.RB [ OPTIONS ]
.
.PP
.B zkey
.I command sub-command
.RB [ OPTIONS ]
.
.
.PP
.B zkey
.BR \-\-help | \-h
.br
.B zkey
.BR \-\-version | \-v
.
.
.
.SH DESCRIPTION
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 or EP11
coprocessor mode, dependent on the key type. 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 who
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 or EP11 master key.
You can also associate a secure key with one or multiple volumes
(block devices), which are encrypted using \fBdm\-crypt\fP with the secure key.
The volume association also contains the device-mapper name, separated by a
colon, used with \fBdm\-crypt\fP. A specific volume can only be associated with
one secure key.
.PP
The generated secure key is saved in a file, and contains an AES secure key with
a length of 128, 192, or 256 bits, or two concatenated AES secure keys with a
length of 128, or 256 bits each, for keys that are used for the XTS cipher mode.
Note that the file size is not related to the key bit size, but is specific for
the secure key type. The key is enciphered with the master key of the CCA or
EP11 cryptographic adapter.
.PP
Secure keys in a key repository can either be generated locally, or by a \fBkey
management system (KMS)\fP. A key repository can be bound to a key management
system (KMS) via a key management system plugin (KMS plugin), which builds the
interface to the key management system. This allows one to integrate a zkey key
repository into an enterprise key management system, that manages the keys in
a larger environment.
When a key repository is bound to a key management system, then all keys are
generated by the key management system per default, and are thus also bound to
the key management system. Any additional information associated with the keys
in the repository is also stored in the key management system.
.
.
.
.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, \fBreencipher\fP, and
\fBconvert\fP.
When the
.B \-\-name
option is specified then it operates on a secure key contained in the secure
key repository.
.
.PP
.SS "Generating secure AES keys"
.
.B zkey
.BR generate | gen
.I secure\-key\-file
.RB [ \-\-keybits | \-k
.IR size ]
.RB [ \-\-xts | \-x ]
.RB [ \-\-clearkey | \-c
.IR clear\-key\-file ]
.RB [ \-\-key\-type | \-K
.IR type ]
.RB [ \-\-verbose | \-V ]
.
.PP
.B zkey
.BR generate | gen
.B \-\-name | \-N
.IR key\-name
.RB [ \-\-description | \-d
.IR description ]
.RB [ \-\-volumes | \-l
.IR volume1:dmname1[,volume2:dmname2[,...]] ]
.RB [ \-\-apqns | \-a
.IR card1.domain1[,card2.domain2[,...]] ]
.RB [ \-\-no\-apqn\-check ]
.RB [ \-\-sector\-size | \-S
.IR bytes ]
.RB [ \-\-volume\-type | \-t
.IR type ]
.RB [ \-\-keybits | \-k
.IR size ]
.RB [ \-\-xts | \-x ]
.RB [ \-\-clearkey | \-c
.IR clear\-key\-file ]
.RB [ \-\-key\-type | \-K
.IR type ]
.RB [ \-\-local | \-L ]
.RB [ \-\-gen\-dummy\-passphrase ]
.RB [ \-\-set\-dummy\-passphrase
.IR passphrase\-file ]
.RB [ KMS-plugin\ specific\ options ]
.RB [ \-\-verbose | \-V ]
.PP
Use the
.B generate
command to generate a new secure AES key either randomly within the CCA or EP11
cryptographic adapter, from a clear AES key specified as input, or using a key
management system plugin (KMS plugin). When specifying 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 or EP11 cryptographic adapter
that contains the master key with which the secure key was generated.
.PP
When the secure key repository is bound to a key management system plugin (KMS
plugin), then the secure key is generated by using the key management system,
except the \fB\-\-local\fP option is specified.
.PP
A key management system plugin may offer plugin specific options that can be
specified with the \fBgenerate\fP command. Use \fBgenerate \-\-help\fP
to display the plugin specific options and their meaning.
.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. Secure keys generated using a key management system plugin can only be
stored in a secure key repository. 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. When the secure key repository is bound to a key management system
plugin, then you can not associate specific APQNs with such keys, but the keys
inherit the APQNs that are associated with the key management system plugin.
.PP
You can generate different types of secure keys: \fBCCA\-AESDATA\fP keys,
\fBCCA\-AESCIPHER\fP, and \fBEP11\-AES\fP keys.
Specify the type of the secure key using the
.B \-\-key\-type
option. Normally, the default key type is CCA\-AESDATA. If the secure key
repository is bound to a key management system plugin, and the plugin does not
support keys of type CCA\-AESDATA, then the default key type is CCA\-AESCIPHER,
or EP11\-AES, whichever the plugin supports.
.PP
.B Note:
Secure keys of type \fBCCA\-AESCIPHER\fP require an IBM cryptographic
adapter in CCA coprocessor mode of version 6 or later, e.g. a CEX6C.
Secure keys of type \fBEP11\-AES\fP require an IBM cryptographic
adapter in EP11 coprocessor mode of version 7 or later, e.g. a CEX7P.
.
.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
.IR key\-name ]
.RB [ \-\-apqns | \-a
.IR card1.domain1[,card2.domain2[,...]] ]
.RB [ \-\-no\-apqn\-check ]
.RB [ \-\-verbose | \-V ]
.PP
Use the
.B validate
command to validate an existing 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, 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.
You can also specify the
.B \-\-apqns
option to validate 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 validated.
If neither option \fIsecure\-key\-file\fP nor options
.B \-\-name
or
.B \-\-apqns
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
.IR output\-file ]
.RB [ \-\-verbose | \-V ]
.PP
.B zkey
.BR reencipher | re
.RB [ \-\-name | \-N
.IR key\-name ]
.RB [ \-\-apqns | \-a
.IR 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 must be re-enciphered when the master key of the CCA or EP11
cryptographic adapter changes.
.PP
Keys of type \fBPVSECRET\-AES\fP can not be re-enciphered. These keys do not
use a cryptographic adapter, thus they do not need to be re-enciphered when the
master of a cryptographic adapter changes.
.PP
The CCA cryptographic adapter has three different registers to store
master keys:
.RS 2
.IP "\(bu" 2
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 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. 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
\fBNote:\fP An EP11 cryptographic adapter has only two registers to store master
keys, \fBCURRENT\fP and \fBNEW\fP.
.PP
Use the
.B \-\-from\-old
option to re-encipher a secure key that is currently enciphered with
the master key in the \fBOLD\fP register with the master key in the
\fBCURRENT\fP register. This option is only available for secure keys of type
\fBCCA\-AESDATA\fP or \fBCCA\-AESCIPHER\fP.
.PP
.PP
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
If both options are omitted, \fBzkey\fP automatically detects whether the
secure key is currently enciphered with the master key in the \fBOLD\fP
register or with the master key in the \fBCURRENT\fP register.
If currently enciphered with the master key in the \fBOLD\fP register,
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 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 or EP11 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 or EP11 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 CCA host library (libcsulcca.so, for)
for secure keys of type CCA\-AESDATA or CCA\-AESCIPHER, or the IBM Z Enterprise
PKCS #11 (EP11) Support Program (EP11 host library) for secure keys of type
EP11\-AES to be installed. For the supported environments and downloads, see:
\fIhttp://www.ibm.com/security/cryptocards\fP
.
.SS "Import existing AES secure keys into the secure key repository"
.
.B zkey
.BR import | im
.I secure\-key\-file
.B \-\-name | \-N
.IR key\-name
.RB [ \-\-description | \-d
.IR description ]
.RB [ \-\-volumes | \-l
.IR volume1:dmname1[,volume2:dmname2[,...]] ]
.RB [ \-\-apqns | \-a
.IR card1.domain1[,card2.domain2[,...]] ]
.RB [ \-\-no\-apqn\-check ]
.RB [ \-\-sector\-size | \-S
.IR bytes ]
.RB [ \-\-volume\-type | \-t
.IR type ]
.RB [ \-\-gen\-dummy\-passphrase ]
.RB [ \-\-set\-dummy\-passphrase
.IR passphrase\-file ]
.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.
.PP
Keys of type \fBPVSECRET\-AES\fP do not use a cryptographic adapter, thus APQNs
can not be associated with them.
.PP
.B Note:
The \fBimport\fP command requires the CCA host library (libcsulcca.so)
to be installed when secure keys of type \fBCCA\-AESCIPHER\fP are imported.
For the supported environments and downloads, see:
\fIhttp://www.ibm.com/security/cryptocards\fP
.
.SS "Export AES secure keys from the secure key repository"
.
.B zkey
.BR export | ex
.I secure\-key\-file
.B \-\-name | \-N
.IR 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.
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
.IR key\-name ]
.RB [ \-\-volumes | \-l
.IR volume1[:dmname1][,volume2[:dmname2][,...]] ]
.RB [ \-\-apqns | \-a
.IR card1.domain1[,card2.domain2[,...]] ]
.RB [ \-\-volume\-type | \-t
.IR type ]
.RB [ \-\-key\-type | \-K
.IR type ]
.RB [ \-\-local | \-L ]
.RB [ \-\-kms\-bound | \-M ]
.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, associated
cryptographic adapters (APQNs), volume type, and whether the keys are local or
bound to a key management system (MKS). 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, key type,
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, the key verification pattern, timestamps for key creation, last
modification and last re-encipherment, and whether the key is local or
bound to a key management system (KMS).
.
.SS "Remove existing AES secure keys from the secure key repository"
.
.B zkey
.BR remove | rem
.B \-\-name | \-N
.IR key\-name
.RB [ \-\-force | \-F ]
.RB [ KMS-plugin\ specific\ options ]
.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
When the secure key that is to be removed is bound to a key management system,
then the key management system plugin might also take an action in the key
management system. It may for example change the state of the key in the key
management system, instead of removing the key. Nevertheless, the secure key
is removed from the local repository.
.PP
A key management system plugin may offer plugin specific options that can be
specified with the \fBremove\fP command. Use \fBremove \-\-help\fP
to display the plugin specific options and their meaning.
.PP
.B Note:
When removing a secure key that is associated with one or multiple volumes,
and the key's volume type is \fBplain\fP,
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. For keys with volume type \fBluks2\fP no such message is issued,
because the secure key is contained in the LUKS2 header.
.
.SS "Change existing AES secure keys contained the secure key repository"
.
.B zkey
.BR change | ch
.B \-\-name | \-N
.IR key\-name
.RB [ \-\-description | \-d
.IR description ]
.RB [ \-\-volumes | \-l
.IR [+|\-]volume1:dmname1[,volume2:dmname2[,...]] ]
.RB [ \-\-apqns | \-a
.IR [+|\-]card1.domain1[,card2.domain2[,...]] ]
.RB [ \-\-no\-apqn\-check ]
.RB [ \-\-sector\-size | \-S
.IR bytes ]
.RB [ \-\-volume\-type | \-t
.IR type ]
.RB [ \-\-gen\-dummy\-passphrase ]
.RB [ \-\-set\-dummy\-passphrase
.IR passphrase\-file ]
.RB [ \-\-remove\-dummy\-passphrase ]
.RB [ \-\-force | \-F ]
.RB [ \-\-verbose | \-V ]
.
.PP
Use the
.B change
command to change the description, the associated volumes, the associated
cryptographic adapters (APQNs), the sector size, and the volume type 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
For secure AES keys that are bound to a key management system (KMS) you can not
change the APQN association. KMS-bound secure AES keys are always bound to the
APQNs that are associated with the key management system plugin.
Other associated information is also changed in the key management system when
changed using the change command.
.PP
For keys of type \fBPVSECRET\-AES\fP you can not change or set the APQN
association. These keys do not use a cryptographic adapter, thus APQNs can not
be associated with them.
.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 or EP11 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
.IR key\-name
.B \-\-new\-name | \-w
.IR 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.
.
.B Note:
When renaming a secure key that is associated with one or multiple volumes and
the key's volume type is \fBplain\fP, a message informs you about the
associated volumes. When the secure key is renamed, these volumes can no
longer be used, unless you change the name of the secure key in the 'cryptsetup
plainOpen' commands and in the '/etc/crypttab' entries.
For keys with volume type \fBluks2\fP no such message is issued, because the
secure key is contained in the LUKS2 header.
.
.SS "Copy (duplicate) existing AES secure keys in the secure key repository"
.
.B zkey
.B copy | co
.RB \-\-name | \-N
.IR key\-name
.B \-\-new\-name | \-w
.IR new\-key\-name
.RB [ \-\-volumes | \-l
.IR volume1:dmname1[,volume2:dmname2[,...]] ]
.RB [ \-\-local | \-L ]
.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.
.PP
You can not copy secure keys that are bound to a key management system (KMS),
except when the \fB\-\-local\fP option is specified. The copied secure key is
then created as a local key.
.
.SS "Generate crypttab entries for volumes associated with secure AES keys"
.
.B zkey
.BR crypttab | cryptt
.RB [ \-\-volumes | \-l
.IR volume1[:dmname1][,volume2[:dmname2][,...]] ]
.RB [ \-\-volume\-type | \-t
.IR type ]
.RB [ \-\-key\-file
.IR file\-name ]
.RB [ \-\-keyfile\-offset
.IR bytes ]
.RB [ \-\-keyfile\-size
.IR bytes ]
.RB [ \-\-tries
.IR number ]
.RB [ \-\-verbose | \-V ]
.
.PP
Use the
.B crypttab
command to generate crypttab entries using the \fBplain\fP or \fBLUKS2\fP
\fBdm\-crypt\fP 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.
Specify the
.B \-\-volume\-type
option to generate crypttab entries for the specified volume type only.
.P
For LUKS2 volumes, a passphrase is required. You are prompted for the
passphrase during system startup when crypttab is evaluated, unless option
.B \-\-key\-file
is specified, or a dummy passphrase is associated with the secure key. Option
.B \-\-tries
specifies how often a passphrase can be re-entered. When option
.B \-\-key\-file
is specified, the passphrase is read from the specified file. You can specify
options
.B \-\-keyfile\-offset
and
.B \-\-keyfile\-size
to control which part of the key file is used as passphrase. These options are
passed to the generated crypttab entries and are only available if
.B zkey
has been compiled with LUKS2 support enabled.
.
.SS "Generate cryptsetup commands for volumes associated with secure AES keys"
.
.B zkey
.BR cryptsetup | crypts
.RB [ \-\-volumes | \-l
.IR volume1[:dmname1][,volume2[:dmname2][,...]] ]
.RB [ \-\-volume\-type | \-t
.IR type ]
.RB [ \-\-run | \-r ]
.RB [ \-\-open ]
.RB [ \-\-format ]
.RB [ \-\-key\-file
.IR file\-name ]
.RB [ \-\-keyfile\-offset
.IR bytes ]
.RB [ \-\-keyfile\-size
.IR bytes ]
.RB [ \-\-tries
.IR number ]
.RB [ \-\-batch\-mode | \-q ]
.RB [ \-\-verbose | \-V ]
.
.PP
Use the
.B cryptsetup
command to generate \fBcryptsetup plainOpen\fP, \fBcryptsetup luksOpen\fP, or
\fBcryptsetup luksFormat\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 \-\-volume\-type
option to generate cryptsetup commands for the specified volume type only.
Specify the
.B \-\-run
option to run the generated cryptsetup commands. Specify the
.B \-\-open
to generate \fBcryptsetup plainOpen\fP or \fBcryptsetup luksOpen\fP commands.
For the plain volume type, this is the default. Specify the
.B \-\-format
option to generate \fBcryptsetup luksFormat\fP commands. For the LUKS2 volume
type, this is the default. If specified for the plain volume type, then no
command is generated.
.P
For LUKS2 volumes, the generated \fBcryptsetup luksFormat\fP contains
options \fB\-\-pbkdf argon2i \-\-pbkdf\-memory 32 \-\-pbkdf\-force\-iterations
4\fP for low memory and time requirements. Using the default \fBArgon2i\fP
options might cause out-of-memory errors when multiple encrypted volumes are
unlocked automatically at boot through \fB/etc/crypttab\fP. In case the system
runs in FIPS mode, \fB\-\-pbkdf pbkdf2\fP is used instead, because \fBArgon2i\fP
might be disabled by a policy when FIPS mode is active. Because PAES uses secure
AES keys as volume keys, the security of the key derivation function used to
encrypt the volume key in the LUKS key slots is of less relevance.
.P
For LUKS2 volumes, a passphrase is required. You are prompted for the
passphrase when running the generated commands, unless option
.B \-\-key\-file
is specified, or a dummy passphrase is associated with the secure key. Option
.B \-\-tries
specifies how often a passphrase can be re-entered. When option
.B \-\-key\-file
is specified, the passphrase is read from the specified file. You can specify
options
.B \-\-keyfile\-offset
and
.B \-\-keyfile\-size
to control which part of the key file is used as passphrase. These options are
only available if
.B zkey
has been compiled with LUKS2 support enabled. To avoid cryptsetup confirmation
questions, you can specify the
.B \-\-batch\-mode
option. These options are passed to the generated command(s) and behave in the
same way as with \fBcryptsetup\fP.
.
.SS "Convert existing AES secure keys from one key type to another type"
.
.B zkey
.BR convert | con
.I secure\-key\-file
.RB \-\-key\-type | \-K
.IR type
.RB [ \-\-no\-apqn\-check ]
.RB [ \-\-force | \-F ]
.RB [ \-\-verbose | \-V ]
.
.PP
.B zkey
.BR convert | con
.B \-\-name | \-N
.IR key\-name
.RB \-\-key\-type | \-K
.IR type
.RB [ \-\-no\-apqn\-check ]
.RB [ \-\-force | \-F ]
.RB [ \-\-verbose | \-V ]
.
.PP
Use the
.B convert
command to convert an existing secure key from one key type to another type.
You can convert secure keys of type CCA\-AESDATA to type CCA\-AESCIPHER only.
You can not convert keys that are bound to a key management system (KMS).

.B Note:
Secure keys converted to type \fBCCA\-AESCIPHER\fP require an IBM cryptographic
adapter in CCA coprocessor mode of version 6 or later, e.g. a CEX6C.

The secure key can either be contained in a file in the file system, or in a
secure key repository. To convert a secure key contained in a file, specify
the file name with option \fIsecure\-key\-file\fP. To convert a secure key
contained in the secure key repository, specify the name of the key
that is to be converted using the
.B \-\-name
option. You cannot use wildcards. The convert command prompts for
a confirmation, unless you specify the
.B \-\-force
option.
.PP
.B Note:
Converting a secure key is irreversible!
When converting a secure key that is associated with one or multiple volumes,
a message informs you about the associated volumes. When the secure key is
converted, this might have an effect on these volumes.
.P
For volumes with volume type \fBplain\fP, you must adapt the crypttab entries
and change the key size parameter to \fBsize=<new\-key\-size\-in\-bits>\fP or
run command \fBzkey crypttab \-\-volumes <device>\fP for each associated volume
to re-generate the crypttab entries.
.P
Associated volumes of type \fBLUKS2\fP still contain the secure AES volume key
of the original type. To change the secure AES volume key in the LUKS2 header,
run command \fBzkey\-cryptsetup setkey <device> \-\-master\-key\-file
<converted\-key>\fP for each associated volume.
.
.P
.B Note:
The \fBconvert\fP command requires the CCA host library (libcsulcca.so)
to be installed. The required CCA IBM cryptographic adapter firmware version
is 6.3.27 or later. For the supported environments and downloads, see:
\fIhttp://www.ibm.com/security/cryptocards\fP
.
.
.SH COMMANDS FOR KEY MANAGEMENT SYSTEM INTEGRATION
.
Use the \fBkms\fP command to control the integration into key management
systems. The \fBkms\fP command offers several subcommands for key management
specific operations. Use \fBzkey kms \-\-help\fP to show the available
subcommands.
.
.SS "List key management system plugins"
.
.B zkey kms
.BR plugins | pl
.RB [ \-\-verbose | \-V ]
.
.PP
Use the
.B kms plugins
command to display a list of configured key management system plugins (KMS
plugins). It displays the key management system plugin name, and the shared
library that implements the plugin.
.
.P
Key management system plugins are configured in configuration file
\fB/etc/zkey/kms\-plugins.conf\fP. This file contains the KMS plugin name and
its shared library. Set environment variable \fBZKEY_KMS_PLUGINS\fP to point to
a different file to use a different KMS plugin configuration file.
.
.SS "Bind the repository to a key management system"
.
.B zkey kms
.BR bind | bi
.I KMS\-plugin\-name
.RB [ \-\-verbose | \-V ]
.
.PP
Use the
.B kms bind
command to bind the repository to a key management system (KMS).
The \fBkms plugins\fP command displays a list of configured key management
system plugins that can be used.
.
.PP
After binding a repository to a key management system, the KMS plugin must
first be configured. Use the \fBkms configure\fP command to
configure the plugin. As a minimum, you must associate APQNs with the key
management system plugin. The plugin may require additional configuration
before it is fully functioning. Use the \fBkms info\fP command to display
information about the key management system plugin and its configuration.
.
.PP
When a key repository is bound to a key management system, then all keys are
generated by this key management system per default, and are thus also bound to
the key management system. Any additional information associated with the keys
in the repository is also stored in the key management system.
.
.SS "Unbind the repository from a key management system"
.
.B zkey kms
.BR unbind | unb
.RB [ \-\-verbose | \-V ]
.
.PP
Use the
.B kms unbind
command to unbind the repository from a key management system (KMS). All keys
that are currently bound to the key management system, are unbound and become
local keys. You are prompted to confirm the unbinding.
.
.SS "Display information about a key management system plugin"
.
.B zkey kms
.BR info | in
.RB [ \-\-verbose | \-V ]
.
.PP
Use the
.B kms info
command to display information about the currently bound key management system
plugin (KMS plugin) and its configuration.
.
.SS "Configure or re-configure a key management system plugin"
.
.B zkey kms
.BR configure | con
.RB [ \-\-apqns | \-a
.IR [+|\-]card1.domain1[,card2.domain2[,...]] ]
.RB [ KMS-plugin\ specific\ options ]
.RB [ \-\-verbose | \-V ]
.
.PP
Use the
.B kms configure
command to configure or re-configure the currently bound key management system
plugin (KMS plugin). As a minimum, you must associate APQNs with the key
management system plugin. The plugin may require an initial configuration
before it is fully functioning. Once configured, a plugin may allow you to
change some configuration settings.
.PP
A key management system plugin may offer plugin specific options that can be
specified with the \fBkms configure\fP command. Use \fBkms configure
\-\-help\fP to display the plugin specific options and their meaning.
.PP
Configuring a key management system plugin may be a multi-step task. You can
supply all configuration options at once or use the \fBkms configure\fP
command several times supplying only one or a few configuration options each
time, dependent on what the plugin supports. A plugin may also require to
perform additional intermediate steps between two configuration attempts,
e.g. perform tasks in the key management system user interface, or elsewhere.
.PP
Use the \fBkms info\fP command to display information about the key management
system plugin and its current configuration.
.
.SS "Re-encipher secure keys used by a key management system plugin"
.
.B zkey kms
.BR reencipher | re
.RB [ \-\-to\-new | \-n ]
.RB [ \-\-from\-old | \-o ]
.RB [ \-\-in\-place | \-i ]
.RB [ \-\-staged | \-s ]
.RB [ \-\-complete | \-c ]
.RB [ KMS-plugin\ specific\ options ]
.RB [ \-\-verbose | \-V ]
.
.PP
Use the
.B kms reencipher
command to re-encipher secure keys internally used by the currently bound
key management system plugin (KMS plugin) with a new master key. This command
must be run when the master keys of the CCA or EP11 cryptographic adapter,
that are associated with the plugin have been changed. Dependent on what key
types the key management system plugin supports, it may internally use secure
keys with CCA or EP11 cryptographic adapters, or both.
.PP
A key management system plugin may offer plugin specific options that can be
specified with the \fBkms reencipher\fP command. Use \fBkms reencipher
\-\-help\fP to display the plugin specific options and their meaning.
.PP
.B Note:
The \fBkms reencipher\fP command does \fBnot\fP re-encipher secure keys that
have been generated by or have been imported from the key management system
plugin and are stored in the repository. Use the regular \fBreencipher\fP
command to re-encipher those secure keys.
.PP
The CCA cryptographic adapter has three different registers to store
master keys:
.RS 2
.IP "\(bu" 2
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 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. 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
\fBNote:\fP An EP11 cryptographic adapter has only two registers to store master
keys, \fBCURRENT\fP and \fBNEW\fP.
.PP
Use the
.B \-\-from\-old
option to re-encipher a secure key that is currently enciphered with
the master key in the \fBOLD\fP register with the master key in the
\fBCURRENT\fP register. This option is only available for CCA-type secure keys.
.PP
.PP
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
If both options are omitted, the key management system plugin may
automatically detect whether the secure key is currently enciphered with the
master key in the \fBOLD\fP register or with the master key in the \fBCURRENT\fP
register. If currently enciphered with the master key in the \fBOLD\fP register,
it is re-enciphered with the master key in the \fBCURRENT\fP register.
If 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
Re-enciphering a secure key used by a key management system plugin can be
performed \fBin-place\fP, or in \fBstaged\fP mode.
.PP
\fB"In-place"\fP immediately replaces the secure key 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.
A secure key that was re-enciphered in-place from \fBCURRENT\fP to \fBNEW\fP
is no longer valid, until the new CCA or EP11 master key has been made the
current one.
.PP
\fBStaged\fP mode means that the re-enciphered secure key is stored separately.
Thus the current secure key is still valid at this point. Once the new CCA or
EP11 master key has been set (made active), you must rerun the \fBkms
reencipher\fP 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.
.
.SS "List secure keys managed by a key management system"
.
.B zkey kms
.BR list | li
.RB [ \-\-label | \-B
.IR key\-label ]
.RB [ \-\-name | \-N
.IR key\-name ]
.RB [ \-\-volumes | \-l
.IR volume1[:dmname1][,volume2[:dmname2][,...]] ]
.RB [ \-\-volume\-type | \-t
.IR type ]
.RB [ KMS-plugin\ specific\ options ]
.RB [ \-\-verbose | \-V ]
.
.PP
Use the
.B kms list
command to display secure keys managed by a key management system (KMS).
You can filter the displayed list by key label, key name, associated volumes,
and volume type. You can use wildcards for the key label, key name, and
associated volumes. The device-mapper name of an associated volume can be
omitted. If specified, then only those keys are listed that are associated
with the specified volume and device-mapper name.
.PP
A key management system plugin may offer plugin specific options that can be
specified with the \fBkms list\fP command. Use \fBkms list \-\-help\fP
to display the plugin specific options and their meaning.
.PP
The
.B kms list
command displays the attributes of the secure keys, such as key label, key name,
whether it is a secure key that can be used for the XTS cipher mode, the textual
description, associated volumes, the volume type, and sector size.
.
.SS "Import secure keys managed by a key management system into the repository"
.
.B zkey kms
.BR import | im
.RB [ \-\-label | \-B
.IR key\-label ]
.RB [ \-\-name | \-N
.IR key\-name ]
.RB [ \-\-volumes | \-l
.IR volume1[:dmname1][,volume2[:dmname2][,...]] ]
.RB [ \-\-volume\-type | \-t
.IR type ]
.RB [ \-\-batch\-mode | \-q ]
.RB [ \-\-no\-volume\-check ]
.RB [ KMS-plugin\ specific\ options ]
.RB [ \-\-verbose | \-V ]
.
.PP
Use the
.B kms import
command to import secure keys managed by a key management system (KMS) into the
secure key repository.
You can filter the list of keys to be imported by key label, key name,
associated volumes, and volume type. You can use wildcards for the key label,
key name, 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
A key management system plugin may offer plugin specific options that can be
specified with the \fBkms import\fP command. Use \fBkms import \-\-help\fP
to display the plugin specific options and their meaning.
.PP
If a secure key with the same name as a key to be imported already exists in
the repository, then you are prompted to enter an alternate name. You can skip
the import of that key, or enter an alternate name. If option
\fB\-\-batch\-mode\fP is specified, then already existing keys are skipped.
.PP
If a key to be imported is associated with one or multiple volumes, it is
verified that the volumes are available, and are not already associated with
another secure key in the repository. If one of the volumes or all of them are
not available, or are already associated with another secure key, the import
fails. Use option \fB\-\-no\-volume\-check\fP to omit the volume check, and
import the keys even if the associated volume(s) do not exist.
.
.SS "Refresh secure keys that are bound to a key management system"
.
.B zkey kms
.BR refresh | ref
.RB [ \-\-name | \-N
.IR key\-name ]
.RB [ \-\-volumes | \-l
.IR volume1[:dmname1][,volume2[:dmname2][,...]] ]
.RB [ \-\-volume\-type | \-t
.IR type ]
.RB [ \-\-key\-type | \-K
.IR type ]
.RB [ \-\-refresh\-properties | \-P ]
.RB [ \-\-no\-volume\-check ]
.RB [ \-\-verbose | \-V ]
.
.PP
Use the
.B kms refresh
command to refresh secure keys that are bound to a key management system (KMS).
Refreshing a key updates the secure key by re-importing it from the key
management system. Use option \fB\-\-refresh\-properties\fP to also update the
associated information, such as the textual description, associated volumes,
volume type, and sector size, with the information stored in the key management
system.
.PP
You can filter the list of keys to be refreshed by key name, associated volumes,
volume type, and key type. You can use wildcards for the key name, 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
If a refreshed key is associated with one or multiple volumes, it is
verified that the volumes are available, and are not already associated with
another secure key in the repository. If one of the volumes or all of them are
not available, or are already associated with another secure key, the refresh
fails. Use option \fB\-\-no\-volume\-check\fP to omit the volume check, and
refresh the keys even if the associated volume(s) do not exist.
.
.
.SH COMMANDS FOR PROTECTED VIRTUALIZATION
.
Use the \fBpvsecrets\fP command to work with protected virtualization (PV)
secrets. Protected virtualization secrets can be made available to a secure
execution guest and can be used only within that guest.
The \fBpvsecrets\fP command provides subcommands for protected
virtualization specific operations. Use \fBzkey pvsecrets \-\-help\fP to show
the available subcommands. These subcommands only work when running in a
secure execution guest. Only the \fBroot\fP user is allowed to perform these
subcommands.
.
.SS "List available protected virtualization secrets"
.
.B zkey pvsecrets
.BR list | li
.RB [ \-\-all | \-A ]
.RB [ \-\-hex | \-H ]
.RB [ \-\-pvsecret\-type | \-T
.IR pvsecret\-type ]
.RB [ \-\-pvsecret\-id | \-I
.IR pvsecret\-id ]
.RB [ \-\-pvsecret\-name | \-e
.IR pvsecret\-name ]
.RB [ \-\-verbose | \-V ]
.
.PP
Use the
.B pvsecrets list
command to display a list of protected virtualization (PV) secrets. It displays
the pvsecret ID as hex string of 32 bytes or as printable name enclosed in
single quotes (\fB'\fP), if the pvsecret ID consists of only printable
characters. Specify the \fB\-\-hex\fP option to list all pvsecret IDs as hex
string. The
.B pvsecrets list
command also shows the pvsecret type of each secret.
.PP
You can filter the list of pvsecrets by pvsecret ID, pvsecret name and pvsecret
type. Either the \fB\-\-pvsecret\-id\fP option or the
\fB\-\-pvsecret\-name\fP option can be specified. By default the
\fBpvsecrets list\fP command displays only those pvsecrets with types that
are supported by the \fBzkey\fP tool. To list all pvsecret types, specify the
\fB\-\-all\fP option.
.PP
This command is only available when running in a secure execution guest.
Only the \fBroot\fP user is allowed to perform this command.
.
.SS "Import protected virtualization secrets into the repository"
.
.B zkey pvsecrets
.BR import | im
.RB [ \-\-pvsecret\-id | \-I
.IR pvsecret\-id ]
.RB [ \-\-pvsecret\-name | \-e
.IR pvsecret\-name ]
.B \-\-name | \-N
.IR key\-name
.RB [ \-\-description | \-d
.IR description ]
.RB [ \-\-volumes | \-l
.IR volume1:dmname1[,volume2:dmname2[,...]] ]
.RB [ \-\-sector\-size | \-S
.IR bytes ]
.RB [ \-\-volume\-type | \-t
.IR type ]
.RB [ \-\-gen\-dummy\-passphrase ]
.RB [ \-\-set\-dummy\-passphrase
.IR passphrase\-file ]
.RB [ \-\-verbose | \-V ]
.
.PP
Use the
.B pvsecrets import
command to import a protected virtualization (PV) secret into the repository.
Either the \fB\-\-pvsecret\-id\fP option or the \fB\-\-pvsecret\-name\fP
option can be specified. If the pvsecret name is specified, then the
\fB\-\-name\fP option can be omitted. The name of the protected virtualization
secret key object in the repository will then be the same as the pvsecret name.
.PP
You can use the YAML file that was created when using the \fBpvsecret create\fP
command for adding the protected virtualization secret:
\fB\-\-pvsecret\-id "$(yq .id \fP\fIYAML\-FILE\fP\fB)"\fP or
\fB\-\-pvsecret\-name "$(yq .name \fP\fIYAML\-FILE\fP\fB)"\fP.
You might have to install the \fByq\fP package first.
.PP
A protected virtualization secret key object does not contain the key material,
but only a reference (i.e. the secret ID) to the key in the ultravisor.
When such a protected virtualization secret key object is used with
\fBdm\-crypt\fP and the \fBPAES\fP kernel cipher, the key material (i.e. a
protected key) is retrieved from the ultravisor and the crypto operation is
performed with it.
.PP
When importing a protected virtualization secret in a key repository,
additional information can be associated with it using the
.B \-\-description
,
.B \-\-volumes
, or the
.B \-\-sector\-size
options. APQNs can not be associated, because protected virtualization secrets
do not require a crypto card.
.PP
This command is only available when running in a secure execution guest.
Only the \fBroot\fP user is allowed to perform this command.
.
.
.
.
.SH OPTIONS
.SS "Options for the generate command"
.TP
.BR \-k ", " \-\-keybits\~\fIsize\fP
Specifies the size of the AES key to be generated in bits.
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 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.
If option \fB\-\-keybits\fP is omitted, the size of the specified file
determines the size of the AES key. If option \fB\-\-keybits\fP
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.
When the secure key is generated using a key management system, then this option
can not be specified.
.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 \fBdm\-crypt\fP with the secure AES key. The volume association
also contains the device-mapper name, separated by a colon, used with
\fBdm\-crypt\fP.
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 or EP11
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 online APQN is used to generate the key. If no APQNs are
specified, then an APQN is selected automatically. All specified APQNs must be
online, unless the \fB\-\-no\-apqn\-check\fP option is specified.
This option is only used for secure keys contained in the secure key repository.
When the secure key is generated using a key management system, then this option
can not be specified.
.TP
.BR \-\-no\-apqn\-check
Do not check if the specified APQNs are available. Use this option to
associate APQNs with a secure AES key that are currently not available.
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 \fBdm\-crypt\fP. It must be a power
of two and in the range of 512 to 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.
.TP
.BR \-t ", " \-\-volume\-type\~\fItype\fP
Specifies the volume type of the associated volumes used with \fBdm\-crypt\fP.
Possible values are \fBplain\fP and \fBluks2\fP. If omitted, \fBluks2\fP is
used.
This option is only available if
.B zkey
has been compiled with LUKS2 support enabled. If LUKS2 support is not enabled,
the default volume type is \fBplain\fP.
This option is only used for secure keys contained in the secure key repository.
.TP
.BR \-K ", " \-\-key\-type\~\fItype\fP
Specifies the key type of the secure key. Possible values are
\fBCCA\-AESDATA\fP, \fBCCA\-AESCIPHER\fP, and \fBEP11\-AES\fP. If this option
is omitted, then a secure key of type CCA\-AESDATA is generated.
Secure keys of type \fBCCA\-AESCIPHER\fP require an IBM cryptographic adapter
in CCA coprocessor mode of version 6 or later, e.g. a CEX6C.
Secure keys of type \fBEP11\-AES\fP require an IBM cryptographic adapter
in EP11 coprocessor mode of version 7 or later, e.g. a CEX7P.
.TP
.BR \-L ", "\-\-local
Generate the secure AES key locally. This is the default when no key management
system plugin (KMS plugin) is bound to the secure key repository. If the
repository is bound to a key management system plugin, then keys are generated
using the key management system by default.
.TP
.BR \-\-gen\-dummy\-passphrase
Generate a dummy passphrase randomly and associate it with the secure AES key
used to encrypt LUKS2 volume(s). The LUKS2 passphrase is of less or no relevance
for the security of the volume(s), when an secure AES key is used to encrypt the
volume(s), and can therefore be stored insecurely inside the secure key
repository. If for a certain usage the passphrase is of relevance for
security, then do not use this option. This option can only be specified for
keys with a volume type of \fBluks2\fP.
This option is only used for secure keys contained in the secure key repository.
.TP
.BR \-\-set\-dummy\-passphrase\~\fIpassphrase\-file\fP
Set a dummy passphrase that is read from the specified file and associate it
with the secure AES key used to encrypt LUKS2 volume(s). The LUKS2 passphrase
is of less or no relevance for the security of the volume(s), when an secure
AES key is used to encrypt the volume(s), and can therefore be stored insecurely
inside the secure key repository. If for a certain usage the passphrase is of
relevance for security, then do not use this option. This option can only be
specified for keys with a volume type of \fBluks2\fP.
This option is only used for secure keys contained in the secure key repository.
.TP
.B KMS-plugin specific options
A key management system plugin may offer and even require plugin specific
options that can be specified with the generate command when the secure key
repository is bound to a key management system plugin. Use \fBgenerate
\-\-help\fP to display the plugin specific options and their meaning.
.
.
.
.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.
.TP
.BR \-a ", " \-\-apqns\~\fIcard1.domain1[,card2.domain2[,...]]\fP
Specifies a comma-separated list of cryptographic adapters in CCA or EP11
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 validated.
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 \-\-no\-apqn\-check
Do not check if the associated APQNs are available.
This option is only used for secure keys contained in the secure key repository.
.
.
.
.SS "Options for the reencipher command"
.TP
.BR \-n ", " \-\-to\-new
Re-enciphers a secure AES key that is currently enciphered with the
master key in the CURRENT register with the master key in the NEW register.
.TP
.BR \-o ", " \-\-from\-old
Re-enciphers a secure AES key that is currently enciphered with the
master key in the OLD register with the master key in the CURRENT register.
This option is only available for secure keys of type CCA\-AESDATA and
CCA\-AESCIPHER.
.TP
.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. 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 or EP11
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 or EP11 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 or EP11
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 \fBdm\-crypt\fP with the secure AES key. The volume association
also contains the device-mapper name, separated by a colon, used with
\fBdm\-crypt\fP.
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 or EP11
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,
unless option \fB\-\-no\-apqn\-check\fP is specified.
This option is only used for secure keys contained in the secure key repository.
.TP
.BR \-\-no\-apqn\-check
Do not check if the specified APQNs are available. Use this option to
associate APQNs with a secure AES key that are currently not available.
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 \fBdm\-crypt\fP. It must be a
power of two and in the range of 512 to 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.
.TP
.BR \-t ", " \-\-volume\-type\~\fItype\fP
Specifies the volume type of the associated volumes used with \fBdm\-crypt\fP.
Possible values are \fBplain\fP and \fBluks2\fP. If omitted, \fBluks2\fP is
used.
This option is only available if
.B zkey
has been compiled with LUKS2 support enabled. If LUKS2 support is not enabled,
the default volume type is \fBplain\fP.
This option is only used for secure keys contained in the secure key repository.
.TP
.BR \-\-gen\-dummy\-passphrase
Generate a dummy passphrase randomly and associate it with the secure AES key
used to encrypt LUKS2 volume(s). The LUKS2 passphrase is of less or no relevance
for the security of the volume(s), when an secure AES key is used to encrypt the
volume(s), and can therefore be stored insecurely inside the secure key
repository. If for a certain usage the passphrase is of relevance for
security, then do not use this option. This option can only be specified for
keys with a volume type of \fBluks2\fP.
This option is only used for secure keys contained in the secure key repository.
.TP
.BR \-\-set\-dummy\-passphrase\~\fIpassphrase\-file\fP
Set a dummy passphrase that is read from the specified file and associate it
with the secure AES key used to encrypt LUKS2 volume(s). The LUKS2 passphrase
is of less or no relevance for the security of the volume(s), when an secure
AES key is used to encrypt the volume(s), and can therefore be stored insecurely
inside the secure key repository. If for a certain usage the passphrase is of
relevance for security, then do not use this option. This option can only be
specified for keys with a volume type of \fBluks2\fP.
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 \fBdm\-crypt\fP. 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 or EP11
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.
.TP
.BR \-t ", " \-\-volume\-type\~\fItype\fP
Specifies the volume type of the associated volumes used with \fBdm\-crypt\fP.
Possible values are \fBplain\fP and \fBluks2\fP. Only keys with the specified
volume type are listed.
This option is only available if
.B zkey
has been compiled with LUKS2 support enabled.
This option is only used for secure keys contained in the secure key repository.
.TP
.BR \-K ", " \-\-key\-type\~\fItype\fP
Specifies the key type of the secure key. Possible values are
\fBCCA\-AESDATA\fP, \fBCCA\-AESCIPHER\fP, and \fBEP11\-AES\fP. Only keys with
the specified key type are listed.
This option is only used for secure keys contained in the secure key repository.
.TP
.BR \-L ", " \-\-local\fP
Lists only local keys. Local keys are not bound to a key management system
(KMS).
This option is only used for secure keys contained in the secure key repository,
and can not be specified together with the
.BR \-\-kms\-bound
option.
.TP
.BR \-M ", " \-\-kms\-bound\fP
Lists only keys that are bound to a key management system (KMS).
This option is only used for secure keys contained in the secure key repository,
and can not be specified together with the
.BR \-\-local
option.
.
.
.
.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.
.TP
.B KMS-plugin specific options
A key management system plugin may offer and even require plugin specific
options that can be specified with the remove command when the secure key
repository is bound to a key management system plugin. Use \fBremove
\-\-help\fP to display the plugin specific options and their meaning.
.
.
.
.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 \fBdm\-crypt\fP with the secure AES key. The volume association
also contains the device-mapper name, separated by a colon, used with
\fBdm\-crypt\fP.
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 or EP11
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, unless option
\fB\-\-no\-apqn\-check\fP is specified.
This option is only used for secure keys contained in the secure key repository.
.TP
.BR \-\-no\-apqn\-check
Do not check if the specified APQNs are available. Use this option to
associate APQNs with a secure AES key that are currently not available.
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 \fBdm\-crypt\fP. It must be a power
of two and in the range of 512 to 4096 bytes. Specify \fI0\fP to set the sector
size to the system default.
This option is only used for secure keys contained in the secure key repository.
.TP
.BR \-t ", " \-\-volume\-type\~\fItype\fP
Specifies the volume type of the associated volumes used with \fBdm\-crypt\fP.
Possible values are \fBplain\fP and \fBluks2\fP.
This option is only available if
.B zkey
has been compiled with LUKS2 support enabled.
This option is only used for secure keys contained in the secure key repository.
.TP
.BR \-\-gen\-dummy\-passphrase
Generate a dummy passphrase randomly and associate it with the secure AES key
used to encrypt LUKS2 volume(s). The LUKS2 passphrase is of less or no relevance
for the security of the volume(s), when an secure AES key is used to encrypt the
volume(s), and can therefore be stored insecurely inside the secure key
repository. If for a certain usage the passphrase is of relevance for
security, then do not use this option. This option can only be specified for
keys with a volume type of \fBluks2\fP. When there is already a dummy
passphrase associated with the key, you must first remove the dummy passphrase
with option \fB\-\-remove\-dummy\-passphrase\fP before you can associate a new
dummy passphrase.
This option is only used for secure keys contained in the secure key repository.
.TP
.BR \-\-set\-dummy\-passphrase\~\fIpassphrase\-file\fP
Set a dummy passphrase that is read from the specified file and associate it
with the secure AES key used to encrypt LUKS2 volume(s). The LUKS2 passphrase
is of less or no relevance for the security of the volume(s), when an secure
AES key is used to encrypt the volume(s), and can therefore be stored insecurely
inside the secure key repository. If for a certain usage the passphrase is of
relevance for security, then do not use this option. This option can only be
specified for keys with a volume type of \fBluks2\fP. When there is already a
dummy passphrase associated with the key, you must first remove the dummy
passphrase with option \fB\-\-remove\-dummy\-passphrase\fP before you can
associate a new dummy passphrase.
This option is only used for secure keys contained in the secure key repository.
.TP
.BR \-\-remove\-dummy\-passphrase
Remove the associated dummy passphrase used with LUKS2 volume(s).
The user is prompted to confirm the removal of the associated dummy passphrase.
Use the \fB\-\-force\fP option to remove the associated dummy passphrase without
prompting for a confirmation.
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 the associated dummy passphrase.
Use this option to remove the associated dummy passphrase without prompting for
a confirmation.
This option is only used for secure keys contained in the secure key repository,
and can only be specified together with option
\fB\-\-remove\-dummy\-passphrase\fP.
.
.
.
.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\fBdm\-crypt\fP with the secure AES key.
The volume association also contains the device-mapper name, separated by a
colon, used with \fBdm\-crypt\fP.
This option is only used for secure keys contained in the secure key repository.
.TP
.BR \-L ", "\-\-local
Copy the secure key to a local key. This is the default when no key management
system plugin (KMS plugin) is bound to the secure key repository. If the
repository is bound to a key management system plugin, then the keys are bound
to the KMS per default, and KMS-bound keys can only be copied to local keys.
.
.
.
.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 \fBdm\-crypt\fP. 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 \-t ", " \-\-volume\-type\~\fItype\fP
Specifies the volume type of the associated volumes used with \fBdm\-crypt\fP.
Possible values are \fBplain\fP and \fBluks2\fP. Only keys with the specified
volume type are selected to generate crypttab entries for.
This option is only available if
.B zkey
has been compiled with LUKS2 support enabled.
This option is only used for secure keys contained in the secure key repository.
.TP
.BR \-\-key\-file\~\fIfile\-name\fP
Reads the passphrase from the specified file. If this option is omitted, and
no dummy passphrase is associated with the secure key, then you are prompted to
enter the passphrase interactively during system startup.
This option is passed to the generated crypttab entries for LUKS2 volumes, and
is only available if
.B zkey
has been compiled with LUKS2 support enabled.
.TP
.BR \-\-keyfile\-offset\~\fIbytes\fP
Specifies the number of bytes to skip before starting to read in the file
specified with option \fB\-\-key\-file\fP. If omitted, the file is read
from the beginning. When option \fB\-\-key\-file\fP is not specified, this
option is ignored. This option is passed to the generated crypttab entries
for LUKS2 volumes, and is only available if
.B zkey
has been compiled with LUKS2 support enabled. Not all distributions support the
.B keyfile\-offset
option in crypttab entries.
.TP
.BR \-\-keyfile\-size\~\fIbytes\fP
Specifies the number of bytes to be read from the beginning of the file
specified with option \fB\-\-key\-file\fP. If omitted, the file is read
until the end. When \fB\-\-keyfile\-offset\fP is also specified, reading starts
at the offset. When option \fB\-\-key\-file\fP is not specified, this option is
ignored. This option is passed to the generated crypttab entries for LUKS2
volumes, and is only available if
.B zkey
has been compiled with LUKS2 support enabled. Not all distributions support the
.B keyfile\-size
option in crypttab entries.
.TP
.BR \-\-tries\~\fInumber\fP
Specifies how often the interactive input of the passphrase can be re-entered
during system startup. The default is 3 times. When option \fB\-\-key\-file\fP
is specified, this option is ignored, and the passphrase is read only once from
the file. This option is passed to the generated crypttab entries for LUKS2
volumes, and is only available if
.B zkey
has been compiled with LUKS2 support enabled.
.
.
.
.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 \fBdm\-crypt\fP. 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 \-t ", " \-\-volume\-type\~\fItype\fP
Specifies the volume type of the associated volumes used with \fBdm\-crypt\fP.
Possible values are \fBplain\fP and \fBluks2\fP. Only keys with the specified
volume type are selected to generate cryptsetup commands for.
This option is only available if
.B zkey
has been compiled with LUKS2 support enabled.
This option is only used for secure keys contained in the secure key repository.
.TP
.BR \-r ", " \-\-run
Runs the generated cryptsetup commands. When one of the cryptsetup commands
fail, no further cryptsetup commands are run, and zkey ends with an error.
This option is only used for secure keys contained in the secure key repository.
.TP
.BR \-\-open
Generates \fBcryptsetup luksOpen\fP or \fBcryptsetup plainOpen\fP commands.
For a plain volume type, this is the default. This option can not be specified
together with the
.BR \-\-format
option, and is only available if
.B zkey
has been compiled with LUKS2 support enabled.
.TP
.BR \-\-format
Generates \fBcryptsetup luksFormat\fP commands. For a LUKS2 volume type, this
is the default. If specified for a plain volume type, then no command is
generated. This option can not be specified together with the
.BR \-\-open
option, and is only available if
.B zkey
has been compiled with LUKS2 support enabled.
.TP
.BR \-\-key\-file\~\fIfile\-name\fP
Reads the passphrase from the specified file. If this option is omitted, and
no dummy passphrase is associated with the secure key, or if the file\-name is
\fI\-\fP (a dash), then you are prompted to enter the passphrase interactively.
This option is passed to the generated command(s) for LUKS2 volumes, and is
only available if
.B zkey
has been compiled with LUKS2 support enabled.
.TP
.BR \-\-keyfile\-offset\~\fIbytes\fP
Specifies the number of bytes to skip before starting to read in the file
specified with option \fB\-\-key\-file\fP. If omitted, the file is read
from the beginning. When option \fB\-\-key\-file\fP is not specified, this
option is ignored. This option is passed to the generated command(s)
for LUKS2 volumes, and is only available if
.B zkey
has been compiled with LUKS2 support enabled.
.TP
.BR \-\-keyfile\-size\~\fIbytes\fP
Specifies the number of bytes to be read from the beginning of the file
specified with option \fB\-\-key\-file\fP. If omitted, the file is read
until the end. When \fB\-\-keyfile\-offset\fP is also specified, reading starts
at the offset. When option \fB\-\-key\-file\fP is not specified, this option is
ignored. This option is passed to the generated command(s) for LUKS2 volumes,
and is only available if
.B zkey
has been compiled with LUKS2 support enabled.
.TP
.BR \-\-tries\~\fInumber\fP
Specifies how often the interactive input of the passphrase can be re-entered.
The default is 3 times. When option \fB\-\-key\-file\fP is specified, this
option is ignored, and the passphrase is read only once from the file.
This option is passed to the generated command(s) for LUKS2 volumes, and is
only available if
.B zkey
has been compiled with LUKS2 support enabled.
.TP
.BR \-q ", " \-\-batch\-mode
Suppress cryptsetup confirmation questions. This option is passed to the
generated cryptsetup command(s).
.
.
.
.SS "Options for the convert 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 \-K ", " \-\-key\-type\~\fItype\fP
Specifies the key type to which the secure key shall be converted to.
Possible values are \fBCCA\-AESCIPHER\fP. Secure keys of type
\fBCCA\-AESCIPHER\fP require an IBM cryptographic adapter in CCA coprocessor
mode of version 6 or later, e.g. a CEX6C.
.TP
.BR \-\-no\-apqn\-check
Do not check if the associated APQNs are available and capable of converting
the secure key to type CCA\-AESCIPHER.
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 conversion of a secure key. Use this option
to convert a secure key without prompting for a confirmation.
.
.
.
.SS "Options for the kms configure command"
.TP
.BR \-a ", " \-\-apqns\~\fI[+|\-]card1.domain1[,card2.domain2[,...]]\fP
Specifies a comma-separated list of cryptographic adapters in CCA or EP11
coprocessor mode (APQN) which are associated with the key management system
plugin. 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.
.TP
.B KMS-plugin specific options
A key management system plugin may offer plugin specific options that can be
specified with the kms configure command. Use \fBkms configure \-\-help\fP to
display the plugin specific options and their meaning.
.
.
.
.SS "Options for the kms reencipher command"
.TP
.BR \-n ", " \-\-to\-new
Re-enciphers key management system plugin internal secure keys that are
currently enciphered with the master key in the CURRENT register with the
master key in the NEW register.
.TP
.BR \-o ", " \-\-from\-old
Re-enciphers key management system plugin internal secure keys that are
currently enciphered with the master key in the OLD register with the master
key in the CURRENT register.
This option is only available for CCA-type secure keys.
.TP
.BR \-i ", " \-\-in\-place
Forces an in-place re-enciphering of key management system plugin internal
secure keys. "in-place" immediately replaces the secure key with the
re-enciphered secure key. Re-enciphering from OLD to CURRENT is performed
in-place per default.
.TP
.BR \-s ", " \-\-staged
Forces that the re-enciphering of key management system plugin internal secure
keys is performed in staged mode. Staged mode means that the re-enciphered
secure keys are stored separately. Thus the current secure keys are still valid
at this point. Once the new CCA or EP11 master keys have been set (made active),
you must rerun the \fBkms reencipher\fP 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.
.TP
.BR \-p ", " \-\-complete
Completes a staged re-enciphering. Use this option after the new CCA or EP11
master keys have been set (made active). This option replaces the secure keys by
their re-enciphered versions.
.TP
.B KMS-plugin specific options
A key management system plugin may offer plugin specific options that can be
specified with the kms reencipher command. Use \fBkms reencipher \-\-help\fP to
display the plugin specific options and their meaning.
.
.
.
.SS "Options for the kms list command"
.TP
.BR \-B ", " \-\-label\~\fIkey\-label\fP
Specifies the label of the secure key in the key management system (KMS).
You can use wildcards to select multiple secure keys.
When wildcards are used you must quote the value.
Only keys with labels that match the pattern are listed.
.TP
.BR \-N ", " \-\-name\~\fIkey\-name\fP
Specifies the name of the secure key in the key management system (KMS).
You can use wildcards to select multiple secure keys.
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 key management system (KMS). 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 \fBdm\-crypt\fP. 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.
.TP
.BR \-t ", " \-\-volume\-type\~\fItype\fP
Specifies the volume type of the associated volumes used with \fBdm\-crypt\fP.
Possible values are \fBplain\fP and \fBluks2\fP. Only keys with the specified
volume type are listed.
This option is only available if
.B zkey
has been compiled with LUKS2 support enabled.
.
.
.
.SS "Options for the kms import command"
.TP
.BR \-B ", " \-\-label\~\fIkey\-label\fP
Specifies the label of the secure key in the key management system (KMS).
You can use wildcards to select multiple secure keys.
When wildcards are used you must quote the value.
Only keys with labels that match the pattern are imported.
.TP
.BR \-N ", " \-\-name\~\fIkey\-name\fP
Specifies the name of the secure key in the key management system (KMS).
You can use wildcards to select multiple secure keys.
When wildcards are used you must quote the value.
Only keys with names that match the pattern are imported.
.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 key management system (KMS). Only
those keys are imported, which are associated with the specified volumes.
The volume association also contains the device-mapper name, separated by a
colon, used with \fBdm\-crypt\fP. 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.
.TP
.BR \-t ", " \-\-volume\-type\~\fItype\fP
Specifies the volume type of the associated volumes used with \fBdm\-crypt\fP.
Possible values are \fBplain\fP and \fBluks2\fP. Only keys with the specified
volume type are imported.
This option is only available if
.B zkey
has been compiled with LUKS2 support enabled.
.TP
.BR \-q ", " \-\-batch\-mode
Suppress prompts to skip or to enter an alternate name, if a secure key with the
same name as the secure key to be imported already exists in the repository.
When this option is specified, then keys with an existing name are skipped.
.TP
.BR \-\-no\-volume\-check
Do not check if the volume(s) associated with the to be imported secure key(s)
are available, or are already associated with other secure keys in the
repository.
.
.
.
.SS "Options for the kms refresh 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 refreshed.
.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
refreshed, which are associated with the specified volumes.
The volume association also contains the device-mapper name, separated by a
colon, used with \fBdm\-crypt\fP. 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.
.TP
.BR \-t ", " \-\-volume\-type\~\fItype\fP
Specifies the volume type of the associated volumes used with \fBdm\-crypt\fP.
Possible values are \fBplain\fP and \fBluks2\fP. Only keys with the specified
volume type are refreshed.
This option is only available if
.B zkey
has been compiled with LUKS2 support enabled.
.TP
.BR \-K ", " \-\-key\-type\~\fItype\fP
Specifies the key type of the secure key. Possible values are
\fBCCA\-AESDATA\fP, \fBCCA\-AESCIPHER\fP, and \fBEP11\-AES\fP. Only keys with
the specified key type are refreshed.
.TP
.BR \-P ", " \-\-refresh\-properties
Also update the associated information, such as the textual description,
associated volumes, volume type, and sector size, with the information stored in
the key management system.
.TP
.BR \-\-no\-volume\-check
Do not check if the volume(s) associated with the secure key(s) to be refreshed
are available, or are already associated with other secure keys in the
repository. This option only has an effect when specified together with option
\fB\-\-refresh\-properties\fP.
.
.
.
.SS "Options for the pvsecrets list command"
.TP
.BR \-A ", " \-\-all
List all protected virtualization (PV) secret types, not only those that can be
used with zkey.
.TP
.BR \-H ", " \-\-hex
Show all protected virtualization (PV) secret IDs in hex, even if the ID
contains only printable characters.
.TP
.BR \-T ", " \-\-pvsecret\-type\~\fIpvsecret\-type\fP
Type of the protected virtualization (PV) secret to list. If omitted, all
secret types are listed. Possible values are: \fBPLAIN\-TEXT\fP, \fBAES\-128\fP,
\fBAES\-192\fP, \fBAES\-256\fP, \fBAES\-XTS\-128\fP, \fBAES\-XTS\-256\fP,
\fBHMAC\-SHA\-256\fP, \fBHMAC\-SHA\-512\fP, \fBECDSA\-P256\fP,
\fBECDSA\-P384\fP, \fBECDSA\-P521\fP, \fBEDDSA\-ED25519\fP, and
\fBEDDSA\-ED448\fP.
.TP
.BR \-I ", " \-\-pvsecret\-id\~\fIpvsecret\-id\fP
ID of the protected virtualization (PV) secret to list. The pvsecret ID is a 32
byte hex string, optionally prefixed by \fB0x\fP. You can use the YAML file that
was created when using the \fBpvsecret create\fP command for adding the
protected virtualization secret:
\fB\-\-pvsecret\-id "$(yq .id \fP\fIYAML\-FILE\fP\fB)"\fP.
You might have to install the \fByq\fP package first.
Either the \fB\-\-pvsecret\-id\fP option or the \fB\-\-pvsecret\-name\fP option
can be specified, but not both.
.TP
.BR \-e ", " \-\-pvsecret\-name\~\fIpvsecret\-name\fP
Name of the protected virtualization (PV) secret to list. You can use the YAML
file that was created when using the \fBpvsecret create\fP command for adding
the protected virtualization secret:
\fB\-\-pvsecret\-name "$(yq .name \fP\fIYAML\-FILE\fP\fB)"\fP.
You might have to install the \fByq\fP package first.
Either the \fB\-\-pvsecret\-id\fP option or the \fB\-\-pvsecret\-name\fP option
can be specified, but not both.
.
.
.
.SS "Options for the pvsecrets import command"
.TP
.BR \-I ", " \-\-pvsecret\-id\~\fIpvsecret\-id\fP
ID of the protected virtualization (PV) secret to import. The pvsecret ID is a
32 byte hex string, optionally prefixed by \fB0x\fP. You can use the YAML file
that was created when using the \fBpvsecret create\fP command for adding the
protected virtualization secret:
\fB\-\-pvsecret\-id "$(yq .id \fP\fIYAML\-FILE\fP\fB)"\fP.
You might have to install the \fByq\fP package first.
Either the \fB\-\-pvsecret\-id\fP option or the \fB\-\-pvsecret\-name\fP option
can be specified, but not both.
.TP
.BR \-e ", " \-\-pvsecret\-name\~\fIpvsecret\-name\fP
Name of the protected virtualization (PV) secret to import. You can use the YAML
file that was created when using the \fBpvsecret create\fP command for adding
the protected virtualization secret:
\fB\-\-pvsecret\-name "$(yq .name \fP\fIYAML\-FILE\fP\fB)"\fP.
You might have to install the \fByq\fP package first.
Either the \fB\-\-pvsecret\-id\fP option or the \fB\-\-pvsecret\-name\fP option
can be specified, but not both. If the \fB\-\-pvsecret\-name\fP option is
specified, then the \fB\-\-name\fP option can be omitted. The name of the
protected virtualization secret key object in the repository will then be the
same as the pvsecret name.
.TP
.BR \-N ", " \-\-name\~\fIkey\-name\fP
Specifies the name of the protected virtualization secret key object in the key
repository. If the \fB\-\-pvsecret\-name\fP option is specified, then the
\fB\-\-name\fP option can be omitted. The name of the protected virtualization
secret in the repository will then be the same as the pvsecret name.
.TP
.BR \-d ", " \-\-description\~\fIdescription\fP
Specifies a textual description for the protected virtualization secret in the
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 protected virtualization secret in the repository. These
volumes are to be encrypted using \fBdm\-crypt\fP with the protected
virtualization secret. The volume association also contains the device-mapper
name, separated by a colon, used with \fBdm\-crypt\fP. A specific volume can
only be associated with a single key.
.TP
.BR \-S ", " \-\-sector\-size\~\fIbytes\fP
Specifies the sector size in bytes used with \fBdm\-crypt\fP. It must be a power
of two and in the range of 512 to 4096 bytes. If omitted, the system default
sector size is used.
.TP
.BR \-t ", " \-\-volume\-type\~\fItype\fP
Specifies the volume type of the associated volumes used with \fBdm\-crypt\fP.
Possible values are \fBplain\fP and \fBluks2\fP. If omitted, \fBluks2\fP is
used. This option is only available if
.B zkey
has been compiled with LUKS2 support enabled. If LUKS2 support is not enabled,
the default volume type is \fBplain\fP.
.TP
.BR \-\-gen\-dummy\-passphrase
Generate a dummy passphrase randomly and associate it with the protected
virtualization secret used to encrypt LUKS2 volume(s). The LUKS2 passphrase is
of less or no relevance for the security of the volume(s), when a protected
virtualization secret is used to encrypt the volume(s), and can therefore be
stored insecurely inside the key repository. If for a certain usage the
passphrase is of relevance for security, then do not use this option. This
option can only be specified for keys with a volume type of \fBluks2\fP.
.TP
.BR \-\-set\-dummy\-passphrase\~\fIpassphrase\-file\fP
Set a dummy passphrase that is read from the specified file and associate it
with the protected virtualization secret used to encrypt LUKS2 volume(s).
The LUKS2 passphrase is of less or no relevance for the security of the
volume(s), when an protected virtualization secret is used to encrypt the
volume(s), and can therefore be stored insecurely inside the key repository.
If for a certain usage the passphrase is of relevance for security, then do
not use this option. This option can only be specified for keys with a volume
type of \fBluks2\fP.
.
.
.
.SS "General options"
.TP
.BR \-V ", " \-\-verbose
Displays additional information messages during processing.
.TP
.BR \-h ", " \-\-help
Displays help text and exits.
.TP
.BR \-v ", " \-\-version
Displays version information and exits.
.
.
.
.SH EXAMPLES
.TP
.B zkey generate 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 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 using the name 'seckey'.
.TP
.B zkey generate \-\-name seckey \-\-volumes /dev/dasdc1:encvol
.B \-\-apqns 03.004c
Generates a random 256-bit secure AES key and stores it in the secure key
repository using the name 'seckey' and associates it with block
device '/dev/dasdc1' and device-mapper name 'encvol', and APQN '03.004c'.
.TP
.B zkey generate \-\-name seckey \-\-volumes /dev/dasdc1:encvol
.B \-\-volume\-type luks2
Generates a random 256-bit secure AES key and stores it in the secure key
repository using the name 'seckey' and associates it with block
device '/dev/dasdc1' and device-mapper name 'encvol', and a volume type of
luks2.
.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
register, and replaces the secure key in file 'seckey.bin' with the
re-enciphered key.
.TP
.B zkey reencipher seckey.bin \-\-to\-new \-\-output seckey2.bin
Re-enciphers the secure key in file 'seckey.bin' which is currently enciphered
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'.
.TP
.B zkey cryptsetup \-\-volume\-type luks2
Generates cryptsetup commands for all volumes of type luks2.
.
.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.
.TP
.BR ZKEY_KMS_PLUGINS
If
.B $ZKEY_KMS_PLUGINS
is set, it specifies the name of the KMS plugin configuration file.
If it is not set, then the default KMS plugin configuration file
\fB/etc/zkey/kms\-plugins.conf\fP is used.