forked from pool/s390-tools
1024 lines
40 KiB
Diff
1024 lines
40 KiB
Diff
|
Subject: zkey: Man page updates
|
||
|
|
From: Philipp Rudo <prudo@linux.ibm.com>
|
||
|
|
|
||
|
|
Summary: zkey: Add support of protected key crypto for dm-crypt.
|
||
|
|
Description: Support the usage of protected key crypto for dm-crypt disks in
|
||
|
|
plain format by providing a tool to manage a key repository
|
||
|
|
allowing to associate secure keys with disk partitions or logical
|
||
|
|
volumes.
|
||
|
|
Upstream-ID: f093d0bfd4242424515c6aa55c7b8ad94d233597
|
||
|
|
Problem-ID: SEC1800
|
||
|
|
|
||
|
|
Upstream-Description:
|
||
|
|
|
||
|
|
zkey: Man page updates
|
||
|
|
|
||
|
|
Add documentation for the new keystore related zkey commands.
|
||
|
|
|
||
|
|
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: Philipp Rudo <prudo@linux.ibm.com>
|
||
|
|
---
|
||
|
|
zkey/zkey.1 | 870 +++++++++++++++++++++++++++++++++++++++++++++++++++++++-----
|
||
|
|
1 file changed, 811 insertions(+), 59 deletions(-)
|
||
|
|
|
||
|
|
--- a/zkey/zkey.1
|
||
|
|
+++ b/zkey/zkey.1
|
||
|
|
@@ -1,38 +1,17 @@
|
||
|
|
-.\" Copyright 2017 IBM Corp.
|
||
|
|
+.\" Copyright IBM Corp. 2017, 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 1 "February 2017" "s390-tools"
|
||
|
|
+.TH ZKEY 1 "May 2018" "s390-tools"
|
||
|
|
.SH NAME
|
||
|
|
-zkey \- Generates, re-enciphers, and validates secure AES keys
|
||
|
|
+zkey \- Manage secure AES keys
|
||
|
|
.
|
||
|
|
.
|
||
|
|
.SH SYNOPSIS
|
||
|
|
.B zkey
|
||
|
|
-.BR generate | gen
|
||
|
|
-.I secure\-key\-file
|
||
|
|
-.RB [ \-\-keybits | \-k
|
||
|
|
-.IB size ]
|
||
|
|
-.RB [ \-\-xts | \-x ]
|
||
|
|
-.RB [ \-\-clearkey | \-c
|
||
|
|
-.IB clear\-key\-file ]
|
||
|
|
-.RB [ \-\-verbose | \-V ]
|
||
|
|
-.
|
||
|
|
-.br
|
||
|
|
-.B zkey
|
||
|
|
-.BR validate | val
|
||
|
|
-.I secure\-key\-file
|
||
|
|
-.RB [ \-\-verbose | \-V ]
|
||
|
|
-.
|
||
|
|
-.br
|
||
|
|
-.B zkey
|
||
|
|
-.BR reencipher | re
|
||
|
|
-.I secure\-key\-file
|
||
|
|
-.RB [ \-\-to\-new | \-n ]
|
||
|
|
-.RB [ \-\-from\-old | \-o ]
|
||
|
|
-.RB [ \-\-output | \-f
|
||
|
|
-.IB output\-file ]
|
||
|
|
-.RB [ \-\-verbose | \-V ]
|
||
|
|
+.I command
|
||
|
|
+.RI [ secure\-key\-file ]
|
||
|
|
+.RB [ OPTIONS ]
|
||
|
|
.
|
||
|
|
.PP
|
||
|
|
.B zkey
|
||
|
|
@@ -44,64 +23,194 @@ zkey \- Generates, re-enciphers, and val
|
||
|
|
.
|
||
|
|
.
|
||
|
|
.SH DESCRIPTION
|
||
|
|
-Use the \fBzkey\fP command to generate secure AES keys that are enciphered
|
||
|
|
-with a master key of an IBM cryptographic adapter in CCA coprocessor mode.
|
||
|
|
-You can also use the \fBzkey\fP command to validate and re-encipher secure
|
||
|
|
+Use the \fBzkey\fP tool to generate and manage secure AES keys that are
|
||
|
|
+enciphered with a master key of an IBM cryptographic adapter in CCA coprocessor
|
||
|
|
+mode. You can also use the \fBzkey\fP tool to validate and re-encipher secure
|
||
|
|
AES keys.
|
||
|
|
.PP
|
||
|
|
+The secure keys can either be stored in a file in the file system, or
|
||
|
|
+in the secure key repository. The default location of the secure key repository
|
||
|
|
+is \fB/etc/zkey/repository\fP. Set environment variable \fBZKEY_REPOSITORY\fP
|
||
|
|
+to point to a different location to use a different secure key repository
|
||
|
|
+location. Keys stored in a secure key repository inherit the permissions from
|
||
|
|
+the repository directory (except write access for other users, which is always
|
||
|
|
+denied). The default repository location \fB/etc/zkey/repository\fP is created
|
||
|
|
+with group \fBzkeyadm\fP as owner and mode \fB770\fP. Thus all secure keys
|
||
|
|
+created in that repository are owned by group \fBzkeyadm\fP. Anyone that
|
||
|
|
+is supposed to access secure keys in the secure key repository must be part of
|
||
|
|
+group \fBzkeyadm\fP.
|
||
|
|
+.PP
|
||
|
|
+When storing the secure key in a key repository, additional information, such as
|
||
|
|
+a textual description of the key, can be associated with a secure key.
|
||
|
|
+You can associate a secure key with one or multiple cryptographic adapters
|
||
|
|
+(APQNs) that are set up with the same CCA master key.
|
||
|
|
+You can also associate a secure key with one or multiple volumes
|
||
|
|
+(block devices), which are encrypted using dm-crypt with the secure key. The
|
||
|
|
+volume association also contains the device-mapper name, separated by a colon,
|
||
|
|
+used with dm-crypt. A specific volume can only be associated with one secure
|
||
|
|
+key.
|
||
|
|
+.PP
|
||
|
|
The generated secure key is saved in a file with a size of 64 or 128 bytes.
|
||
|
|
-The file contains an AES key of 128, 192, or 256 bits enciphered with the
|
||
|
|
-master key of the CCA cryptographic adapter.
|
||
|
|
+The file contains an AES key with a length of 128, 192, or 256 bits. The key is
|
||
|
|
+enciphered with the master key of the CCA cryptographic adapter.
|
||
|
|
Secure keys that are used for the XTS cipher mode can be 128 or 256 bits
|
||
|
|
-in size, because XTS requires two concatenated secure keys.
|
||
|
|
+in size.
|
||
|
|
+.
|
||
|
|
.
|
||
|
|
.
|
||
|
|
+.SH COMMANDS
|
||
|
|
+The \fBzkey\fP tool can operate in two modes. When argument
|
||
|
|
+.I secure\-key\-file
|
||
|
|
+is specified then it operates on the secure key contained in the specified file.
|
||
|
|
+This applies to commands \fBgenerate\fP, \fBvalidate\fP, and \fBreencipher\fP.
|
||
|
|
+When the
|
||
|
|
+.B \-\-name
|
||
|
|
+option is specified then it operates on a secure key contained in the secure
|
||
|
|
+key repository.
|
||
|
|
.
|
||
|
|
-.SH USAGE
|
||
|
|
+.PP
|
||
|
|
.SS "Generating secure AES keys"
|
||
|
|
+.
|
||
|
|
+.B zkey
|
||
|
|
+.BR generate | gen
|
||
|
|
+.I secure\-key\-file
|
||
|
|
+.RB [ \-\-keybits | \-k
|
||
|
|
+.IB size ]
|
||
|
|
+.RB [ \-\-xts | \-x ]
|
||
|
|
+.RB [ \-\-clearkey | \-c
|
||
|
|
+.IB clear\-key\-file ]
|
||
|
|
+.RB [ \-\-verbose | \-V ]
|
||
|
|
+.
|
||
|
|
+.PP
|
||
|
|
+.B zkey
|
||
|
|
+.BR generate | gen
|
||
|
|
+.B \-\-name | \-N
|
||
|
|
+.IB key-name
|
||
|
|
+.RB [ \-\-description | \-d
|
||
|
|
+.IB description ]
|
||
|
|
+.RB [ \-\-volumes | \-l
|
||
|
|
+.IB volume1:dmname1[,volume2:dmname2[,...]] ]
|
||
|
|
+.RB [ \-\-apqns | \-a
|
||
|
|
+.IB card1.domain1[,card2.domain2[,...]] ]
|
||
|
|
+.RB [ \-\-sector-size | \-S
|
||
|
|
+.IB bytes ]
|
||
|
|
+.RB [ \-\-keybits | \-k
|
||
|
|
+.IB size ]
|
||
|
|
+.RB [ \-\-xts | \-x ]
|
||
|
|
+.RB [ \-\-clearkey | \-c
|
||
|
|
+.IB clear\-key\-file ]
|
||
|
|
+.RB [ \-\-verbose | \-V ]
|
||
|
|
+.PP
|
||
|
|
Use the
|
||
|
|
.B generate
|
||
|
|
command to generate a new secure AES key either randomly within the CCA
|
||
|
|
cryptographic adapter, or from a clear AES key specified as input. When specifying
|
||
|
|
-a clear key as input, the clear key should be kept at a secure place, or be
|
||
|
|
+a clear key as input, the clear key should be kept in a secure place, or be
|
||
|
|
securely erased after creation of the secure key. The secure key itself does
|
||
|
|
not need to be kept secure, because it can only be used together with a
|
||
|
|
CCA cryptographic adapter that contains the master key with which the secure
|
||
|
|
key was generated.
|
||
|
|
+.PP
|
||
|
|
+The generated secure key can either be stored in a file in the file system,
|
||
|
|
+or in the secure key repository. To store the generated secure key in a
|
||
|
|
+file, specify the file name with option \fIsecure\-key\-file\fP. To store the
|
||
|
|
+secure key in the secure key repository, specify the name of the key using the
|
||
|
|
+.B --name
|
||
|
|
+option. When storing the secure key in a key repository,
|
||
|
|
+additional information can be associated with a secure key using the
|
||
|
|
+.B --description
|
||
|
|
+,
|
||
|
|
+.B --volumes
|
||
|
|
+,
|
||
|
|
+.B --apqns
|
||
|
|
+, or the
|
||
|
|
+.B --sector-size
|
||
|
|
+options.
|
||
|
|
.
|
||
|
|
.SS "Validating secure AES keys"
|
||
|
|
+.
|
||
|
|
+.B zkey
|
||
|
|
+.BR validate | val
|
||
|
|
+.I secure\-key\-file
|
||
|
|
+.RB [ \-\-verbose | \-V ]
|
||
|
|
+.
|
||
|
|
+.PP
|
||
|
|
+.B zkey
|
||
|
|
+.BR validate | val
|
||
|
|
+.RB [ \-\-name | \-N
|
||
|
|
+.IB key-name ]
|
||
|
|
+.RB [ \-\-verbose | \-V ]
|
||
|
|
+.PP
|
||
|
|
Use the
|
||
|
|
.B validate
|
||
|
|
command to validate an existing secure key.
|
||
|
|
-It checks if the specified file contains a valid secure key.
|
||
|
|
+It checks if the specified file or repository entry contains a valid secure key.
|
||
|
|
It also displays the attributes of the secure key, such as key sizes, whether
|
||
|
|
-it is a secure key that can be used for the XTS cipher mode, and the master key
|
||
|
|
-register with which the secure key is enciphered.
|
||
|
|
+it is a secure key that can be used for the XTS cipher mode, the master key
|
||
|
|
+register (CURRENT or OLD) with which the secure key is enciphered, and other key
|
||
|
|
+attributes. For further information about master key registers, see the
|
||
|
|
+\fBreencipher\fP command.
|
||
|
|
+.PP
|
||
|
|
+The secure key can either be contained in a file in the file system, or in a
|
||
|
|
+secure key repository. To validate a secure key contained in a file, specify
|
||
|
|
+the file name with option \fIsecure\-key\-file\fP. To validate secure keys
|
||
|
|
+contained in the secure key repository, specify the name of the key
|
||
|
|
+or a pattern containing wildcards using the
|
||
|
|
+.B --name
|
||
|
|
+option. When wildcards are used you must quote the value.
|
||
|
|
+If neither option \fIsecure\-key\-file\fP nor option
|
||
|
|
+.B --name
|
||
|
|
+are specified, then all secure keys contained in the key repository
|
||
|
|
+are validated.
|
||
|
|
.
|
||
|
|
.SS "Re-encipher existing AES secure keys"
|
||
|
|
+.
|
||
|
|
+.B zkey
|
||
|
|
+.BR reencipher | re
|
||
|
|
+.I secure\-key\-file
|
||
|
|
+.RB [ \-\-to\-new | \-n ]
|
||
|
|
+.RB [ \-\-from\-old | \-o ]
|
||
|
|
+.RB [ \-\-output | \-f
|
||
|
|
+.IB output\-file ]
|
||
|
|
+.RB [ \-\-verbose | \-V ]
|
||
|
|
+.PP
|
||
|
|
+.B zkey
|
||
|
|
+.BR reencipher | re
|
||
|
|
+.RB [ \-\-name | \-N
|
||
|
|
+.IB key-name ]
|
||
|
|
+.RB [ \-\-apqns | \-a
|
||
|
|
+.IB card1.domain1[,card2.domain2[,...]] ]
|
||
|
|
+.RB [ \-\-to\-new | \-n ]
|
||
|
|
+.RB [ \-\-from\-old | \-o ]
|
||
|
|
+.RB [ \-\-in-place | \-i ]
|
||
|
|
+.RB [ \-\-staged | \-s ]
|
||
|
|
+.RB [ \-\-complete | \-c ]
|
||
|
|
+.RB [ \-\-verbose | \-V ]
|
||
|
|
+.PP
|
||
|
|
Use the
|
||
|
|
.B reencipher
|
||
|
|
command to re-encipher an existing secure key with a new master key.
|
||
|
|
-A secure key have to be re-enciphered, when the master key of the CCA
|
||
|
|
-cryptographic adapter is being changed.
|
||
|
|
+A secure key bust be re-enciphered when the master key of the CCA
|
||
|
|
+cryptographic adapter changes.
|
||
|
|
.PP
|
||
|
|
-The CCA cryptographic adapter has 3 different registers to store
|
||
|
|
+The CCA cryptographic adapter has three different registers to store
|
||
|
|
master keys:
|
||
|
|
.RS 2
|
||
|
|
.IP "\(bu" 2
|
||
|
|
-The \fPCURRENT\fP register contains the current master key.
|
||
|
|
+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 canstill be used until the master key is changed again.
|
||
|
|
+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. Note that a secure key can be proactively
|
||
|
|
-re-enciphered with the master key in the \fBNEW\fP register before
|
||
|
|
-the new master key is made the current one.
|
||
|
|
+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
|
||
|
|
Use the
|
||
|
|
@@ -110,13 +219,12 @@ option to re-encipher a secure key that
|
||
|
|
the master key in the \fBOLD\fP register with the master key in the
|
||
|
|
\fBCURRENT\fP register.
|
||
|
|
.PP
|
||
|
|
-Use the
|
||
|
|
-.B \-\-to\-new
|
||
|
|
-option to proactively re-encipher a secure key that is currently
|
||
|
|
-enciphered with the master key in the \fBCURRENT\fP register with
|
||
|
|
-the master key in the \fBNEW\fP register.
|
||
|
|
.PP
|
||
|
|
-If both options are specified, a secure key that is currently enciphered
|
||
|
|
+If both the
|
||
|
|
+.B \-\-from-old
|
||
|
|
+and
|
||
|
|
+.B \-\-to-new
|
||
|
|
+options are specified, a secure 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.
|
||
|
|
.PP
|
||
|
|
@@ -127,11 +235,310 @@ If currently enciphered with the master
|
||
|
|
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
|
||
|
|
+The secure key can either be contained in a file in the file system, or in a
|
||
|
|
+secure key repository. To re-encipher a secure key contained in a file,
|
||
|
|
+specify the file name with option \fIsecure\-key\-file\fP. To re-encipher
|
||
|
|
+secure keys contained in the secure key repository, specify the name of the key
|
||
|
|
+or a pattern containing wildcards using the
|
||
|
|
+.B --name
|
||
|
|
+option. When wildcards are used you must quote the value.
|
||
|
|
+You can also specify the
|
||
|
|
+.B --apqns
|
||
|
|
+option to re-encipher those secure
|
||
|
|
+keys which are associated with the specified cryptographic adapters (APQNs).
|
||
|
|
+You can use wildcards for the APQN specification.
|
||
|
|
+When wildcards are used you must quote the value.
|
||
|
|
+If both option
|
||
|
|
+.B --name
|
||
|
|
+and option
|
||
|
|
+.B --apqns
|
||
|
|
+are specified then all secure keys
|
||
|
|
+contained in the key repository that match both patterns are re-enciphered.
|
||
|
|
+If all both options are omitted, then all secure keys contained in the key
|
||
|
|
+repository are re-enciphered.
|
||
|
|
+.PP
|
||
|
|
+Re-enciphering a secure key contained in the secure key repository can be
|
||
|
|
+performed \fBin-place\fP, or in \fBstaged\fP mode.
|
||
|
|
+.PP
|
||
|
|
+\fB"In-place"\fP immediately replaces the secure key in the repository with
|
||
|
|
+the re-enciphered secure 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
|
||
|
|
+a secure key that was re-enciphered in-place from \fBCURRENT\fP to \fBNEW\fP
|
||
|
|
+is no longer valid, until the new CCA master key has been made the current one.
|
||
|
|
+.PP
|
||
|
|
+\fBStaged\fP mode means that the re-enciphered secure key is stored in a
|
||
|
|
+separate file in the secure key repository. Thus the current secure key is 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. You can use option \fB--staged\fP to force
|
||
|
|
+a staged re-enciphering for the \fBOLD\fP to \fBCURRENT\fP case.
|
||
|
|
.PP
|
||
|
|
.B Note:
|
||
|
|
-The \fBreencipher\fP command requires the IBM CCA Host Library (libcsulcca.so)
|
||
|
|
+The \fBreencipher\fP command requires the CCA host library (libcsulcca.so)
|
||
|
|
to be installed.
|
||
|
|
.
|
||
|
|
+.SS "Import existing AES secure keys into the secure key repository"
|
||
|
|
+.
|
||
|
|
+.B zkey
|
||
|
|
+.BR import | im
|
||
|
|
+.I secure\-key\-file
|
||
|
|
+.B \-\-name | \-N
|
||
|
|
+.IB key-name
|
||
|
|
+.RB [ \-\-description | \-d
|
||
|
|
+.IB description ]
|
||
|
|
+.RB [ \-\-volumes | \-l
|
||
|
|
+.IB volume1:dmname1[,volume2:dmname2[,...]] ]
|
||
|
|
+.RB [ \-\-apqns | \-a
|
||
|
|
+.IB card1.domain1[,card2.domain2[,...]] ]
|
||
|
|
+.RB [ \-\-sector-size | \-S
|
||
|
|
+.IB bytes ]
|
||
|
|
+.RB [ \-\-verbose | \-V ]
|
||
|
|
+.
|
||
|
|
+.PP
|
||
|
|
+Use the
|
||
|
|
+.B import
|
||
|
|
+command to import an existing secure key contained in a file into the the
|
||
|
|
+secure key repository. When importing a secure key in a key repository,
|
||
|
|
+additional information can be associated with a secure key using the
|
||
|
|
+.B --description
|
||
|
|
+,
|
||
|
|
+.B --volumes
|
||
|
|
+,
|
||
|
|
+.B --apqns
|
||
|
|
+, or the
|
||
|
|
+.B --sector-size
|
||
|
|
+options.
|
||
|
|
+.
|
||
|
|
+.SS "Export AES secure keys from the secure key repository"
|
||
|
|
+.
|
||
|
|
+.B zkey
|
||
|
|
+.BR export | ex
|
||
|
|
+.I secure\-key\-file
|
||
|
|
+.B \-\-name | \-N
|
||
|
|
+.IB key-name
|
||
|
|
+.RB [ \-\-verbose | \-V ]
|
||
|
|
+.
|
||
|
|
+.PP
|
||
|
|
+Use the
|
||
|
|
+.B export
|
||
|
|
+command to export an existing secure key contained in the secure key repository
|
||
|
|
+to a file in the file system. Specify the name of the key that is to be exported
|
||
|
|
+using the
|
||
|
|
+.B --name
|
||
|
|
+option. You cannot use wildcards.
|
||
|
|
+When wildcards are used you must quote the value.
|
||
|
|
+The exported secure key also remains in the secure key repository.
|
||
|
|
+.
|
||
|
|
+.SS "List AES secure keys contained in the secure key repository"
|
||
|
|
+.
|
||
|
|
+.B zkey
|
||
|
|
+.BR list | li
|
||
|
|
+.RB [ \-\-name | \-N
|
||
|
|
+.IB key-name ]
|
||
|
|
+.RB [ \-\-volumes | \-l
|
||
|
|
+.IB volume1[:dmname1][,volume2[:dmname2][,...]] ]
|
||
|
|
+.RB [ \-\-apqns | \-a
|
||
|
|
+.IB card1.domain1[,card2.domain2[,...]] ]
|
||
|
|
+.RB [ \-\-verbose | \-V ]
|
||
|
|
+.
|
||
|
|
+.PP
|
||
|
|
+Use the
|
||
|
|
+.B list
|
||
|
|
+command to display a list of secure keys contained in the secure key repository.
|
||
|
|
+You can filter the displayed list by key name, associated volumes, and
|
||
|
|
+associated cryptographic adapters (APQNs). You can use wildcards for the key
|
||
|
|
+name, associated APQNs, and associated volumes. The device-mapper name of an
|
||
|
|
+associated volume can be omitted; if it is specified then only those keys are
|
||
|
|
+listed that are associated with the specified volume and device-mapper name.
|
||
|
|
+.PP
|
||
|
|
+The
|
||
|
|
+.B list
|
||
|
|
+command displays the attributes of the secure keys, such as key sizes,
|
||
|
|
+whether it is a secure key that can be used for the XTS cipher mode, the textual
|
||
|
|
+description, associated cryptographic adapters (APQNs) and volumes, the
|
||
|
|
+sector size, and timestamps for key creation, last modification and last
|
||
|
|
+re-encipherment.
|
||
|
|
+.
|
||
|
|
+.SS "Remove existing AES secure keys from the secure key repository"
|
||
|
|
+.
|
||
|
|
+.B zkey
|
||
|
|
+.BR remove | rem
|
||
|
|
+.B \-\-name | \-N
|
||
|
|
+.IB key-name
|
||
|
|
+.RB [ \-\-force | \-F ]
|
||
|
|
+.RB [ \-\-verbose | \-V ]
|
||
|
|
+.
|
||
|
|
+.PP
|
||
|
|
+Use the
|
||
|
|
+.B remove
|
||
|
|
+command to remove an existing secure key from the secure key repository.
|
||
|
|
+Specify the name of the key that is to be removed using the
|
||
|
|
+.B --name
|
||
|
|
+option. You cannot use wildcards. The remove command prompts for
|
||
|
|
+a confirmation, unless you specify the
|
||
|
|
+.B --force
|
||
|
|
+option.
|
||
|
|
+.PP
|
||
|
|
+.B Note:
|
||
|
|
+When removing a secure key that is associated with one or multiple volumes,
|
||
|
|
+a message informs you about the associated volumes. When the secure key is
|
||
|
|
+removed, these volumes can no longer be used, unless you have a backup of the
|
||
|
|
+secure key.
|
||
|
|
+.
|
||
|
|
+.SS "Change existing AES secure keys contained the secure key repository"
|
||
|
|
+.
|
||
|
|
+.B zkey
|
||
|
|
+.BR change | ch
|
||
|
|
+.B \-\-name | \-N
|
||
|
|
+.IB key-name
|
||
|
|
+.RB [ \-\-description | \-d
|
||
|
|
+.IB description ]
|
||
|
|
+.RB [ \-\-volumes | \-l
|
||
|
|
+.IB [+|-]volume1:dmname1[,volume2:dmname2[,...]] ]
|
||
|
|
+.RB [ \-\-apqns | \-a
|
||
|
|
+.IB [+|-]card1.domain1[,card2.domain2[,...]] ]
|
||
|
|
+.RB [ \-\-sector-size | \-S
|
||
|
|
+.IB bytes ]
|
||
|
|
+.RB [ \-\-verbose | \-V ]
|
||
|
|
+.
|
||
|
|
+.PP
|
||
|
|
+Use the
|
||
|
|
+.B change
|
||
|
|
+command to change the description, the associated volumes, the associated
|
||
|
|
+cryptographic adapters (APQNs), and the sector size of a secure key contained
|
||
|
|
+in the secure key repository. Specify the name of the key that is to be changed
|
||
|
|
+using the
|
||
|
|
+.B --name
|
||
|
|
+option. You cannot use wildcards.
|
||
|
|
+.PP
|
||
|
|
+You can set (replace), add, or
|
||
|
|
+remove volume and cryptographic adapters (APQN) associations. To set
|
||
|
|
+(replace) an association, specify the association with the
|
||
|
|
+.B --volumes
|
||
|
|
+or the
|
||
|
|
+.B --apqns
|
||
|
|
+options. To add an association,
|
||
|
|
+specify the new association prefixed with a \fI+\fP with the
|
||
|
|
+.B --volumes
|
||
|
|
+or the
|
||
|
|
+.B --apqns
|
||
|
|
+options. To remove an association,
|
||
|
|
+specify the association to remove prefixed with a \fI-\fP with the
|
||
|
|
+.B --volumes
|
||
|
|
+or the
|
||
|
|
+.B --apqns
|
||
|
|
+options. You cannot mix \fI+\fP and
|
||
|
|
+\fI-\fP in one specification. You can either add or remove (or set) the
|
||
|
|
+associations with one command.
|
||
|
|
+.PP
|
||
|
|
+.B Note:
|
||
|
|
+The secure key itself cannot be changed, only information about the secure
|
||
|
|
+key is changed. To rename a secure key, use the \fBrename\fP command.
|
||
|
|
+To re-encipher a secure key with a new CCA master key, use the \fBreencipher\fP
|
||
|
|
+command.
|
||
|
|
+.
|
||
|
|
+.SS "Rename existing AES secure keys in the secure key repository"
|
||
|
|
+.
|
||
|
|
+.B zkey
|
||
|
|
+.BR rename | ren
|
||
|
|
+.B \-\-name | \-N
|
||
|
|
+.IB key-name
|
||
|
|
+.B \-\-new-name | \-w
|
||
|
|
+.IB new-key-name
|
||
|
|
+.RB [ \-\-verbose | \-V ]
|
||
|
|
+.
|
||
|
|
+.PP
|
||
|
|
+Use the
|
||
|
|
+.B rename
|
||
|
|
+command to rename an existing secure key in the secure key repository.
|
||
|
|
+Specify the name of the key that is to be renamed using the
|
||
|
|
+.B --name
|
||
|
|
+option and the new name using the
|
||
|
|
+.B --new-name
|
||
|
|
+option. You cannot use wildcards.
|
||
|
|
+.
|
||
|
|
+.SS "Copy (duplicate) existing AES secure keys in the secure key repository"
|
||
|
|
+.
|
||
|
|
+.B zkey
|
||
|
|
+.B copy | co
|
||
|
|
+.RB \-\-name | \-N
|
||
|
|
+.IB key-name
|
||
|
|
+.B \-\-new-key-name | \-w
|
||
|
|
+.IB new-name
|
||
|
|
+.RB [ \-\-volumes | \-l
|
||
|
|
+.IB volume1:dmname1[,volume2:dmname2[,...]] ]
|
||
|
|
+.RB [ \-\-verbose | \-V ]
|
||
|
|
+.
|
||
|
|
+.PP
|
||
|
|
+Use the
|
||
|
|
+.B copy
|
||
|
|
+command to copy (duplicate) an existing secure key in the secure key repository.
|
||
|
|
+Specify the name of the key that is to be copied using the
|
||
|
|
+.B --name
|
||
|
|
+option and the name of the copied key using the
|
||
|
|
+.B --new-name
|
||
|
|
+option. You cannot use wildcards.
|
||
|
|
+.PP
|
||
|
|
+.B Note:
|
||
|
|
+When copying a secure key, the volume associations are not copied, because
|
||
|
|
+a specific volume can only be associated with a single secure key. Specify the
|
||
|
|
+.B --volumes
|
||
|
|
+option to associate different
|
||
|
|
+volumes with the copied secure key, or use the \fBchange\fP command to associate
|
||
|
|
+volumes afterwards.
|
||
|
|
+.
|
||
|
|
+.SS "Generate crypttab entries for volumes associated with secure AES keys"
|
||
|
|
+.
|
||
|
|
+.B zkey
|
||
|
|
+.BR crypttab | cryptt
|
||
|
|
+.RB [ \-\-volumes | \-l
|
||
|
|
+.IB volume1[:dmname1][,volume2[:dmname2][,...]] ]
|
||
|
|
+.RB [ \-\-verbose | \-V ]
|
||
|
|
+.
|
||
|
|
+.PP
|
||
|
|
+Use the
|
||
|
|
+.B crypttab
|
||
|
|
+command to generate crypttab entries using the \fBplain\fP dm-crypt mode
|
||
|
|
+for volumes that are associated with secure keys contained in the secure key
|
||
|
|
+repository. Specify the
|
||
|
|
+.B --volumes
|
||
|
|
+option to limit the list
|
||
|
|
+of volumes where crypttab entries are generated for. You can use wildcards.
|
||
|
|
+When wildcards are used you must quote the value.
|
||
|
|
+The device-mapper name of an associated volume can be omitted; if it is
|
||
|
|
+specified then only those volumes with the specified volume and device-mapper
|
||
|
|
+name are selected.
|
||
|
|
+.
|
||
|
|
+.SS "Generate cryptsetup commands for volumes associated with secure AES keys"
|
||
|
|
+.
|
||
|
|
+.B zkey
|
||
|
|
+.BR cryptsetup | crypts
|
||
|
|
+.RB [ \-\-volumes | \-l
|
||
|
|
+.IB volume1[:dmname1][,volume2[:dmname2][,...]] ]
|
||
|
|
+.RB [ \-\-run | \-r ]
|
||
|
|
+.RB [ \-\-verbose | \-V ]
|
||
|
|
+.
|
||
|
|
+.PP
|
||
|
|
+Use the
|
||
|
|
+.B cryptsetup
|
||
|
|
+command to generate \fBcryptsetup plainOpen\fP commands for volumes that are
|
||
|
|
+associated with secure keys contained in the secure key repository. Specify the
|
||
|
|
+.B --volumes
|
||
|
|
+option to limit the list
|
||
|
|
+of volumes where cryptsetup commands are generated for. You can use wildcards.
|
||
|
|
+When wildcards are used you must quote the value.
|
||
|
|
+The device-mapper name of an associated volume can be omitted; if it is
|
||
|
|
+specified then only those volumes with the specified volume and device-mapper
|
||
|
|
+name are selected. Specify the
|
||
|
|
+.B --run
|
||
|
|
+option to run the generated cryptsetup commands.
|
||
|
|
+.
|
||
|
|
+.
|
||
|
|
.
|
||
|
|
.
|
||
|
|
.SH OPTIONS
|
||
|
|
@@ -139,13 +546,13 @@ to be installed.
|
||
|
|
.TP
|
||
|
|
.BR \-k ", " \-\-keybits\~\fIsize\fP
|
||
|
|
Specifies the size of the AES key to be generated in bits.
|
||
|
|
-Valid sizes are 128, 192, and 256 bits. Secure keys for use with the
|
||
|
|
+Valid values are 128, 192, and 256. Secure keys for use with the
|
||
|
|
XTS cipher mode can only use keys of 128 or 256 bits.
|
||
|
|
The default is 256 bits.
|
||
|
|
.TP
|
||
|
|
.BR \-x ", " \-\-xts
|
||
|
|
-Generates a secure AES key for the XTS cipher mode. A secure AES key for
|
||
|
|
-the XTS cipher mode consist of two concatenated secure keys.
|
||
|
|
+Generates a secure AES key for the XTS cipher mode that consist of two
|
||
|
|
+concatenated secure keys.
|
||
|
|
.TP
|
||
|
|
.BR \-c ", " \-\-clearkey\~\fIclear\-key\-file\fP
|
||
|
|
Specifies a file path that contains the clear AES key in binary form.
|
||
|
|
@@ -154,6 +561,49 @@ determines the size of the AES key. If
|
||
|
|
is specified, the size of the specified file must match the specified
|
||
|
|
key size. Valid file sizes are of 16, 24, or 32 bytes, and of 32 or 64
|
||
|
|
bytes for keys to be used with the XTS cipher mode.
|
||
|
|
+.TP
|
||
|
|
+.BR \-N ", " \-\-name\~\fIkey-name\fP
|
||
|
|
+Specifies the name of the secure key in the secure key repository.
|
||
|
|
+This option is only used for secure keys contained in the secure key repository.
|
||
|
|
+.TP
|
||
|
|
+.BR \-d ", " \-\-description\~\fIdescription\fP
|
||
|
|
+Specifies a textual description for the secure key in the secure key repository.
|
||
|
|
+This option is only used for secure keys contained in the secure key repository.
|
||
|
|
+.TP
|
||
|
|
+.BR \-l ", " \-\-volumes\~\fIvolume1:dmname1[,volume2:dmname2[,...]]\fP
|
||
|
|
+Specifies a comma-separated list of volumes (block devices) that are
|
||
|
|
+associated with the secure AES key in the repository. These volumes are to be
|
||
|
|
+encrypted using dm-crypt with the secure AES key. The volume association also
|
||
|
|
+contains the device-mapper name, separated by a colon, used with dm-crypt.
|
||
|
|
+A specific volume can only be associated with a single secure key.
|
||
|
|
+This option is only used for secure keys contained in the secure key repository.
|
||
|
|
+.TP
|
||
|
|
+.BR \-a ", " \-\-apqns\~\fIcard1.domain1[,card2.domain2[,...]]\fP
|
||
|
|
+Specifies a comma-separated list of cryptographic adapters in CCA
|
||
|
|
+coprocessor mode (APQN) which are associated with the secure AES key in the
|
||
|
|
+repository. Each APQN association specifies a card and domain number separated
|
||
|
|
+by a period (like lszcrypt displays it). When at least one APQN is specified,
|
||
|
|
+then the first one is used to generate the key. If no APQNs are specified,
|
||
|
|
+then an APQN is selected automatically. All specified APQNs must be online.
|
||
|
|
+This option is only used for secure keys contained in the secure key repository.
|
||
|
|
+.TP
|
||
|
|
+.BR \-S ", " \-\-sector-size\~\fIbytes\fP
|
||
|
|
+Specifies the sector size in bytes used with dm-crypt. It must be a power of two
|
||
|
|
+and in the range 512 - 4096 bytes. If omitted, the system default sector size
|
||
|
|
+is used.
|
||
|
|
+This option is only used for secure keys contained in the secure key repository.
|
||
|
|
+.
|
||
|
|
+.
|
||
|
|
+.
|
||
|
|
+.SS "Options for the validate command"
|
||
|
|
+.TP
|
||
|
|
+.BR \-N ", " \-\-name\~\fIkey-name\fP
|
||
|
|
+Specifies the name of the secure key in the secure key repository. You can
|
||
|
|
+use wildcards to select multiple secure keys in the secure key repository.
|
||
|
|
+When wildcards are used you must quote the value.
|
||
|
|
+This option is only used for secure keys contained in the secure key repository.
|
||
|
|
+.
|
||
|
|
+.
|
||
|
|
.
|
||
|
|
.SS "Options for the reencipher command"
|
||
|
|
.TP
|
||
|
|
@@ -168,7 +618,256 @@ master key in the OLD register with the
|
||
|
|
.BR \-f ", " \-\-output\~\fIoutput\-file\fP
|
||
|
|
Specifies the name of the output file to which the re-enciphered secure key
|
||
|
|
is written. If this option is omitted, the re-enciphered secure key
|
||
|
|
-is replaced in the file that currently contains the secure key.
|
||
|
|
+is replaced in the file that currently contains the secure key. This option is
|
||
|
|
+only used for secure keys stored in a file in the file system. It is not valid
|
||
|
|
+for keys contained in the secure key repository.
|
||
|
|
+.TP
|
||
|
|
+.BR \-N ", " \-\-name\~\fIkey-name\fP
|
||
|
|
+Specifies the name of the secure key in the secure key repository. You can
|
||
|
|
+use wildcards to select multiple secure keys in the secure key repository.
|
||
|
|
+When wildcards are used you must quote the value.
|
||
|
|
+This option is only used for secure keys contained in the secure key repository.
|
||
|
|
+.TP
|
||
|
|
+.BR \-a ", " \-\-apqns\~\fIcard1.domain1[,card2.domain2[,...]]\fP
|
||
|
|
+Specifies a comma-separated list of cryptographic adapters in CCA
|
||
|
|
+coprocessor mode (APQNs). You can use wildcards in the APQN specification.
|
||
|
|
+All secure keys contained in the secure key repository
|
||
|
|
+which are associated with the specified APQNs are re-enciphered.
|
||
|
|
+Each APQN specifies a card and domain number separated by a period (like
|
||
|
|
+lszcrypt displays it).
|
||
|
|
+This option is only used for secure keys contained in the secure key repository.
|
||
|
|
+.TP
|
||
|
|
+.BR \-i ", " \-\-in-place
|
||
|
|
+Forces an in-place re-enciphering of a secure AES key contained in the secure
|
||
|
|
+key repository. "In-place" immediately replaces the secure key in the repository
|
||
|
|
+with the re-enciphered secure key.
|
||
|
|
+Re-enciphering from OLD to CURRENT is performed in-place per default.
|
||
|
|
+This option is only used for secure keys contained in the secure key repository.
|
||
|
|
+.TP
|
||
|
|
+.BR \-s ", " \-\-staged
|
||
|
|
+Forces that the re-enciphering of a secure AES key contained in the secure key
|
||
|
|
+repository is performed in staged mode. Staged mode means that the re-enciphered
|
||
|
|
+secure key is stored in a separate file in the secure key repository. Thus the
|
||
|
|
+current secure key is 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 CURRENT to NEW is performed in staged mode per default.
|
||
|
|
+This option is only used for secure keys contained in the secure key repository.
|
||
|
|
+.TP
|
||
|
|
+.BR \-p ", " \-\-complete
|
||
|
|
+Completes a staged re-enciphering. Use this option after the new CCA master key
|
||
|
|
+has been set (made active). This option replaces the secure key by its
|
||
|
|
+re-enciphered version in the secure key repository.
|
||
|
|
+This option is only used for secure keys contained in the secure key repository.
|
||
|
|
+.
|
||
|
|
+.
|
||
|
|
+.
|
||
|
|
+.
|
||
|
|
+.SS "Options for the import command"
|
||
|
|
+.TP
|
||
|
|
+.BR \-N ", " \-\-name\~\fIkey-name\fP
|
||
|
|
+Specifies the name of the secure key in the secure key repository.
|
||
|
|
+This option is only used for secure keys contained in the secure key repository.
|
||
|
|
+.TP
|
||
|
|
+.BR \-d ", " \-\-description\~\fIdescription\fP
|
||
|
|
+Specifies a textual description for the secure key in the secure key repository.
|
||
|
|
+This option is only used for secure keys contained in the secure key repository.
|
||
|
|
+.TP
|
||
|
|
+.BR \-l ", " \-\-volumes\~\fIvolume1:dmname1[,volume2:dmname2[,...]]\fP
|
||
|
|
+Specifies a comma-separated list of volumes (block devices) which are
|
||
|
|
+associated with the secure AES key in the repository. These volumes are to be
|
||
|
|
+encrypted using dm-crypt with the secure AES key. The volume association also
|
||
|
|
+contains the device-mapper name, separated by a colon, used with dm-crypt.
|
||
|
|
+A specific volume can only be associated with a single secure key.
|
||
|
|
+This option is only used for secure keys contained in the secure key repository.
|
||
|
|
+.TP
|
||
|
|
+.BR \-a ", " \-\-apqns\~\fIcard1.domain1[,card2.domain2[,...]]\fP
|
||
|
|
+Specifies a comma-separated list of cryptographic adapters in CCA
|
||
|
|
+coprocessor mode (APQN) which are associated with the secure AES key in the
|
||
|
|
+repository. Each APQN association specifies a card and domain number separated
|
||
|
|
+by a period (like lszcrypt displays it). All specified APQNs must be online.
|
||
|
|
+This option is only used for secure keys contained in the secure key repository.
|
||
|
|
+.TP
|
||
|
|
+.BR \-S ", " \-\-sector-size\~\fIbytes\fP
|
||
|
|
+Specifies the sector size in bytes used with dm-crypt. It must be a power of two
|
||
|
|
+and in the range 512 - 4096 bytes. If omitted, the system default sector size
|
||
|
|
+is used.
|
||
|
|
+This option is only used for secure keys contained in the secure key repository.
|
||
|
|
+.
|
||
|
|
+.
|
||
|
|
+.
|
||
|
|
+.SS "Options for the export command"
|
||
|
|
+.TP
|
||
|
|
+.BR \-N ", " \-\-name\~\fIkey-name\fP
|
||
|
|
+Specifies the name of the secure key in the secure key repository. You cannot
|
||
|
|
+use wildcards.
|
||
|
|
+This option is only used for secure keys contained in the secure key repository.
|
||
|
|
+.
|
||
|
|
+.
|
||
|
|
+.
|
||
|
|
+.SS "Options for the list command"
|
||
|
|
+.TP
|
||
|
|
+.BR \-N ", " \-\-name\~\fIkey-name\fP
|
||
|
|
+Specifies the name of the secure key in the secure key repository. You can
|
||
|
|
+use wildcards to select multiple secure keys in the secure key repository.
|
||
|
|
+When wildcards are used you must quote the value.
|
||
|
|
+Only keys with names that match the pattern are listed.
|
||
|
|
+This option is only used for secure keys contained in the secure key repository.
|
||
|
|
+.TP
|
||
|
|
+.BR \-l ", " \-\-volumes\~\fIvolume1[:dmname1][,volume2[:dmname2][,...]]\fP
|
||
|
|
+Specifies a comma-separated list of volumes (block devices) which are
|
||
|
|
+associated with the secure AES key in the repository. Only those keys are
|
||
|
|
+listed, which are associated with the specified volumes.
|
||
|
|
+The volume association also contains the device-mapper name, separated by a
|
||
|
|
+colon, used with dm-crypt. You can omit the device-mapper name; if it is
|
||
|
|
+specified then only those keys are listed that are associated with the
|
||
|
|
+specified volume and device-mapper name. You can use wildcards to specify
|
||
|
|
+the volumes and device-mapper names.
|
||
|
|
+When wildcards are used you must quote the value.
|
||
|
|
+This option is only used for secure keys contained in the secure key repository.
|
||
|
|
+.TP
|
||
|
|
+.BR \-a ", " \-\-apqns\~\fIcard1.domain1[,card2.domain2[,...]]\fP
|
||
|
|
+Specifies a comma-separated list of cryptographic adapters in CCA
|
||
|
|
+coprocessor mode (APQN) which are associated with the secure AES key in the
|
||
|
|
+repository. Only those keys are listed, which are associated with the specified
|
||
|
|
+APQNs. Each APQN association specifies a card and domain number separated
|
||
|
|
+by a period (like lszcrypt displays it). You can use wildcards in the APQN
|
||
|
|
+specification.
|
||
|
|
+This option is only used for secure keys contained in the secure key repository.
|
||
|
|
+.
|
||
|
|
+.
|
||
|
|
+.
|
||
|
|
+.SS "Options for the remove command"
|
||
|
|
+.TP
|
||
|
|
+.BR \-N ", " \-\-name\~\fIkey-name\fP
|
||
|
|
+Specifies the name of the secure key in the secure key repository. You cannot
|
||
|
|
+use wildcards.
|
||
|
|
+This option is only used for secure keys contained in the secure key repository.
|
||
|
|
+.TP
|
||
|
|
+.BR \-F ", " \-\-force\fP
|
||
|
|
+The user is prompted to confirm the removal of a secure key from the secure
|
||
|
|
+key repository. Use this option to remove a secure key without prompting for
|
||
|
|
+a confirmation.
|
||
|
|
+This option is only used for secure keys contained in the secure key repository.
|
||
|
|
+.
|
||
|
|
+.
|
||
|
|
+.
|
||
|
|
+.SS "Options for the change command"
|
||
|
|
+.TP
|
||
|
|
+.BR \-N ", " \-\-name\~\fIkey-name\fP
|
||
|
|
+Specifies the name of the secure key in the secure key repository. You cannot
|
||
|
|
+use wildcards.
|
||
|
|
+This option is only used for secure keys contained in the secure key repository.
|
||
|
|
+.TP
|
||
|
|
+.BR \-d ", " \-\-description\~\fIdescription\fP
|
||
|
|
+Specifies a textual description for the secure key in the secure key repository.
|
||
|
|
+This option is only used for secure keys contained in the secure key repository.
|
||
|
|
+.TP
|
||
|
|
+.BR \-l ", " \-\-volumes\~\fI[+|-]volume1:dmname1[,volume2:dmname2[,...]]\fP
|
||
|
|
+Specifies a comma-separated list of volumes (block devices) which are
|
||
|
|
+associated with the secure AES key in the repository. These volumes are to be
|
||
|
|
+encrypted using dm-crypt with the secure AES key. The volume association also
|
||
|
|
+contains the device-mapper name, separated by a colon, used with dm-crypt.
|
||
|
|
+To add a volume to the associated volumes, prefix the volume with a \fI+\fP.
|
||
|
|
+To remove a volume from the associated volumes, prefix the volume with a \fI-\fP.
|
||
|
|
+To set (replace) the volume association do not specify a prefix.
|
||
|
|
+You cannot mix \fI+\fP and \fI-\fP in one specification. You can either add or
|
||
|
|
+remove (or set) the associations with one command.
|
||
|
|
+A specific volume can only be associated with a single secure key.
|
||
|
|
+This option is only used for secure keys contained in the secure key repository.
|
||
|
|
+.TP
|
||
|
|
+.BR \-a ", " \-\-apqns\~\fI[+|-]card1.domain1[,card2.domain2[,...]]\fP
|
||
|
|
+Specifies a comma-separated list of cryptographic adapters in CCA
|
||
|
|
+coprocessor mode (APQN) which are associated with the secure AES key in the
|
||
|
|
+repository. Each APQN association specifies a card and domain number separated
|
||
|
|
+by a period (like lszcrypt displays it).
|
||
|
|
+To add an APQN to the associated APQNs, prefix the APQN with a \fI+\fP.
|
||
|
|
+To remove an APQN from the associated APQNs, prefix the APQN with a \fI-\fP.
|
||
|
|
+To set (replace) the APQN association do not specify a prefix.
|
||
|
|
+You cannot mix \fI+\fP and \fI-\fP in one specification. You can either add or
|
||
|
|
+remove (or set) the associations with one command.
|
||
|
|
+All APQNs being added or set (replaced) must be online.
|
||
|
|
+This option is only used for secure keys contained in the secure key repository.
|
||
|
|
+.TP
|
||
|
|
+.BR \-S ", " \-\-sector-size\~\fIbytes\fP
|
||
|
|
+Specifies the sector size in bytes used with dm-crypt. It must be a power of two
|
||
|
|
+and in the range 512 - 4096 bytes. If omitted, the system default sector size
|
||
|
|
+is used. Specify \fI0\fP to un-set the sector size so that the system default
|
||
|
|
+is used.
|
||
|
|
+This option is only used for secure keys contained in the secure key repository.
|
||
|
|
+.
|
||
|
|
+.
|
||
|
|
+.
|
||
|
|
+.SS "Options for the rename command"
|
||
|
|
+.TP
|
||
|
|
+.BR \-N ", " \-\-name\~\fIkey-name\fP
|
||
|
|
+Specifies the name of the secure key in the secure key repository. You cannot
|
||
|
|
+use wildcards.
|
||
|
|
+This option is only used for secure keys contained in the secure key repository.
|
||
|
|
+.TP
|
||
|
|
+.BR \-w ", " \-\-new-name\~\fInew-key-name\fP
|
||
|
|
+Specifies the new name of the secure key in the secure key repository.
|
||
|
|
+This option is only used for secure keys contained in the secure key repository.
|
||
|
|
+.
|
||
|
|
+.
|
||
|
|
+.
|
||
|
|
+.SS "Options for the copy command"
|
||
|
|
+.TP
|
||
|
|
+.BR \-N ", " \-\-name\~\fIkey-name\fP
|
||
|
|
+Specifies the name of the secure key to be copied in the secure key repository.
|
||
|
|
+You cannot use wildcards.
|
||
|
|
+This option is only used for secure keys contained in the secure key repository.
|
||
|
|
+.TP
|
||
|
|
+.BR \-w ", " \-\-new-name\~\fInew-key-name\fP
|
||
|
|
+Specifies the new name of the secure key in the secure key repository.
|
||
|
|
+This option is only used for secure keys contained in the secure key repository.
|
||
|
|
+.TP
|
||
|
|
+.BR \-l ", " \-\-volumes\~\fIvolume1:dmname1,volume2:dmname2[,...]]\fP
|
||
|
|
+Volume associations are not copied, because a volume can only be associated
|
||
|
|
+with a single secure key. To associate different volumes with the copied
|
||
|
|
+secure AES key, specify a comma-separated list of volumes (block devices).
|
||
|
|
+These volumes are to be encrypted using dm-crypt with the secure AES key. The
|
||
|
|
+volume association also contains the device-mapper name, separated by a colon,
|
||
|
|
+used with dm-crypt.
|
||
|
|
+This option is only used for secure keys contained in the secure key repository.
|
||
|
|
+.
|
||
|
|
+.
|
||
|
|
+.
|
||
|
|
+.SS "Options for the crypttab command"
|
||
|
|
+.TP
|
||
|
|
+.BR \-l ", " \-\-volumes\~\fIvolume1[:dmname1][,volume2[:dmname2][,...]]\fP
|
||
|
|
+Specifies a comma-separated list of volumes (block devices) which are
|
||
|
|
+associated with secure AES keys in the repository.
|
||
|
|
+The volume association also contains the device-mapper name, separated by a
|
||
|
|
+colon, used with dm-crypt. You can omit the device-mapper name; if it is
|
||
|
|
+specified then only those keys are selected that are associated with the
|
||
|
|
+specified volume and device-mapper name. You can use wildcards to specify
|
||
|
|
+the volumes and device-mapper names.
|
||
|
|
+When wildcards are used you must quote the value.
|
||
|
|
+This option is only used for secure keys contained in the secure key repository.
|
||
|
|
+.
|
||
|
|
+.
|
||
|
|
+.
|
||
|
|
+.SS "Options for the cryptsetup command"
|
||
|
|
+.TP
|
||
|
|
+.BR \-l ", " \-\-volumes\~\fIvolume1[:dmname1][,volume2[:dmname2][,...]]\fP
|
||
|
|
+Specifies a comma-separated list of volumes (block devices) which are
|
||
|
|
+associated with secure AES keys in the repository.
|
||
|
|
+The volume association also contains the device-mapper name, separated by a
|
||
|
|
+colon, used with dm-crypt. You can omit the device-mapper name; if it is
|
||
|
|
+specified then only those keys are selected that are associated with the
|
||
|
|
+specified volume and device-mapper name. You can use wildcards to specify
|
||
|
|
+the volumes and device-mapper names.
|
||
|
|
+When wildcards are used you must quote the value.
|
||
|
|
+This option is only used for secure keys contained in the secure key repository.
|
||
|
|
+.TP
|
||
|
|
+.BR \-r ", " \-\-run\fP
|
||
|
|
+Runs the generated cryptsetup commands. When an execution of a cryptsetup
|
||
|
|
+command fails, no further cryptsetup commands are executed, and zkey ends
|
||
|
|
+with an error.
|
||
|
|
+This option is only used for secure keys contained in the secure key repository.
|
||
|
|
+.
|
||
|
|
+.
|
||
|
|
.
|
||
|
|
.SS "General options"
|
||
|
|
.TP
|
||
|
|
@@ -186,16 +885,25 @@ Displays version information and exits.
|
||
|
|
.SH EXAMPLES
|
||
|
|
.TP
|
||
|
|
.B zkey generate seckey.bin
|
||
|
|
-Generates a 256-bit secure AES key and stores it in file 'seckey.bin'.
|
||
|
|
+Generates a random 256-bit secure AES key and stores it in file 'seckey.bin'.
|
||
|
|
.TP
|
||
|
|
.B zkey generate seckey.bin \-\-keybits 128 \-\-xts
|
||
|
|
-Generates a 128-bit secure AES key for the XTS cipher mode and stores it
|
||
|
|
+Generates a random 128-bit secure AES key for the XTS cipher mode and stores it
|
||
|
|
in file 'seckey.bin'.
|
||
|
|
.TP
|
||
|
|
.B zkey generate seckey.bin \-\-clearkey clearkey.bin
|
||
|
|
Generates a secure AES key from the clear key in file 'clearkey.bin' and
|
||
|
|
stores it in file 'seckey.bin'.
|
||
|
|
.TP
|
||
|
|
+.B zkey generate --name seckey
|
||
|
|
+Generates a random 256-bit secure AES key and stores it in the secure key
|
||
|
|
+repository under the name 'seckey'.
|
||
|
|
+.TP
|
||
|
|
+.B zkey generate --name seckey --volumes /dev/dasdc1:encvol --apqns 03.004c
|
||
|
|
+Generates a random 256-bit secure AES key and stores it in the secure key
|
||
|
|
+repository under the name 'seckey' and associates it with block
|
||
|
|
+device '/dev/dasdc1' and device-mapper name 'encvol', and APQN '03.004c'.
|
||
|
|
+.TP
|
||
|
|
.B zkey reencipher seckey.bin \-\-from\-old
|
||
|
|
Re-enciphers the secure key in file 'seckey.bin' which is currently enciphered
|
||
|
|
with the master key in the OLD register with the master key in the CURRENT
|
||
|
|
@@ -207,5 +915,49 @@ Re-enciphers the secure key in file 'sec
|
||
|
|
with the master key in the CURRENT register with the master key in the NEW
|
||
|
|
register, and saves the re-enciphered secure key to file 'seckey2.bin'.
|
||
|
|
.TP
|
||
|
|
+.B zkey reencipher --name seckey
|
||
|
|
+Re-enciphers the secure key 'seckey' in the secure key repository.
|
||
|
|
+.TP
|
||
|
|
+.B zkey reencipher --apqns 03.004c
|
||
|
|
+Re-enciphers all secure keys contained in the secure key repository that are
|
||
|
|
+associated with APQN '03.004c'.
|
||
|
|
+.TP
|
||
|
|
.B zkey validate seckey.bin
|
||
|
|
Validates the secure key in file 'seckey.bin' and displays its attributes.
|
||
|
|
+.TP
|
||
|
|
+.B zkey validate --name seckey
|
||
|
|
+Validates the secure key 'seckey' in the secure key repository and displays its
|
||
|
|
+attributes.
|
||
|
|
+.TP
|
||
|
|
+.B zkey list
|
||
|
|
+Lists all secure keys in the secure key repository and displays its
|
||
|
|
+attributes.
|
||
|
|
+.TP
|
||
|
|
+.B zkey list --name '*key'
|
||
|
|
+Lists all secure keys in the secure key repository with names ending with 'key'
|
||
|
|
+and displays its attributes.
|
||
|
|
+.TP
|
||
|
|
+.B zkey change --name seckey --volumes +/dev/dasdc2:encvol2
|
||
|
|
+Changes the secure key 'seckey' in the secure key repository and adds
|
||
|
|
+volume '/dev/dasdc2' with device-mapper name 'encvol2' to the list of associated
|
||
|
|
+volumes of this secure key.
|
||
|
|
+.TP
|
||
|
|
+.B zkey change --name seckey --apqns -03.004c
|
||
|
|
+Changes the secure key 'seckey' in the secure key repository and removes
|
||
|
|
+APQN '03.004c' from the list of associated APQNs of this secure key.
|
||
|
|
+.TP
|
||
|
|
+.B zkey crypttab --volumes '/dev/dasdc*'
|
||
|
|
+Generates crypttab entries for all volumes that match the pattern '/dev/dasdc*'.
|
||
|
|
+.TP
|
||
|
|
+.B zkey cryptsetup --volumes '*:enc_dasd'
|
||
|
|
+Generates cryptsetup commands for the volumes that uses the device-mapper
|
||
|
|
+name 'enc_dasd'.
|
||
|
|
+.
|
||
|
|
+.SH ENVIRONMENT
|
||
|
|
+.TP
|
||
|
|
+.BR ZKEY_REPOSITORY
|
||
|
|
+If
|
||
|
|
+.B $ZKEY_REPOSITORY
|
||
|
|
+is set, it specifies the location of the secure key repository.
|
||
|
|
+If it is not set, then the the default location of the secure key
|
||
|
|
+repository is \fB/etc/zkey/repository\fP.
|
||
|
|
\ No newline at end of file
|