mirror of
https://github.com/ibm-s390-linux/s390-tools.git
synced 2026-08-05 02:14:52 +00:00
a9059449b9
Add the definitions and utility functions for the PVSECRET-HMAC key type. A PVSECRET-HMAC key token contains the secret id of a protected virtualization secret. It does not contain the key material, just a reference to the key in the ultravisor. When such a key token is used to perform HMAC operations later on, the PHMAC kernel cipher will obtain the protected key belonging to this secret id with the help of the pkey 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>
584 lines
21 KiB
Groff
584 lines
21 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 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 [ \-\-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.
|
|
.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 \-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.
|