mirror of
https://github.com/ibm-s390-linux/s390-tools.git
synced 2026-08-05 02:14:52 +00:00
103a99fa34
The commands 'zkey cryptsetup' generates commands for formatting and opening volumes of type PLAIN and LUKS2. For LUKS2, if there exists an HMAC key that is associated to the same volume as the AES key, generate a 'cryptsetup luksFormat' command for combined encryption and integrity protection. This uses the '--integrity' and '--integrity-key-size' options of the 'cryptsetup luksFormat' command to specify the integrity settings. The volume key specified with '--master-key-file' must contain the encryption key and the integrity key concatenated to each other. The size of the volume key specified with '--key-size' however must be the size of the encryption key only, in bits. The 'cryptsetup luksFormat' command will internally read the whole file, use the first part as encryption key, and the second part as integrity key. The size of the second part must be specified with the '--integrity-key-size'. Note: This requires 'wrapped integrity key' support in the cryptsetup package, as well as in the dm-crypt kernel module. Signed-off-by: Ingo Franzki <ifranzki@linux.ibm.com> Reviewed-by: Finn Callies <fcallies@linux.ibm.com> Signed-off-by: Jan Höppner <hoeppner@linux.ibm.com>
2553 lines
108 KiB
Groff
2553 lines
108 KiB
Groff
.\" 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 or HMAC 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 or HMAC 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 or HMAC 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 or are integrity
|
|
protected using \fBdm\-integrity\fP with the secure key. The volume association
|
|
also contains the device-mapper name, separated by a colon, used with
|
|
\fBdm\-crypt\fP or \fBdm\-integrity\fP. A specific volume can only be associated
|
|
with one secure key. Keys of type AES are used for disk encryption, while keys
|
|
of type HMAC are used for integrity protection. Combined encryption and
|
|
integrity protetion is possible with \fBLUKS2\fP. Here, the same volume can be
|
|
associated to an AES-type key and an HMAC-type 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 or HMAC 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 [ \-\-exportable ]
|
|
.RB [ \-\-wrap\-with\-trusted ]
|
|
.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 [ \-\-exportable ]
|
|
.RB [ \-\-wrap\-with\-trusted ]
|
|
.RB [ KMS-plugin\ specific\ options ]
|
|
.RB [ \-\-verbose | \-V ]
|
|
.PP
|
|
Use the
|
|
.B generate
|
|
command to generate a new secure AES or HMAC key either randomly within the CCA
|
|
or EP11 cryptographic adapter, from a clear AES or HMAC 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.
|
|
.PP
|
|
By default, secure keys of type \fBCCA\-AESCIPHER\fP and \fBEP11\-AES\fP are
|
|
export restricted when generated by zkey. Keys of type \fBCCA\-AESDATA\fP can
|
|
not be export restricted. Export restricted means that the secure keys can not
|
|
be wrapped by a key encrypting key (KEK), and thus can not escape the
|
|
protection of the IBM cryptographic adapter (HSM). If exportability is required
|
|
for a secure key of type \fBCCA\-AESCIPHER\fP or \fBEP11\-AES\fP, specify
|
|
option \fB\-\-exportable\fP. This makes the generated secure keys exportable.
|
|
Additionally, for keys of type \fBEP11\-AES\fP option
|
|
\fB\-\-wrap\-with\-trusted\fP can be specified to allow wrapping only with a
|
|
trusted KEK. When the secure key repository is bound to a key management system
|
|
plugin (KMS plugin), options \fB\-\-exportable\fP and
|
|
\fB\-\-wrap\-with\-trusted\fP are not allowed, except the \fB\-\-local\fP option
|
|
is specified.
|
|
|
|
.PP
|
|
.B Note:
|
|
For keys of type \fBEP11\-AES\fP to be exportable, the access control point
|
|
(ACP) \fBXCP_CPB_ALLOW_COMBINED_EXTRACT\fP must be \fBON\fP on all APQNs used.
|
|
This access control point is only supported on newer EP11 firmware levels. If
|
|
the access control point is \fBOFF\fP or not supported by the EP11 firmware,
|
|
key generation fails with a generic error (Input/output error). The \fBzkey\fP
|
|
tool prints an appropriate error message in that case.
|
|
.
|
|
.SS "Validating secure AES or HMAC 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. Keys of type \fBPVSECRET\-AES\fP and
|
|
\fBPVSECRET\-HMAC\fP do not use a cryptographic adapter, thus no master key
|
|
information is displayed for such keys.
|
|
.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 or HMAC 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 and \fBPVSECRET\-HMAC\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 or HMAC 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 [ \-\-exportable ]
|
|
.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 and \fBPVSECRET\-HMAC\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
|
|
.PP
|
|
By default, secure keys of type \fBCCA\-AESCIPHER\fP are changed to be export
|
|
restricted during the import operation. Export restricted means that the secure
|
|
keys can not be wrapped by a key encrypting key (KEK), and thus can not escape
|
|
the protection of the IBM cryptographic adapter (HSM). If exportability of an
|
|
imported key is required, specify option \fB\-\-exportable\fP. The import
|
|
operation will then not change the exportability of the secure key.
|
|
.
|
|
.SS "Export AES or HMAC 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 or HMAC 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 or HMAC 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 or HMAC 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 or HMAC 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 and \fBPVSECRET\-HMAC\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 or HMAC 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 or HMAC 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 AES 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.
|
|
.PP
|
|
.B Note:
|
|
Use the
|
|
.B integritytab
|
|
command to generate integritytab entries for volumes using the \fBintegrity\fP
|
|
volume type that are associated with secure HMAC keys contained in the
|
|
secure key repository.
|
|
.
|
|
.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 AES 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 combined encryption and integrity protection of a volume, the same volume
|
|
must be assigned to an AES-type key and an HMAC-type key. Both keys must use the
|
|
\fBluks2\fP volume type. For such a volume, the generated \fBcryptsetup
|
|
luksFormat\fP command contains the \fB\-\-integrity\fP option to enable
|
|
integrity protection. An additional command is generated prior to the
|
|
\fBcryptsetup luksFormat\fP command to concatenate the encryption key and the
|
|
integrity key to each other into a temporary file. This temporary file is then
|
|
used with the \fBcryptsetup luksFormat\fP command as volume key. When the
|
|
\fP\-\-run\fP option is specified, the temporary file is removed automatically
|
|
after running the commands, otherwise a command to remove the temporary file is
|
|
generated, too.
|
|
.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.
|
|
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.
|
|
.PP
|
|
.B Note:
|
|
Use the
|
|
.B integritysetup
|
|
command to generate \fBintegritysetup format\fP and \fBintegritysetup open\fP
|
|
commands for volumes using the \fBintegrity\fP volume type that are associated
|
|
with secure HMAC keys contained in the
|
|
secure key repository.
|
|
.
|
|
.SS "Generate integritytab entries for volumes associated with secure HMAC keys"
|
|
.
|
|
.B zkey
|
|
.BR integritytab | integrityt
|
|
.RB [ \-\-volumes | \-l
|
|
.IR volume1[:dmname1][,volume2[:dmname2][,...]] ]
|
|
.RB [ \-\-verbose | \-V ]
|
|
.
|
|
.PP
|
|
Use the
|
|
.B integritytab
|
|
command to generate integritytab entries using \fBdm\-integrity\fP for volumes
|
|
that are associated with secure HMAC keys contained in the secure key
|
|
repository. Only HMAC keys with a volume type of \fBintegrity\fP are considered.
|
|
Specify the
|
|
.B \-\-volumes
|
|
option to limit the list
|
|
of volumes where integritytab 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.
|
|
.PP
|
|
.B Note:
|
|
Use the
|
|
.B crypttab
|
|
command to generate crypttab entries for volumes using the \fBplain\fP or
|
|
\fBluks2\fP volume type that are associated with secure AES keys contained in
|
|
the secure key repository.
|
|
.
|
|
.SS "Generate integritysetup commands for volumes associated with secure HMAC keys"
|
|
.
|
|
.B zkey
|
|
.BR integritysetup | integritys
|
|
.RB [ \-\-volumes | \-l
|
|
.IR volume1[:dmname1][,volume2[:dmname2][,...]] ]
|
|
.RB [ \-\-run | \-r ]
|
|
.RB [ \-\-open ]
|
|
.RB [ \-\-batch\-mode | \-q ]
|
|
.RB [ \-\-verbose | \-V ]
|
|
.
|
|
.PP
|
|
Use the
|
|
.B integritysetup
|
|
command to generate \fBintegritysetup format\fP, or \fBintegritysetup open\fP
|
|
commands for volumes that are associated with secure HMAC keys contained in the
|
|
secure key repository. Only HMAC keys with a volume type of \fBintegrity\fP are
|
|
considered. Specify the
|
|
.B \-\-volumes
|
|
option to limit the list
|
|
of volumes where integritysetup commands are generated for. You can use
|
|
wildcards. When wildcards are used you must quote the value.
|
|
The device-mapper name of an associated volume can be omitted; if it is
|
|
specified then only those volumes with the specified volume and device-mapper
|
|
name are selected.
|
|
Specify the
|
|
.B \-\-run
|
|
option to run the generated integritysetup commands. Specify the
|
|
.B \-\-open
|
|
to generate \fBintegritysetup open\fP commands. By default \fBintegritysetup
|
|
format\fP commands are generated.
|
|
To avoid integritysetup confirmation questions, you can specify the
|
|
.B \-\-batch\-mode
|
|
option. These option is passed to the generated command(s) and behave in the
|
|
same way as with \fBintegritysetup\fP.
|
|
.PP
|
|
.B Note:
|
|
Use the
|
|
.B cryptsetup
|
|
command to generate\fBcryptsetup plainOpen\fP, \fBcryptsetup luksOpen\fP, or
|
|
\fBcryptsetup luksFormat\fP commands for volumes using the \fBplain\fP or
|
|
\fBluks2\fP volume types that are associated with secure AES keys contained in
|
|
the secure key repository.
|
|
.
|
|
.SS "Convert existing AES or HMAC 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 [ \-\-exportable ]
|
|
.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 or HMAC
|
|
volume key of the original type. To change the secure AES or HMAC volume key in
|
|
the LUKS2 header, run command \fBzkey\-cryptsetup setkey <device>
|
|
\-\-volume\-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
|
|
.PP
|
|
By default, secure keys are changed to be export restricted during the convert
|
|
operation. Export restricted means that the secure keys can not be wrapped by a
|
|
key encrypting key (KEK), and thus can not escape the protection of the IBM
|
|
cryptographic adapter (HSM). If exportability of a converted key is required,
|
|
specify option \fB\-\-exportable\fP. The convert operation will then not change
|
|
the exportability of the secure key.
|
|
.
|
|
.
|
|
.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, or \fBdm\-integrity\fP and
|
|
the \fBPHMAC\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.
|
|
For combined encryption and integrity protection of a volume associate the same
|
|
volume to an AES-type key and an HMAC-type key. Both keys must use the
|
|
\fBluks2\fP volume type.
|
|
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.
|
|
You can only set a sector size for an HMAC key of a volume of type
|
|
\fBintegrity\fP. For an HMAC key that is used for combined encryption and
|
|
integrity protection (volume type \fBluks2\fP), set the sector size for the
|
|
corresponding AES key instead.
|
|
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 or
|
|
\fBdm\-integrity\fP. Possible values for AES keys are \fBplain\fP and
|
|
\fBluks2\fP, and \fBintegrity\fP and \fBluks2\fP for HMAC keys. If omitted,
|
|
\fBluks2\fP is used for AES keys, and \fBintegrity\fP for HMAC keys.
|
|
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
|
|
AES-type 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 AES-type 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 or HMAC 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 or HMAC 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 or HMAC 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 or HMAC 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 or HMAC key in the repository. These volumes are
|
|
to be encrypted using \fBdm\-crypt\fP with the secure AES key, or are to be
|
|
integrity protected using \fBdm\-integrity\fP with the secure HMAC key. The
|
|
volume association also contains the device-mapper name, separated by a colon,
|
|
used with \fBdm\-crypt\fP or \fBdm\-integrity\fP.
|
|
A specific volume can only be associated with a single secure key.
|
|
For combined encryption and integrity protection of a volume associate the same
|
|
volume to an AES-type key and an HMAC-type key. Both keys must use the
|
|
\fBluks2\fP volume type.
|
|
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 or HMAC 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 or HMAC 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 or
|
|
\fBdm\-integrity\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.
|
|
You can only set a sector size for an HMAC key of a volume of type
|
|
\fBintegrity\fP. For an HMAC key that is used for combined encryption and
|
|
integrity protection (volume type \fBluks2\fP), set the sector size for the
|
|
corresponding AES key instead.
|
|
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 or
|
|
\fBdm\-integrity\fP. Possible values for AES keys are \fBplain\fP and
|
|
\fBluks2\fP, and \fBintegrity\fP and \fBluks2\fP for HMAC keys. If omitted,
|
|
\fBluks2\fP is used for AES keys, and \fBintegrity\fP for HMAC keys.
|
|
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
|
|
AES-type 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 AES-type 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 or HMAC 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 or \fBdm\-integrity\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 or HMAC 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 or
|
|
\fBdm\-integrity\fP. Possible values for AES keys are \fBplain\fP and
|
|
\fBluks2\fP, and \fBintegrity\fP and \fBluks2\fP for HMAC keys.
|
|
Only keys with the specified volume type are listed.
|
|
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, \fBEP11\-AES\fP, \fBPVSECRET\-AES\fP,
|
|
and \fBPVSECRET\-HMAC\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 or HMAC key in the repository. These volumes are
|
|
to be encrypted using \fBdm\-crypt\fP with the secure AES key, or are to be
|
|
integrity protected using \fBdm\-integrit\fP with the secure HMAC key. The
|
|
volume association also contains the device-mapper name, separated by a colon,
|
|
used with \fBdm\-crypt\fP or \fBdm\-integrity\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.
|
|
For combined encryption and integrity protection of a volume associate the same
|
|
volume to an AES-type key and an HMAC-type key. Both keys must use the
|
|
\fBluks2\fP volume type.
|
|
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 or HMAC 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 or HMAC 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 or
|
|
\fBdm\-integrity\fP. It must be a power of two and in the range of 512 to 4096
|
|
ytes. Specify \fI0\fP to set the sector size to the system default.
|
|
You can only set a sector size for an HMAC key of a volume of type
|
|
\fBintegrity\fP. For an HMAC key that is used for combined encryption and
|
|
integrity protection (volume type \fBluks2\fP), set the sector size for the
|
|
corresponding AES key instead.
|
|
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 or
|
|
\fBdm\-integrity\fP. Possible values for AES keys are \fBplain\fP and
|
|
\fBluks2\fP, and \fBintegrity\fP and \fBluks2\fP for HMAC keys.
|
|
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
|
|
AES-type 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 AES-type 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 or HMAC 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, or are to be integrity protected using \fBdm\-integrity\fP with
|
|
the secure HMAC key. The volume association also contains the device-mapper
|
|
name, separated by a colon, used with \fBdm\-crypt\fP or \fBdm\-integrity\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 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.
|
|
.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. 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. 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.
|
|
.
|
|
.
|
|
.
|
|
.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 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.
|
|
.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.
|
|
.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.
|
|
.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.
|
|
.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.
|
|
.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.
|
|
.TP
|
|
.BR \-q ", " \-\-batch\-mode
|
|
Suppress cryptsetup confirmation questions. This option is passed to the
|
|
generated cryptsetup command(s).
|
|
.
|
|
.
|
|
.
|
|
.SS "Options for the integritytab command"
|
|
.TP
|
|
.BR \-l ", " \-\-volumes\~\fIvolume1[:dmname1][,volume2[:dmname2][,...]]\fP
|
|
Specifies a comma-separated list of volumes (block devices) which are
|
|
associated with secure HMAC keys in the repository. Only HMAC keys with a
|
|
volume type of \fBintegrity\fP are considered.
|
|
The volume association also contains the device-mapper name, separated by a
|
|
colon, used with \fBdm\-integrity\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.
|
|
.
|
|
.
|
|
.
|
|
.SS "Options for the integritysetup command"
|
|
.TP
|
|
.BR \-l ", " \-\-volumes\~\fIvolume1[:dmname1][,volume2[:dmname2][,...]]\fP
|
|
Specifies a comma-separated list of volumes (block devices) which are
|
|
associated with secure HMAC keys in the repository. Only HMAC keys with a
|
|
volume type of \fBintegrity\fP are considered.
|
|
The volume association also contains the device-mapper name, separated by a
|
|
colon, used with \fBdm\-integrity\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 \-r ", " \-\-run
|
|
Runs the generated integritysetup commands. When one of the integritysetup
|
|
commands fail, no further integritysetup 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 \fBintegritysetup open\fP commands. By default \fBintegritysetup
|
|
format\fP commands are generated.
|
|
.TP
|
|
.BR \-q ", " \-\-batch\-mode
|
|
Suppress integritysetup confirmation questions. This option is passed to the
|
|
generated integritysetup 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 or HMAC 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 or \fBdm\-integrity\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 or
|
|
\fBdm\-integrity\fP. Possible values for AES keys are \fBplain\fP and
|
|
\fBluks2\fP, and \fBintegrity\fP and \fBluks2\fP for HMAC keys. Only keys
|
|
with the specified volume type are listed.
|
|
.
|
|
.
|
|
.
|
|
.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 or HMAC 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 or \fBdm\-integrity\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 or
|
|
\fBdm\-integrity\fP. Possible values for AES keys are \fBplain\fP and
|
|
\fBluks2\fP, and \fBintegrity\fP and \fBluks2\fP for HMAC keys. Only keys
|
|
with the specified volume type are imported.
|
|
.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 or HMAC 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 or \fBdm\-integrity\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 or
|
|
\fBdm\-integrity\fP. Possible values for AES keys are \fBplain\fP and
|
|
\fBluks2\fP, and \fBintegrity\fP and \fBluks2\fP for HMAC keys. Only keys
|
|
with the specified volume type are refreshed.
|
|
.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, or are to be integrity protected using
|
|
\fBdm\-integrity\fP with the protected virtualization secret. The volume
|
|
association also contains the device-mapper name, separated by a colon, used
|
|
with \fBdm\-crypt\fP or \fBdm\-integrity\fP. A specific volume can only be
|
|
associated with a single key. For combined encryption and integrity protection
|
|
of a volume associate the same volume to an AES-type key and an HMAC-type key.
|
|
Both keys must use the \fBluks2\fP volume type.
|
|
.TP
|
|
.BR \-S ", " \-\-sector\-size\~\fIbytes\fP
|
|
Specifies the sector size in bytes used with \fBdm\-crypt\fP or
|
|
\fBdm\-integrity\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.
|
|
You can only set a sector size for an HMAC key of a volume of type
|
|
\fBintegrity\fP. For an HMAC key that is used for combined encryption and
|
|
integrity protection (volume type \fBluks2\fP), set the sector size for the
|
|
corresponding AES key instead.
|
|
.TP
|
|
.BR \-t ", " \-\-volume\-type\~\fItype\fP
|
|
Specifies the volume type of the associated volumes used with \fBdm\-crypt\fP or
|
|
\fBdm\-integrity\fP. Possible values for AES keys are \fBplain\fP and
|
|
\fBluks2\fP, and \fBintegrity\fP and \fBluks2\fP for HMAC keys. If omitted,
|
|
\fBluks2\fP is used for AES keys, and \fBintegrity\fP for HMAC keys. If
|
|
omitted, \fBluks2\fP is used.
|
|
.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 AES-type 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 AES-type 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.
|