Sign Up
Log In
Log In
or
Sign Up
Places
All Projects
Status Monitor
Collapse sidebar
Please login to access the resource
SUSE:SLE-15-SP1:GA
s390-tools
s390-tools-sles15sp1-0016-zkey-Add-man-page-for...
Overview
Repositories
Revisions
Requests
Users
Attributes
Meta
File s390-tools-sles15sp1-0016-zkey-Add-man-page-for-zkey-cryptsetup.patch of Package s390-tools
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.
Locations
Projects
Search
Status Monitor
Help
OpenBuildService.org
Documentation
API Documentation
Code of Conduct
Contact
Support
@OBShq
Terms
openSUSE Build Service is sponsored by
The Open Build Service is an
openSUSE project
.
Sign Up
Log In
Places
Places
All Projects
Status Monitor
