forked from pool/s390-tools
a7f8ed0265
Lots of features implemented for SLES15 SP1. OBS-URL: https://build.opensuse.org/request/show/648783 OBS-URL: https://build.opensuse.org/package/show/Base:System/s390-tools?expand=0&rev=57
444 lines
16 KiB
Diff
444 lines
16 KiB
Diff
Subject: zkey: Add man page for zkey-cryptsetup
|
|
From: Ingo Franzki <ifranzki@linux.ibm.com>
|
|
|
|
Summary: zkey: Support CCA master key change with LUKS2 volumes using paes
|
|
Description: Support the usage of protected key crypto for dm-crypt disks in
|
|
LUKS2 format by providing a tool allowing to re-encipher a
|
|
secure LUKS2 volume key when the CCA master key is changed
|
|
Upstream-ID: 5e65df7375aec81d9348a57cdcbccb89a65422c3
|
|
Problem-ID: SEC1424.1
|
|
|
|
Upstream-Description:
|
|
|
|
zkey: Add man page for zkey-cryptsetup
|
|
|
|
Add documentation for the new zkey-cryptsetup tool
|
|
|
|
Signed-off-by: Ingo Franzki <ifranzki@linux.ibm.com>
|
|
Reviewed-by: Hendrik Brueckner <brueckner@linux.ibm.com>
|
|
Signed-off-by: Jan Höppner <hoeppner@linux.ibm.com>
|
|
|
|
|
|
Signed-off-by: Ingo Franzki <ifranzki@linux.ibm.com>
|
|
---
|
|
zkey/Makefile | 1
|
|
zkey/zkey-cryptsetup.1 | 403 +++++++++++++++++++++++++++++++++++++++++++++++++
|
|
2 files changed, 404 insertions(+)
|
|
|
|
--- a/zkey/Makefile
|
|
+++ b/zkey/Makefile
|
|
@@ -42,6 +42,7 @@ install: all
|
|
$(INSTALL) -g $(GROUP) -o $(OWNER) -m 755 zkey-cryptsetup $(DESTDIR)$(USRBINDIR)
|
|
$(INSTALL) -d -m 755 $(DESTDIR)$(MANDIR)/man1
|
|
$(INSTALL) -m 644 -c zkey.1 $(DESTDIR)$(MANDIR)/man1
|
|
+ $(INSTALL) -m 644 -c zkey-cryptsetup.1 $(DESTDIR)$(MANDIR)/man1
|
|
$(INSTALL) -d -m 770 $(DESTDIR)$(SYSCONFDIR)/zkey
|
|
$(INSTALL) -d -m 770 $(DESTDIR)$(SYSCONFDIR)/zkey/repository
|
|
|
|
--- /dev/null
|
|
+++ b/zkey/zkey-cryptsetup.1
|
|
@@ -0,0 +1,403 @@
|
|
+.\" Copyright IBM Corp. 2018
|
|
+.\" 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 "May 2018" "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 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 --master-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.
|
|
+.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 [ \-\-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 [ \-\-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
|
|
+coprocessor mode 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.
|
|
+.RE
|
|
+.PP
|
|
+\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 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 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
|
|
+.B Note:
|
|
+The \fBreencipher\fP command requires the CCA host library (libcsulcca.so)
|
|
+to be installed.
|
|
+.
|
|
+.
|
|
+.
|
|
+.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 \-\-master\-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 [ \-\-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 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 master key has been
|
|
+changed. Thus, the copy of the secure key must be currently enciphered with the
|
|
+CCA master key in the CURRENT or OLD master key register.
|
|
+Specify the secure key file with option
|
|
+.B \-\-master\-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.
|
|
+.
|
|
+.
|
|
+.
|
|
+.
|
|
+.SH OPTIONS
|
|
+.
|
|
+.SS "Options for the reencipher command"
|
|
+.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 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 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.
|
|
+.
|
|
+.
|
|
+.
|
|
+.SS "Options for the setkey command"
|
|
+.TP
|
|
+.BR \-m ", " \-\-master\-key\-file\~\fIfile\-name\fP
|
|
+Specifies the name of a file containing the secure AES key that is set as the
|
|
+new volume key.
|
|
+.
|
|
+.
|
|
+.
|
|
+.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\-name is \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 --master-key-file seckey.key
|
|
+Sets the secure key contained in file seckey.key as the new volume key
|
|
+for the encrypted volume /dev/dasdd1.
|