mirror of
https://github.com/ibm-s390-linux/s390-tools.git
synced 2026-08-05 02:14:52 +00:00
c80a0c8af0
Starting with cryptsetup version 2.5.0 the luksFormat command accepts option '--volume-key-file' to specify the volume key file. Option '--master-key-file' is still accepted as an alias to '--volume-key-file'. Follow this pattern with the zkey-cryptsetup tool and also accept both options '--volume-key-file' and '--master-key-file'. The short option form stays '-m' for compatibility reasons (cryptsetup does not have a short option for that). Signed-off-by: Ingo Franzki <ifranzki@linux.ibm.com> Reviewed-by: Jorg Schmidbauer <jschmidb@de.ibm.com> Signed-off-by: Jan Höppner <hoeppner@linux.ibm.com>
490 lines
17 KiB
Groff
490 lines
17 KiB
Groff
.\" 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 volume keys of volumes encrypted with
|
|
\fBLUKS2\fP and the \fBpaes\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
|
|
volume keys of volumes encrypted with \fBLUKS2\fP and the \fBpaes\fP cipher.
|
|
These secure AES 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 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 volume key of a volume encrypted with
|
|
\fBLUKS2\fP and the \fBpaes\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.
|
|
For further information about master key registers, see the
|
|
\fBreencipher\fP command. Keys of type \fBPVSECRET\-AES\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 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 volume key of a volume encrypted with
|
|
\fBLUKS2\fP and the \fBpaes\fP cipher. A secure AES 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 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 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 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.
|
|
.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 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 volume key of a volume
|
|
encrypted with \fBLUKS2\fP and the \fBpaes\fP cipher. The verification pattern
|
|
identifies the effective key used to encrypt 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 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. Use this command to recover from an
|
|
invalid secure AES volume key contained in the LUKS2 header.
|
|
A secure AES 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.
|
|
.
|
|
.
|
|
.
|
|
.
|
|
.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 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 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.
|