.\" Copyright IBM Corp. 2018, 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\-CRYPTSETUP 1 "February 2024" "s390-tools"
.SH NAME
zkey\-cryptsetup \- Manage secure AES or HMAC volume keys of volumes encrypted
with \fBLUKS2\fP and the \fBpaes\fP cipher, and optionally integrity protected
with the \fBphmac\fP cipher.
.
.
.SH SYNOPSIS
.B zkey\-cryptsetup
.I command
.I device
.RI [ OPTIONS ]
.
.PP
.B zkey\-cryptsetup
.RI [ command ]
.BR \-\-help | \-h
.br
.B zkey\-cryptsetup
.BR \-\-version | \-v
.
.
.
.SH DESCRIPTION
Use \fBzkey\-cryptsetup\fP to validate and re-encipher secure AES or HMAC
volume keys of volumes encrypted with \fBLUKS2\fP and the \fBpaes\fP cipher,
and optionally integrity protected with the \fBphmac\fP cipher.
These secure AES or HMAC volume keys are enciphered with a master key of an IBM
cryptographic adapter in CCA or EP11 coprocessor mode.
.PP
To encrypt a volume using \fBLUKS2\fP and the \fBpaes\fP cipher, generate a
secure AES key using \fBzkey\fP: \fB'zkey generate luks.key \-\-xts'\fP.
Then format the device with \fBcryptsetup\fP using the just generated secure
AES key from file luks.key: \fB'cryptsetup luksFormat <device> \-\-type luks2
\-\-cipher paes\-xts\-plain64 \-\-volume\-key\-file luks.key
\-\-key\-size 1024'\fP. For more details about \fBzkey\fP or \fBcryptsetup\fP
see the corresponding man pages.
.
.
.
.SH COMMANDS
.
.
.SS "Validate secure AES or HMAC volume keys"
.
.B zkey\-cryptsetup
.BR validate | val
.I device
.RB [ \-\-key\-file | \-d
.IR file\-name ]
.RB [ \-\-keyfile\-offset | \-o
.IR bytes ]
.RB [ \-\-keyfile\-size | \-l
.IR bytes ]
.RB [ \-\-tries | \-T
.IR number ]
.RB [ \-\-verbose | \-V ]
.RB [ \-\-debug | \-D ]
.PP
Use the
.B validate
command to validate a secure AES or HMAC volume key of a volume encrypted with
\fBLUKS2\fP and the \fBpaes\fP cipher, and optionally integrity protected with
the \fBphmac\fP cipher.
It checks if the LUKS2 header of the volume contains a valid secure key.
It also displays the attributes of the secure key, such as key size, whether
it is a secure key that can be used for the XTS cipher mode, and the master key
register (CURRENT or OLD) with which the secure key is enciphered. The same
appplies to a secure integrity key, if present.
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
To open a key slot contained in the LUKS2 header of the volume, a passphrase is
required. You are prompted for the passphrase, unless option
.B \-\-key\-file
is specified. Option
.B \-\-tries
specifies how often a passphrase can be re-entered. When option
.B \-\-key\-file
is specified, the passphrase is read from the specified file. You can specify
options
.B \-\-keyfile\-offset
and
.B \-\-keyfile\-size
to control which part of the key file is used as passphrase. These options
behave in the same way as with \fBcryptsetup\fP.
.
.SS "Re-encipher secure AES or HMAC volume keys"
.
.PP
.B zkey\-cryptsetup
.BR reencipher | re
.I device
.RB [ \-\-to\-new | \-N ]
.RB [ \-\-from\-old | \-O ]
.RB [ \-\-staged | \-s ]
.RB [ \-\-in\-place | \-i ]
.RB [ \-\-complete | \-c ]
.RB [ \-\-key\-file | \-d
.IR file\-name ]
.RB [ \-\-keyfile\-offset | \-o
.IR bytes ]
.RB [ \-\-keyfile\-size | \-l
.IR bytes ]
.RB [ \-\-tries | \-T
.IR number ]
.RB [ \-\-batch\-mode | \-q ]
.RB [ \-\-verbose | \-V ]
.RB [ \-\-debug | \-D ]
.PP
Use the
.B reencipher
command to re-encipher a secure AES or HMAC volume key of a volume encrypted
with \fBLUKS2\fP and the \fBpaes\fP cipher, and optionally integrity protected
with the \fBphmac\fP cipher. A secure AES or HMAC volume key must be
re-enciphered when the master key of the cryptographic adapter in CCA or EP11
coprocessor mode changes.
.PP
Volume 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 key of a cryptographic adapter
changes.
.PP
The cryptographic adapter in CCA coprocessor mode 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 volume 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 volume 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.
.RE
.PP
If both options are omitted, \fBzkey\-cryptsetup\fP automatically detects
whether the secure volume 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
Re-enciphering a secure volume key of a volume encrypted with
\fBLUKS2\fP and the \fBpaes\fP cipher, and optionally integrity protected with
the \fBphmac\fP cipher, can be performed \fBin-place\fP, or in
\fBstaged\fP mode.
.PP
\fB"In-place"\fP immediately replaces the secure volume key in the LUKS2
header of the encrypted volume with the re-enciphered secure volume 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
an encrypted volume with a secure volume key that was re-enciphered in-place
from \fBCURRENT\fP to \fBNEW\fP is no longer usable, until the new CCA or EP11
master key has been made the current one.
.PP
\fBStaged\fP mode means that the re-enciphered secure volume key is stored in a
separate (unbound) key slot in the LUKS2 header of the encrypted volume. Thus
all key slots containing the current secure volume key are 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. When completing the staged re-enciphering, the (unbound)
key slot containing the re-enciphered secure volume key becomes the active
key slot and, optionally, all key slots containing the old secure volume key
are removed.
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
To open a key slot contained in the LUKS2 header of the volume, a passphrase is
required. You are prompted for the passphrase, unless option
.B \-\-key\-file
is specified. Option
.B \-\-tries
specifies how often a passphrase can be re-entered. When option
.B \-\-key\-file
is specified, the passphrase is read from the specified file. You can specify
options
.B \-\-keyfile\-offset
and
.B \-\-keyfile\-size
to control which part of the key file is used as passphrase. These options
behave in the same way as with \fBcryptsetup\fP.
.PP
The
.B reencipher
command creates a new key slot with the re-enciphered secure AES or HMAC volume
key. The new key slot uses
.B PBKDF2
as password based key derivation function. LUKS2 volumes typically default to
.B Argon2i
as password based key derivation function,
but this might cause out-of-memory errors when multiple encrypted volumes are
unlocked automatically at boot through /etc/crypttab. Because PAES and PHMAC
uses secure AES or HMAC 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.
.PP
.B Note:
The \fBreencipher\fP command requires the CCA host library (libcsulcca.so)
for secure volume keys of type CCA\-AESDATA or CCA\-AESCIPHER, or the IBM Z
Enterprise PKCS #11 (EP11) Support Program (EP11 host library) for secure volume
keys of type EP11\-AES to be installed. For the supported environments and
downloads, see: \fIhttp://www.ibm.com/security/cryptocards\fP
.
.
.
.SS "Set a verification pattern of the secure AES or HMAC volume key"
.
.B zkey\-cryptsetup
.BR setvp | setv
.I device
.RB [ \-\-key\-file | \-d
.IR file\-name ]
.RB [ \-\-keyfile\-offset | \-o
.IR bytes ]
.RB [ \-\-keyfile\-size | \-l
.IR bytes ]
.RB [ \-\-tries | \-T
.IR number ]
.RB [ \-\-verbose | \-V ]
.RB [ \-\-debug | \-D ]
.PP
Use the
.B setvp
command to set a verification pattern of the secure AES or HMAC volume key of a
volume encrypted with \fBLUKS2\fP and the \fBpaes\fP cipher, and optionally
integrity protected with the \fBphmac\fP cipher. The verification pattern
identifies the effective key used to encrypt or integrity protect the volume's
data.
The verification pattern is stored in a token named
\fBpaes\-verification\-pattern\fP in the LUKS2 header.
.PP
.B Note:
Set the verification pattern right after formatting the volume using
\fB'cryptsetup luksFormat'\fP.
.PP
To open a key slot contained in the LUKS2 header of the volume, a passphrase is
required. You are prompted for the passphrase, unless option
.B \-\-key\-file
is specified. Option
.B \-\-tries
specifies how often a passphrase can be re-entered. When option
.B \-\-key\-file
is specified, the passphrase is read from the specified file. You can specify
options
.B \-\-keyfile\-offset
and
.B \-\-keyfile\-size
to control which part of the key file is used as passphrase. These options
behave in the same way as with \fBcryptsetup\fP.
.
.
.
.SS "Set a new secure AES or HMAC volume key for a volume"
.
.B zkey\-cryptsetup
.BR setkey | setk
.I device
.BR \-\-volume\-key\-file | \-m
.IR file\-name
.RB [ \-\-key\-file | \-d
.IR file\-name ]
.RB [ \-\-keyfile\-offset | \-o
.IR bytes ]
.RB [ \-\-keyfile\-size | \-l
.IR bytes ]
.RB [ \-\-tries | \-T
.IR number ]
.RB [ \-\-batch\-mode | \-q ]
.RB [ \-\-verbose | \-V ]
.RB [ \-\-debug | \-D ]
.PP
Use the
.B setkey
command to set a new secure AES volume key for a volume encrypted with
\fBLUKS2\fP and the \fBpaes\fP cipher, and optionally integrity protected with
the \fBphmac\fP cipher. Use this command to recover from an invalid secure AES
or HMAC volume key contained in the LUKS2 header.
A secure AES or HMAC volume key contained in the LUKS2 header can become invalid
when the CCA or EP11 master key is changed without re-enciphering the secure
volume key.
.PP
You can recover the secure volume key only if you have a copy of the secure key
in a file, and this copy was re-enciphered when the CCA or EP11 master key has
been changed. Thus, the copy of the secure key must be currently enciphered with
the CCA or EP11 master key in the CURRENT or OLD master key register.
Specify the secure key file with option
.B \-\-volume\-key\-file
to set this secure key as the new volume key.
.PP
In case the LUKS2 header of the volume contains a verification pattern token,
it is used to ensure that the new volume key contains the same effective key.
If no verification pattern token is available, then you are prompted to confirm
that the specified secure key is the correct one.
.B ATTENTION:
If you set a wrong secure key you will loose all the data on the encrypted
volume!
.PP
To open a key slot contained in the LUKS2 header of the volume, a passphrase is
required. You are prompted for the passphrase, unless option
.B \-\-key\-file
is specified. Option
.B \-\-tries
specifies how often a passphrase can be re-entered. When option
.B \-\-key\-file
is specified, the passphrase is read from the specified file. You can specify
options
.B \-\-keyfile\-offset
and
.B \-\-keyfile\-size
to control which part of the key file is used as passphrase. These options
behave in the same way the same as with \fBcryptsetup\fP.
.PP
The
.B setkey
command creates a new key slot with the re-enciphered secure AES volume key.
The new key slot uses
.B PBKDF2
as password based key derivation function. LUKS2 volumes typically default to
.B Argon2i
as password based key derivation function,
but this might cause out-of-memory errors when multiple encrypted volumes are
unlocked automatically at boot through /etc/crypttab. 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.
.
.
.
.SS "Convert a clear-key LUKS2 volume to use a secure AES or HMAC volume key"
.
.B zkey\-cryptsetup
.BR convert | conv
.I device
.BR \-\-volume\-key\-file | \-m
.IR file\-name
.RB [ \-\-integrity\-key\-size | \-I
.IR bytes ]
.RB [ \-\-key\-file | \-d
.IR file\-name ]
.RB [ \-\-keyfile\-offset | \-o
.IR bytes ]
.RB [ \-\-keyfile\-size | \-l
.IR bytes ]
.RB [ \-\-tries | \-T
.IR number ]
.RB [ \-\-batch\-mode | \-q ]
.RB [ \-\-verbose | \-V ]
.RB [ \-\-debug | \-D ]
.PP
Use the
.B convert
command to convert a clear-key \fBLUKS2\fP volume to use a secure volume key
and the \fBpaes\fP cipher, optionally integrity protected with the
\fBphmac\fP cipher. You must provide a secure volume key that uses
the exact same effective key as the current volume key. The volume must not be
open when a conversion is performed, otherwise it fails.
.PP
.B ATTENTION:
It is strongly recommended to take a LUKS header backup using \fBcryptsetup
luksHeaderBackup\fP before converting a volume. The volume might not be
recoverable after a failing conversion, if you don't have a LUKS header backup.
.PP
Specify the secure key file with option
.B \-\-volume\-key\-file
to convert the volume to use this secure key as the new volume key.
When the volume uses integrity protection, and you want to also use a secure
integrity key, then concatenate the secure AES encryption key and the secure
HMAC key, and specify the result as volume key. You must then also specify the
size of the secure HMAC key in bytes using the
.B \-\-integrity\-key\-size
option. This will then convert the integrity algorithm to use the \fBphmac\fP
cipher.
.PP
To open a key slot contained in the LUKS2 header of the volume, a passphrase is
required. You are prompted for the passphrase, unless option
.B \-\-key\-file
is specified. Option
.B \-\-tries
specifies how often a passphrase can be re-entered. When option
.B \-\-key\-file
is specified, the passphrase is read from the specified file. You can specify
options
.B \-\-keyfile\-offset
and
.B \-\-keyfile\-size
to control which part of the key file is used as passphrase. These options
behave in the same way the same as with \fBcryptsetup\fP.
.PP
The
.B convert
command creates a new key slot with the specified secure AES volume key.
The new key slot uses the same password based key derivation function as
the key slot that is used to open the volume. LUKS2 volumes typically default to
.B Argon2i
as password based key derivation function,
but this might cause out-of-memory errors when multiple encrypted volumes are
unlocked automatically at boot through /etc/crypttab. 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. Use \fBcryptsetup luksConvertKey --pbkdf pbkdf2\fP to convert
the key slot(s) to use \fBPBKDF2\fP as password based key derivation function
after the conversion.
.
.
.
.
.SH OPTIONS
.
.SS "Options for the reencipher command"
.TP
.BR \-N ", " \-\-to\-new
Re-enciphers a secure volume key in the LUKS2 header 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 volume key in the LUKS2 header that is currently
enciphered with the master key in the OLD register with the master key in the
CURRENT register.
.TP
.BR \-i ", " \-\-in\-place
Forces an in-place re-enciphering of a secure volume key in the LUKS2
header. This option immediately replaces the secure volume key in the LUKS2
header of the encrypted volume with the re-enciphered secure volume key.
Re-enciphering from \fBOLD\fP to \fBCURRENT\fP is performed in-place per
default.
.TP
.BR \-s ", " \-\-staged
Forces that the re-enciphering of a secure volume key in the LUKS2
header is performed in staged mode. Staged mode means that the re-enciphered
secure volume key is stored in a separate (unbound) key slot in the LUKS2
header of the encrypted volume. Thus all key slots containing the current
secure volume key are 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.
.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). When completing the staged
re-enciphering, the (unbound) key slot containing the re-enciphered secure
volume key becomes the active key slot and, optionally, all key slots containing
the old secure volume key are removed.
.TP
.BR \-q ", " \-\-batch\-mode
Suppresses all confirmation questions. Use with care!
.
.
.
.SS "Options for the setkey command"
.TP
.BR \-m ", " \-\-volume\-key\-file\~\fIfile\-name\fP
Specifies the name of a file containing the secure AES key (and optionally a
secure HMAC key) that is set as the new volume key.
.TP
.BR \-\-master\-key\-file\~\fIfile\-name\fP
Alias for the
.BR \-\-volume\-key\-file\~\fIfile\-name\fP
option.
.TP
.BR \-q ", " \-\-batch\-mode
Suppresses all confirmation questions. Use with care!
.
.
.
.SS "Options for the convert command"
.TP
.BR \-m ", " \-\-volume\-key\-file\~\fIfile\-name\fP
Specifies the name of a file containing the secure AES key that is used as
volume key for the converted volume.
.TP
.BR \-\-master\-key\-file\~\fIfile\-name\fP
Alias for the
.BR \-\-volume\-key\-file\~\fIfile\-name\fP
option.
.TP
.BR \-I ", " \-\-integrity\-key\-size\~\fIbytes\fP
Specifies the size of the secure HMAC key part in bytes.
.TP
.BR \-q ", " \-\-batch\-mode
Suppresses all confirmation questions. Use with care!
.
.
.
.SS "Options for supplying the passphrase"
.TP
.BR \-d ", " \-\-key\-file\~\fIfile\-name\fP
Reads the passphrase from the specified file. If this option is omitted,
or if the file\-zkey\-cryptsetup \fI\-\fP (a dash), then you are prompted to
enter the passphrase interactively.
.TP
.BR \-o ", " \-\-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.
.TP
.BR \-l ", " \-\-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.
.TP
.BR \-T ", " \-\-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.
.
.
.
.SS "General options"
.TP
.BR \-V ", " \-\-verbose
Displays additional information messages during processing.
.TP
.BR \-D ", " \-\-debug
Displays additional debugging messages during processing. This option also
implies \fB\-\-verbose\fP.
.TP
.BR \-h ", " \-\-help
Displays help text and exits.
.TP
.BR \-v ", " \-\-version
Displays version information and exits.
.
.
.
.SH EXAMPLES
.TP
.B zkey\-cryptsetup reencipher /dev/dasdd1
Re-enciphers the secure volume key of the encrypted volume /dev/dasdd1.
.TP
.B zkey\-cryptsetup reencipher /dev/dasdd1 \-\-staged
Re-enciphers the secure volume key of the encrypted volume /dev/dasdd1 in
staged mode.
.TP
.B zkey\-cryptsetup reencipher /dev/dasdd1 \-\-complete
Completes re-enciphers the secure volume key of the encrypted
volume /dev/dasdd1.
.TP
.B zkey\-cryptsetup reencipher /dev/dasdd1 \-\-in\-place
Re-enciphers the secure volume key of the encrypted volume /dev/dasdd1 in
in-place mode.
.TP
.B zkey\-cryptsetup validate /dev/dasdd1
Validates the secure volume key of the encrypted volume /dev/dasdd1 and
displays its attributes.
.TP
.B zkey\-cryptsetup setvp /dev/dasdd1
Sets the verification pattern of the secure volume key of the encrypted
volume /dev/dasdd1.
.TP
.B zkey\-cryptsetup setkey /dev/dasdd1 \-\-volume\-key\-file seckey.key
Sets the secure key contained in file seckey.key as the new volume key
for the encrypted volume /dev/dasdd1.