kata-containers/s390-tools
1
0
Fork 0
mirror of https://github.com/ibm-s390-linux/s390-tools.git synced 2026-08-05 02:14:52 +00:00
Code Issues Packages Projects Releases Wiki Activity

zkey: Add PVSECRET-HMAC key type and general HMAC support

Browse Source 
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>
This commit is contained in:
Ingo Franzki
2024-03-11 17:17:58 +01:00
committed by Jan Höppner
parent c3d8208a57
commit a9059449b9
9 changed files with 493 additions and 304 deletions
Download Patch File Download Diff File Expand all files Collapse all files

41
zkey/keystore.c
View File

@@ -357,6 +357,8 @@ static int _keystore_valid_key_type(const char *key_type)
return 1;
if (strcasecmp(key_type, KEY_TYPE_PVSECRET_AES) == 0)
return 1;
if (strcasecmp(key_type, KEY_TYPE_PVSECRET_HMAC) == 0)
return 1;
return 0;
}
@@ -1588,12 +1590,12 @@ static int _keystore_set_timestamp_property(struct properties *properties,
}
/**
* Sets the default properties of a key, such as key-type, cipher-name, and
* IV-mode
* Sets the default properties of an AES key, such as cipher-name, IV-mode,
* and timestamps
*
* @param[in] key_props the properties object
*/
static int _keystore_set_default_properties(struct properties *key_props)
static int _keystore_set_default_aes_properties(struct properties *key_props)
{
int rc;
@@ -1613,6 +1615,32 @@ static int _keystore_set_default_properties(struct properties *key_props)
return 0;
}
/**
* Sets the default properties of an HMAC key, such as cipher-name and
* timestmmps
*
* @param[in] key_props the properties object
*/
static int _keystore_set_default_hmac_properties(struct properties *key_props)
{
int rc;
rc = properties_set(key_props, PROP_NAME_CIPHER, "phmac");
if (rc != 0)
return rc;
rc = properties_set(key_props, PROP_NAME_DIGEST, "sha");
if (rc != 0)
return rc;
rc = _keystore_set_timestamp_property(key_props,
PROP_NAME_CREATION_TIME);
if (rc != 0)
return rc;
return 0;
}
/**
* Generate, Set or remove a dummy LUKS2 passphrase of a key.
*
@@ -1785,7 +1813,12 @@ static int _keystore_create_info_props(struct keystore *keystore,
*props = NULL;
key_props = properties_new();
rc = _keystore_set_default_properties(key_props);
if (is_aes_key_type(key_type))
rc = _keystore_set_default_aes_properties(key_props);
else if (is_hmac_key_type(key_type))
rc = _keystore_set_default_hmac_properties(key_props);
else
rc = -EINVAL;
if (rc != 0)
goto out;

1
zkey/keystore.h
View File

@@ -29,6 +29,7 @@ struct keystore {
#define PROP_NAME_KEY_TYPE "key-type"
#define PROP_NAME_CIPHER "cipher"
#define PROP_NAME_IV_MODE "iv-mode"
#define PROP_NAME_DIGEST "digest"
#define PROP_NAME_DESCRIPTION "description"
#define PROP_NAME_VOLUMES "volumes"
#define PROP_NAME_APQNS "apqns"

118
zkey/pkey.c
View File

@@ -1863,6 +1863,35 @@ bool is_pvsecret_aes_key(const u8 *key, size_t key_size)
}
}
/**
* Check if the specified key is a PVSECRET-HMAC key token.
*
* @param[in] key the secure key token
* @param[in] key_size the size of the secure key
*
* @returns true if the key is a PVSECRET token type
*/
bool is_pvsecret_hmac_key(const u8 *key, size_t key_size)
{
struct pvsecrettoken *pvsecret = (struct pvsecrettoken *)key;
if (key == NULL || key_size < PVSECRET_KEY_SIZE)
return false;
if (pvsecret->hdr.type != TOKEN_TYPE_NON_CCA)
return false;
if (pvsecret->hdr.version != TOKEN_VERSION_PVSECRET)
return false;
switch (pvsecret->secret_type) {
case UV_SECRET_TYPE_HMAC_SHA_256:
case UV_SECRET_TYPE_HMAC_SHA_512:
return true;
default:
return false;
}
}
/**
* Check if the specified key is an XTS type key
*
@@ -1930,6 +1959,46 @@ bool is_secure_key(const u8 *key, size_t key_size)
return false;
}
/**
* Check if the specified key is an AES key type
*
* @param[in] key the secure key token
* @param[in] key_size the size of the secure key
*
* @returns true if the key is a secure key type
*/
bool is_aes_key(const u8 *key, size_t key_size)
{
if (is_cca_aes_data_key(key, key_size))
return true;
if (is_cca_aes_cipher_key(key, key_size))
return true;
if (is_ep11_aes_key(key, key_size))
return true;
if (is_ep11_aes_key_with_header(key, key_size))
return true;
if (is_pvsecret_aes_key(key, key_size))
return true;
return false;
}
/**
* Check if the specified key is an HMAC key type
*
* @param[in] key the secure key token
* @param[in] key_size the size of the secure key
*
* @returns true if the key is a secure key type
*/
bool is_hmac_key(const u8 *key, size_t key_size)
{
if (is_pvsecret_hmac_key(key, key_size))
return true;
return false;
}
/**
* Gets the size in bits of the effective key of the specified secure key
*
@@ -2002,6 +2071,17 @@ int get_key_bit_size(const u8 *key, size_t key_size, size_t *bitsize)
default:
return -EINVAL;
}
} else if (is_pvsecret_hmac_key(key, key_size)) {
switch (pvsecret->secret_type) {
case UV_SECRET_TYPE_HMAC_SHA_256:
*bitsize = 512;
break;
case UV_SECRET_TYPE_HMAC_SHA_512:
*bitsize = 1024;
break;
default:
return -EINVAL;
}
} else {
return -EINVAL;
}
@@ -2029,6 +2109,8 @@ const char *get_key_type(const u8 *key, size_t key_size)
return KEY_TYPE_EP11_AES;
if (is_pvsecret_aes_key(key, key_size))
return KEY_TYPE_PVSECRET_AES;
if (is_pvsecret_hmac_key(key, key_size))
return KEY_TYPE_PVSECRET_HMAC;
return NULL;
}
@@ -2052,6 +2134,42 @@ bool is_secure_key_type(const char *key_type)
return false;
}
/**
* Returns true if the key type is an AES key type
*
* @param[in] key_type the type of the key
*
* @returns true if the key type is an AES key type, false otherwise
*/
bool is_aes_key_type(const char *key_type)
{
if (strcasecmp(key_type, KEY_TYPE_CCA_AESCIPHER) == 0)
return true;
if (strcasecmp(key_type, KEY_TYPE_CCA_AESDATA) == 0)
return true;
if (strcasecmp(key_type, KEY_TYPE_EP11_AES) == 0)
return true;
if (strcasecmp(key_type, KEY_TYPE_PVSECRET_AES) == 0)
return true;
return false;
}
/**
* Returns true if the key type is a HMAC key type
*
* @param[in] key_type the type of the key
*
* @returns true if the key type is a HMAC key type, false otherwise
*/
bool is_hmac_key_type(const char *key_type)
{
if (strcasecmp(key_type, KEY_TYPE_PVSECRET_HMAC) == 0)
return true;
return false;
}
/**
* Returns the minimum card level for a specific key type
*

6
zkey/pkey.h
View File

@@ -302,6 +302,7 @@ struct pkey_apqns4keytype {
#define KEY_TYPE_CCA_AESCIPHER "CCA-AESCIPHER"
#define KEY_TYPE_EP11_AES "EP11-AES"
#define KEY_TYPE_PVSECRET_AES "PVSECRET-AES"
#define KEY_TYPE_PVSECRET_HMAC "PVSECRET-HMAC"
#define DEFAULT_KEYBITS 256
#define PAES_BLOCK_SIZE 16
@@ -367,11 +368,16 @@ bool is_ep11_aes_key(const u8 *key, size_t key_size);
bool is_ep11_aes_key_with_header(const u8 *key, size_t key_size);
bool is_ep11_key_session_bound(const u8 *key, size_t key_size);
bool is_pvsecret_aes_key(const u8 *key, size_t key_size);
bool is_pvsecret_hmac_key(const u8 *key, size_t key_size);
bool is_xts_key(const u8 *key, size_t key_size);
bool is_secure_key(const u8 *key, size_t key_size);
bool is_aes_key(const u8 *key, size_t key_size);
bool is_hmac_key(const u8 *key, size_t key_size);
int get_key_bit_size(const u8 *key, size_t key_size, size_t *bitsize);
const char *get_key_type(const u8 *key, size_t key_size);
bool is_secure_key_type(const char *key_type);
bool is_aes_key_type(const char *key_type);
bool is_hmac_key_type(const char *key_type);
int get_min_card_level_for_keytype(const char *key_type);
const struct fw_version *get_min_fw_version_for_keytype(const char *key_type);
enum card_type get_card_type_for_keytype(const char *key_type);

4
zkey/pvsecrets.c
View File

@@ -53,9 +53,9 @@ static const struct pvsecret_type_info pvsecret_type_info[] = {
{ .type = UV_SECRET_TYPE_AES_XTS_256, .name = "AES-XTS-256",
.zkey_usage = true },
{ .type = UV_SECRET_TYPE_HMAC_SHA_256, .name = "HMAC-SHA-256",
.zkey_usage = false },
.zkey_usage = true },
{ .type = UV_SECRET_TYPE_HMAC_SHA_512, .name = "HMAC-SHA-512",
.zkey_usage = false },
.zkey_usage = true },
{ .type = UV_SECRET_TYPE_ECDSA_P256, .name = "ECDSA-P256",
.zkey_usage = false },
{ .type = UV_SECRET_TYPE_ECDSA_P384, .name = "ECDSA-P384",

85
zkey/zkey-cryptsetup.1
View File

@@ -4,8 +4,9 @@
.\"
.TH ZKEY\-CRYPTSETUP 1 "February 2024" "s390-tools"
.SH NAME
zkey\-cryptsetup \- Manage secure AES volume keys of volumes encrypted with
\fBLUKS2\fP and the \fBpaes\fP cipher
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
@@ -25,9 +26,10 @@ zkey\-cryptsetup \- Manage secure AES volume keys of volumes encrypted with
.
.
.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
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
@@ -43,7 +45,7 @@ see the corresponding man pages.
.SH COMMANDS
.
.
.SS "Validate secure AES volume keys"
.SS "Validate secure AES or HMAC volume keys"
.
.B zkey\-cryptsetup
.BR validate | val
@@ -61,16 +63,18 @@ see the corresponding man pages.
.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.
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.
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 do not use a
cryptographic adapter, thus no master key information is displayed for such
keys.
\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
@@ -87,7 +91,7 @@ and
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"
.SS "Re-encipher secure AES or HMAC volume keys"
.
.PP
.B zkey\-cryptsetup
@@ -112,14 +116,16 @@ behave in the same way as with \fBcryptsetup\fP.
.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
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 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.
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:
@@ -172,7 +178,8 @@ 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
\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
@@ -214,15 +221,15 @@ behave in the same way as with \fBcryptsetup\fP.
.PP
The
.B reencipher
command creates a new key slot with the re-enciphered secure AES volume key.
The new key slot uses
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
uses secure AES keys as volume keys, the security of the key derivation
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
@@ -235,7 +242,7 @@ downloads, see: \fIhttp://www.ibm.com/security/cryptocards\fP
.
.
.
.SS "Set a verification pattern of the secure AES volume key"
.SS "Set a verification pattern of the secure AES or HMAC volume key"
.
.B zkey\-cryptsetup
.BR setvp | setv
@@ -253,9 +260,11 @@ downloads, see: \fIhttp://www.ibm.com/security/cryptocards\fP
.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.
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
@@ -280,7 +289,7 @@ behave in the same way as with \fBcryptsetup\fP.
.
.
.
.SS "Set a new secure AES volume key for a volume"
.SS "Set a new secure AES or HMAC volume key for a volume"
.
.B zkey\-cryptsetup
.BR setkey | setk
@@ -302,11 +311,12 @@ behave in the same way as with \fBcryptsetup\fP.
Use the
.B setkey
command to set a new secure AES volume key for a volume encrypted with
\fBLUKS2\fP and the \fBpaes\fP cipher. Use this command to recover from an
invalid secure AES volume key contained in the LUKS2 header.
A secure AES volume key contained in the LUKS2 header can become invalid when
the CCA or EP11 master key is changed without re-enciphering the secure volume
key.
\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
@@ -355,7 +365,7 @@ relevance.
.
.
.
.SS "Convert a clear-key LUKS2 volume to use a secure AES volume key"
.SS "Convert a clear-key LUKS2 volume to use a secure AES or HMAC volume key"
.
.B zkey\-cryptsetup
.BR convert | conv
@@ -377,7 +387,8 @@ relevance.
Use the
.B convert
command to convert a clear-key \fBLUKS2\fP volume to use a secure volume key
and the \fBpaes\fP cipher. You must provide a secure volume key that uses
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
@@ -469,8 +480,8 @@ Suppresses all confirmation questions. Use with care!
.SS "Options for the setkey command"
.TP
.BR \-m ", " \-\-volume\-key\-file\~\fIfile\-name\fP
Specifies the name of a file containing the secure AES key that is set as the
new volume key.
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

40
zkey/zkey-cryptsetup.c
View File

@@ -73,7 +73,8 @@ static void misc_print_required_parms(const char *parm_name1,
*/
static const struct util_prg prg = {
.desc = "Manage secure volume keys of volumes encrypted with LUKS2 and "
"the 'paes' cipher",
"the 'paes' cipher, and optionally integrity protected with "
"the 'phmac' cipher.",
.command_args = "COMMAND DEVICE",
.args = "",
.copyright_vec = {
@@ -234,7 +235,8 @@ static struct util_opt opt_vec[] = {
.option = {"volume-key-file", required_argument, NULL, 'm'},
.argument = "FILE-NAME",
.desc = "Specifies the name of a file containing the secure "
"AES key that is set as new volume key",
"AES key (and optionally a secure HMAC key) that "
"is set as new volume key",
.command = COMMAND_SETKEY,
},
{
@@ -332,7 +334,9 @@ static struct zkey_cryptsetup_command zkey_cryptsetup_commands[] = {
.need_pkey_device = 1,
.short_desc = "Re-encipher a secure volume key",
.long_desc = "Re-encipher a secure volume key of a volume "
"encrypted with LUKS2 and the 'paes' cipher",
"encrypted with LUKS2 and the 'paes' cipher, and "
"optionally integrity protected with the 'phmac' "
"cipher",
.has_options = 1,
.pos_arg = "DEVICE",
.open_device = 1,
@@ -345,7 +349,9 @@ static struct zkey_cryptsetup_command zkey_cryptsetup_commands[] = {
.need_pkey_device = 1,
.short_desc = "Validate a secure volume key",
.long_desc = "Validate a secure volume key of a volume "
"encrypted with LUKS2 and the 'paes' cipher",
"encrypted with LUKS2 and the 'paes' cipher, and "
"optionally integrity protected with the 'phmac' "
"cipher",
.has_options = 1,
.pos_arg = "DEVICE",
.open_device = 1,
@@ -358,9 +364,10 @@ static struct zkey_cryptsetup_command zkey_cryptsetup_commands[] = {
.need_pkey_device = 1,
.short_desc = "Set a verification pattern of the secure volume "
"key",
.long_desc = "Set a verification pattern of the secure AES "
.long_desc = "Set a verification pattern of the secure "
"volume key of a volume encrypted with LUKS2 and "
"the 'paes' cipher",
"the 'paes' cipher, and optionally integrity "
"protected with the 'phmac' cipher",
.has_options = 1,
.pos_arg = "DEVICE",
.open_device = 1,
@@ -372,8 +379,10 @@ static struct zkey_cryptsetup_command zkey_cryptsetup_commands[] = {
.function = command_setkey,
.need_pkey_device = 1,
.short_desc = "Set a new secure volume key",
.long_desc = "Set a new secure AES volume key for a volume "
"encrypted with LUKS2 and the 'paes' cipher",
.long_desc = "Set a new secure volume key for a volume "
"encrypted with LUKS2 and the 'paes' cipher, and "
"optionally integrity protected with the 'phmac' "
"cipher",
.has_options = 1,
.pos_arg = "DEVICE",
.open_device = 1,
@@ -388,7 +397,8 @@ static struct zkey_cryptsetup_command zkey_cryptsetup_commands[] = {
"secure volume key",
.long_desc = "Convert a LUKS2 volume that uses a clear volume "
"key and the 'aes' cipher to use a secure volume "
"key and the 'paes' cipher",
"key and the 'paes' cipher, optionally integrity "
"protected with the 'phmac' cipher",
.has_options = 1,
.pos_arg = "DEVICE",
.open_device = 1,
@@ -1754,7 +1764,7 @@ static int reencipher_prepare(int token)
if (rc != 0) {
if (rc == -ENODEV) {
warnx("No APQN found that is suitable for "
"re-enciphering the secure AES volume "
"re-enciphering the secure volume "
"key from the OLD to the CURRENT master "
"key.");
} else {
@@ -1766,7 +1776,7 @@ static int reencipher_prepare(int token)
!is_ep11_aes_key_with_header((u8 *)key,
securekeysize))
print_msg_for_cca_envvars(
"secure AES volume key");
"secure volume key");
rc = -EINVAL;
}
goto out;
@@ -1780,7 +1790,7 @@ static int reencipher_prepare(int token)
if (rc != 0) {
if (rc == -ENODEV) {
warnx("No APQN found that is suitable for "
"re-enciphering the secure AES volume "
"re-enciphering the secure volume "
"key from the CURRENT to the NEW master "
"key.");
} else {
@@ -1792,7 +1802,7 @@ static int reencipher_prepare(int token)
!is_ep11_aes_key_with_header((u8 *)key,
securekeysize))
print_msg_for_cca_envvars(
"secure AES volume key");
"secure volume key");
rc = -EINVAL;
}
goto out;
@@ -1923,7 +1933,7 @@ static int reencipher_complete(int token)
if (rc != 0) {
if (rc == -ENODEV) {
warnx("No APQN found that is suitable for "
"re-enciphering the secure AES volume "
"re-enciphering the secure volume "
"key from the OLD to the CURRENT master "
"key.");
} else {
@@ -1935,7 +1945,7 @@ static int reencipher_complete(int token)
!is_ep11_aes_key_with_header((u8 *)key,
securekeysize))
print_msg_for_cca_envvars(
"secure AES volume key");
"secure volume key");
rc = -EINVAL;
}
goto out;

293
zkey/zkey.1
View File

@@ -4,7 +4,7 @@
.\"
.TH ZKEY 1 "February 2024" "s390-tools"
.SH NAME
zkey \- Manage secure AES keys
zkey \- Manage secure AES or HMAC keys
.
.
.SH SYNOPSIS
@@ -29,10 +29,10 @@ zkey \- Manage secure AES keys
.
.
.SH DESCRIPTION
Use the \fBzkey\fP tool to generate and manage secure AES keys that are
Use the \fBzkey\fP tool to generate and manage secure AES or HMAC keys that are
enciphered with a master key of an IBM cryptographic adapter in CCA or EP11
coprocessor mode, dependent on the key type. You can also use the \fBzkey\fP
tool to validate and re-encipher secure AES keys.
tool to validate and re-encipher secure AES or HMAC 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
@@ -88,7 +88,7 @@ option is specified then it operates on a secure key contained in the secure
key repository.
.
.PP
.SS "Generating secure AES keys"
.SS "Generating secure AES or HMAC keys"
.
.B zkey
.BR generate | gen
@@ -138,13 +138,14 @@ key repository.
.PP
Use the
.B generate
command to generate a new secure AES key either randomly within the CCA or EP11
cryptographic adapter, from a clear AES key specified as input, or using a key
management system plugin (KMS plugin). When specifying 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 or EP11 cryptographic adapter
that contains the master key with which the secure key was generated.
command to generate a new secure AES or HMAC key either randomly within the CCA
or EP11 cryptographic adapter, from a clear AES or HMAC key specified as input,
or using a key management system plugin (KMS plugin). When specifying 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 or EP11
cryptographic adapter that contains the master key with which the secure key
was generated.
.PP
When the secure key repository is bound to a key management system plugin (KMS
plugin), then the secure key is generated by using the key management system,
@@ -211,7 +212,7 @@ the access control point is \fBOFF\fP or not supported by the EP11 firmware,
key generation fails with a generic error (Input/output error). The \fBzkey\fP
tool prints an appropriate error message in that case.
.
.SS "Validating secure AES keys"
.SS "Validating secure AES or HMAC keys"
.
.B zkey
.BR validate | val
@@ -236,9 +237,9 @@ 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, 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. Keys of type \fBPVSECRET\-AES\fP do not use a
cryptographic adapter, thus no master key information is displayed for such
keys.
\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
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
@@ -265,7 +266,7 @@ or
are specified, then all secure keys contained in the key repository
are validated.
.
.SS "Re-encipher existing AES secure keys"
.SS "Re-encipher existing AES or HMAC secure keys"
.
.B zkey
.BR reencipher | re
@@ -295,9 +296,9 @@ command to re-encipher an existing secure key with a new master key.
A secure key must be re-enciphered when the master key of the CCA or EP11
cryptographic adapter changes.
.PP
Keys of type \fBPVSECRET\-AES\fP can not be re-enciphered. These keys do not
use a cryptographic adapter, thus they do not need to be re-enciphered when the
master of a cryptographic adapter changes.
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 of a cryptographic adapter changes.
.PP
The CCA cryptographic adapter has three different registers to store
master keys:
@@ -397,7 +398,7 @@ PKCS #11 (EP11) Support Program (EP11 host library) for secure keys of type
EP11\-AES to be installed. For the supported environments and downloads, see:
\fIhttp://www.ibm.com/security/cryptocards\fP
.
.SS "Import existing AES secure keys into the secure key repository"
.SS "Import existing AES or HMAC secure keys into the secure key repository"
.
.B zkey
.BR import | im
@@ -436,8 +437,8 @@ additional information can be associated with a secure key using the
.B \-\-sector\-size
options.
.PP
Keys of type \fBPVSECRET\-AES\fP do not use a cryptographic adapter, thus APQNs
can not be associated with them.
Keys of type \fBPVSECRET\-AES\fP and \fBPVSECRET\-HMAC\fP do not use a
cryptographic adapter, thus APQNs can not be associated with them.
.PP
.B Note:
The \fBimport\fP command requires the CCA host library (libcsulcca.so)
@@ -452,7 +453,7 @@ the protection of the IBM cryptographic adapter (HSM). If exportability of an
imported key is required, specify option \fB\-\-exportable\fP. The import
operation will then not change the exportability of the secure key.
.
.SS "Export AES secure keys from the secure key repository"
.SS "Export AES or HMAC secure keys from the secure key repository"
.
.B zkey
.BR export | ex
@@ -471,7 +472,7 @@ using the
option. You cannot use wildcards.
The exported secure key also remains in the secure key repository.
.
.SS "List AES secure keys contained in the secure key repository"
.SS "List AES or HMAC secure keys contained in the secure key repository"
.
.B zkey
.BR list | li
@@ -509,7 +510,7 @@ sector size, the key verification pattern, timestamps for key creation, last
modification and last re-encipherment, and whether the key is local or
bound to a key management system (KMS).
.
.SS "Remove existing AES secure keys from the secure key repository"
.SS "Remove existing AES or HMAC secure keys from the secure key repository"
.
.B zkey
.BR remove | rem
@@ -548,7 +549,7 @@ removed, these volumes can no longer be used, unless you have a backup of the
secure key. For keys with volume type \fBluks2\fP no such message is issued,
because the secure key is contained in the LUKS2 header.
.
.SS "Change existing AES secure keys contained the secure key repository"
.SS "Change existing AES or HMAC secure keys contained the secure key repository"
.
.B zkey
.BR change | ch
@@ -602,15 +603,15 @@ 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
For secure AES keys that are bound to a key management system (KMS) you can not
change the APQN association. KMS-bound secure AES keys are always bound to the
APQNs that are associated with the key management system plugin.
For secure AES or HMAC keys that are bound to a key management system (KMS) you
can not change the APQN association. KMS-bound secure AES keys are always bound
to the APQNs that are associated with the key management system plugin.
Other associated information is also changed in the key management system when
changed using the change command.
.PP
For keys of type \fBPVSECRET\-AES\fP you can not change or set the APQN
association. These keys do not use a cryptographic adapter, thus APQNs can not
be associated with them.
For keys of type \fBPVSECRET\-AES\fP and \fBPVSECRET\-HMAC\fP you can not change
or set the APQN association. These keys do not use a cryptographic adapter,
thus APQNs can not be associated with them.
.PP
.B Note:
The secure key itself cannot be changed, only information about the secure
@@ -618,7 +619,7 @@ key is changed. To rename a secure key, use the \fBrename\fP command.
To re-encipher a secure key with a new CCA or EP11 master key, use the
\fBreencipher\fP command.
.
.SS "Rename existing AES secure keys in the secure key repository"
.SS "Rename existing AES or HMAC secure keys in the secure key repository"
.
.B zkey
.BR rename | ren
@@ -647,7 +648,7 @@ plainOpen' commands and in the '/etc/crypttab' entries.
For keys with volume type \fBluks2\fP no such message is issued, because the
secure key is contained in the LUKS2 header.
.
.SS "Copy (duplicate) existing AES secure keys in the secure key repository"
.SS "Copy (duplicate) existing AES or HMAC secure keys in the secure key repository"
.
.B zkey
.B copy | co
@@ -807,7 +808,7 @@ To avoid cryptsetup confirmation questions, you can specify the
option. These options are passed to the generated command(s) and behave in the
same way as with \fBcryptsetup\fP.
.
.SS "Convert existing AES secure keys from one key type to another type"
.SS "Convert existing AES or HMAC secure keys from one key type to another type"
.
.B zkey
.BR convert | con
@@ -863,10 +864,10 @@ and change the key size parameter to \fBsize=<new\-key\-size\-in\-bits>\fP or
run command \fBzkey crypttab \-\-volumes <device>\fP for each associated volume
to re-generate the crypttab entries.
.P
Associated volumes of type \fBLUKS2\fP still contain the secure AES volume key
of the original type. To change the secure AES volume key in the LUKS2 header,
run command \fBzkey\-cryptsetup setkey <device> \-\-volume\-key\-file
<converted\-key>\fP for each associated volume.
Associated volumes of type \fBLUKS2\fP still contain the secure AES or HMAC
volume key of the original type. To change the secure AES or HMAC volume key in
the LUKS2 header, run command \fBzkey\-cryptsetup setkey <device>
\-\-volume\-key\-file <converted\-key>\fP for each associated volume.
.
.P
.B Note:
@@ -1299,9 +1300,9 @@ You might have to install the \fByq\fP package first.
A protected virtualization secret key object does not contain the key material,
but only a reference (i.e. the secret ID) to the key in the ultravisor.
When such a protected virtualization secret key object is used with
\fBdm\-crypt\fP and the \fBPAES\fP kernel cipher, the key material (i.e. a
protected key) is retrieved from the ultravisor and the crypto operation is
performed with it.
\fBdm\-crypt\fP and the \fBPAES\fP kernel cipher, or \fBdm\-integrity\fP and
the \fBPHMAC\fP kernel cipher, the key material (i.e. a protected key) is
retrieved from the ultravisor and the crypto operation is performed with it.
.PP
When importing a protected virtualization secret in a key repository,
additional information can be associated with it using the
@@ -1410,7 +1411,7 @@ for the security of the volume(s), when an secure AES key is used to encrypt the
volume(s), and can therefore be stored insecurely inside the secure key
repository. If for a certain usage the passphrase is of relevance for
security, then do not use this option. This option can only be specified for
keys with a volume type of \fBluks2\fP.
AES-type keys with a volume type of \fBluks2\fP.
This option is only used for secure keys contained in the secure key repository.
.TP
.BR \-\-set\-dummy\-passphrase\~\fIpassphrase\-file\fP
@@ -1420,7 +1421,7 @@ is of less or no relevance for the security of the volume(s), when an secure
AES key is used to encrypt the volume(s), and can therefore be stored insecurely
inside the secure key repository. If for a certain usage the passphrase is of
relevance for security, then do not use this option. This option can only be
specified for keys with a volume type of \fBluks2\fP.
specified for AES-type keys with a volume type of \fBluks2\fP.
This option is only used for secure keys contained in the secure key repository.
.TP
.B KMS-plugin specific options
@@ -1457,11 +1458,11 @@ This option is only used for secure keys contained in the secure key repository.
.SS "Options for the reencipher command"
.TP
.BR \-n ", " \-\-to\-new
Re-enciphers a secure AES key that is currently enciphered with the
Re-enciphers a secure AES or HMAC key 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 AES key that is currently enciphered with the
Re-enciphers a secure AES or HMAC key that is currently enciphered with the
master key in the OLD register with the master key in the CURRENT register.
This option is only available for secure keys of type CCA\-AESDATA and
CCA\-AESCIPHER.
@@ -1489,20 +1490,21 @@ 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.
Forces an in-place re-enciphering of a secure AES or HMAC 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 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 CURRENT to NEW is performed in staged mode per default.
Forces that the re-enciphering of a secure AES or HMAC 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 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 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
@@ -1526,36 +1528,37 @@ 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 \fBdm\-crypt\fP with the secure AES key. The volume association
also contains the device-mapper name, separated by a colon, used with
\fBdm\-crypt\fP.
associated with the secure AES or HMAC key in the repository. These volumes are
to be encrypted using \fBdm\-crypt\fP with the secure AES key, or are to be
integrity protected using \fBdm\-integrity\fP with the secure HMAC key. The
volume association also contains the device-mapper name, separated by a colon,
used with \fBdm\-crypt\fP or \fBdm\-integrity\fP.
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 or EP11
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,
unless option \fB\-\-no\-apqn\-check\fP is specified.
coprocessor mode (APQN) which are associated with the secure AES or HMAC 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, unless option \fB\-\-no\-apqn\-check\fP is specified.
This option is only used for secure keys contained in the secure key repository.
.TP
.BR \-\-no\-apqn\-check
Do not check if the specified APQNs are available. Use this option to
associate APQNs with a secure AES key that are currently not available.
associate APQNs with a secure AES or HMAC key that are currently not available.
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 \fBdm\-crypt\fP. It must be a
power of two and in the range of 512 to 4096 bytes. If omitted, the system
default sector size is used.
Specifies the sector size in bytes used with \fBdm\-crypt\fP or
\fBdm\-integrity\fP. It must be a power of two and in the range of 512 to 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.
.TP
.BR \-t ", " \-\-volume\-type\~\fItype\fP
Specifies the volume type of the associated volumes used with \fBdm\-crypt\fP.
Possible values are \fBplain\fP and \fBluks2\fP. If omitted, \fBluks2\fP is
used.
Specifies the volume type of the associated volumes used with \fBdm\-crypt\fP or
\fBdm\-integrity\fP. Possible values are \fBplain\fP and \fBluks2\fP. If
omitted, \fBluks2\fP is used.
This option is only used for secure keys contained in the secure key repository.
.TP
.BR \-\-gen\-dummy\-passphrase
@@ -1565,7 +1568,7 @@ for the security of the volume(s), when an secure AES key is used to encrypt the
volume(s), and can therefore be stored insecurely inside the secure key
repository. If for a certain usage the passphrase is of relevance for
security, then do not use this option. This option can only be specified for
keys with a volume type of \fBluks2\fP.
AES-type keys with a volume type of \fBluks2\fP.
This option is only used for secure keys contained in the secure key repository.
.TP
.BR \-\-set\-dummy\-passphrase\~\fIpassphrase\-file\fP
@@ -1575,7 +1578,7 @@ is of less or no relevance for the security of the volume(s), when an secure
AES key is used to encrypt the volume(s), and can therefore be stored insecurely
inside the secure key repository. If for a certain usage the passphrase is of
relevance for security, then do not use this option. This option can only be
specified for keys with a volume type of \fBluks2\fP.
specified for AES-type keys with a volume type of \fBluks2\fP.
This option is only used for secure keys contained in the secure key repository.
.
.
@@ -1600,35 +1603,35 @@ 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.
associated with the secure AES or HMAC 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 \fBdm\-crypt\fP. 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.
colon, used with \fBdm\-crypt\fP or \fBdm\-integrity\fP. 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 or EP11
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.
coprocessor mode (APQN) which are associated with the secure AES or HMAC 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.
.TP
.BR \-t ", " \-\-volume\-type\~\fItype\fP
Specifies the volume type of the associated volumes used with \fBdm\-crypt\fP.
Possible values are \fBplain\fP and \fBluks2\fP. Only keys with the specified
volume type are listed.
Specifies the volume type of the associated volumes used with \fBdm\-crypt\fP or
\fBdm\-integrity\fP. Possible values are \fBplain\fP and \fBluks2\fP. Only keys
with the specified volume type are listed.
This option is only used for secure keys contained in the secure key repository.
.TP
.BR \-K ", " \-\-key\-type\~\fItype\fP
Specifies the key type of the secure key. Possible values are
\fBCCA\-AESDATA\fP, \fBCCA\-AESCIPHER\fP, \fBEP11\-AES\fP, and
\fBPVSECRET\-AES\fP. Only keys with the specified key type are listed.
\fBCCA\-AESDATA\fP, \fBCCA\-AESCIPHER\fP, \fBEP11\-AES\fP, \fBPVSECRET\-AES\fP,
and \fBPVSECRET\-HMAC\fP. Only keys with the specified key type are listed.
This option is only used for secure keys contained in the secure key repository.
.TP
.BR \-L ", " \-\-local\fP
@@ -1682,10 +1685,11 @@ 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 \fBdm\-crypt\fP with the secure AES key. The volume association
also contains the device-mapper name, separated by a colon, used with
\fBdm\-crypt\fP.
associated with the secure AES or HMAC key in the repository. These volumes are
to be encrypted using \fBdm\-crypt\fP with the secure AES key, or are to be
integrity protected using \fBdm\-integrit\fP with the secure HMAC key. The
volume association also contains the device-mapper name, separated by a colon,
used with \fBdm\-crypt\fP or \fBdm\-integrity\fP.
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.
@@ -1696,9 +1700,9 @@ 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 or EP11
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).
coprocessor mode (APQN) which are associated with the secure AES or HMAC 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.
@@ -1710,18 +1714,18 @@ This option is only used for secure keys contained in the secure key repository.
.TP
.BR \-\-no\-apqn\-check
Do not check if the specified APQNs are available. Use this option to
associate APQNs with a secure AES key that are currently not available.
associate APQNs with a secure AES or HMAC key that are currently not available.
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 \fBdm\-crypt\fP. It must be a power
of two and in the range of 512 to 4096 bytes. Specify \fI0\fP to set the sector
size to the system default.
Specifies the sector size in bytes used with \fBdm\-crypt\fP or
\fBdm\-integrity\fP. It must be a power of two and in the range of 512 to 4096
ytes. Specify \fI0\fP to set the sector size to the system default.
This option is only used for secure keys contained in the secure key repository.
.TP
.BR \-t ", " \-\-volume\-type\~\fItype\fP
Specifies the volume type of the associated volumes used with \fBdm\-crypt\fP.
Possible values are \fBplain\fP and \fBluks2\fP.
Specifies the volume type of the associated volumes used with \fBdm\-crypt\fP or
\fBdm\-integrity\fP. Possible values are \fBplain\fP and \fBluks2\fP.
This option is only used for secure keys contained in the secure key repository.
.TP
.BR \-\-gen\-dummy\-passphrase
@@ -1731,7 +1735,7 @@ for the security of the volume(s), when an secure AES key is used to encrypt the
volume(s), and can therefore be stored insecurely inside the secure key
repository. If for a certain usage the passphrase is of relevance for
security, then do not use this option. This option can only be specified for
keys with a volume type of \fBluks2\fP. When there is already a dummy
AES-type keys with a volume type of \fBluks2\fP. When there is already a dummy
passphrase associated with the key, you must first remove the dummy passphrase
with option \fB\-\-remove\-dummy\-passphrase\fP before you can associate a new
dummy passphrase.
@@ -1794,10 +1798,11 @@ This option is only used for secure keys contained in the secure key repository.
.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\fBdm\-crypt\fP with the secure AES key.
The volume association also contains the device-mapper name, separated by a
colon, used with \fBdm\-crypt\fP.
secure AES or HMAC key, specify a comma-separated list of volumes (block
devices). These volumes are to be encrypted using \fBdm\-crypt\fP with the
secure AES key, or are to be integrity protected using \fBdm\-integrity\fP with
the secure HMAC key. The volume association also contains the device-mapper
name, separated by a colon, used with \fBdm\-crypt\fP or \fBdm\-integrity\fP.
This option is only used for secure keys contained in the secure key repository.
.TP
.BR \-L ", "\-\-local
@@ -2033,19 +2038,19 @@ 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 key management system (KMS). Only
those keys are listed, which are associated with the specified volumes.
associated with the secure AES or HMAC key in the key management system (KMS).
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 \fBdm\-crypt\fP. 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.
colon, used with \fBdm\-crypt\fP or \fBdm\-integrity\fP. 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.
.TP
.BR \-t ", " \-\-volume\-type\~\fItype\fP
Specifies the volume type of the associated volumes used with \fBdm\-crypt\fP.
Possible values are \fBplain\fP and \fBluks2\fP. Only keys with the specified
volume type are listed.
Specifies the volume type of the associated volumes used with \fBdm\-crypt\fP or
\fBdm\-integrity\fP. Possible values are \fBplain\fP and \fBluks2\fP. Only keys
with the specified volume type are listed.
.
.
.
@@ -2065,19 +2070,19 @@ Only keys with names that match the pattern are imported.
.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 key management system (KMS). Only
those keys are imported, which are associated with the specified volumes.
associated with the secure AES or HMAC key in the key management system (KMS).
Only those keys are imported, which are associated with the specified volumes.
The volume association also contains the device-mapper name, separated by a
colon, used with \fBdm\-crypt\fP. 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.
colon, used with \fBdm\-crypt\fP or \fBdm\-integrity\fP. 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.
.TP
.BR \-t ", " \-\-volume\-type\~\fItype\fP
Specifies the volume type of the associated volumes used with \fBdm\-crypt\fP.
Possible values are \fBplain\fP and \fBluks2\fP. Only keys with the specified
volume type are imported.
Specifies the volume type of the associated volumes used with \fBdm\-crypt\fP or
\fBdm\-integrity\fP. Possible values are \fBplain\fP and \fBluks2\fP. Only keys
with the specified volume type are imported.
.TP
.BR \-q ", " \-\-batch\-mode
Suppress prompts to skip or to enter an alternate name, if a secure key with the
@@ -2101,19 +2106,19 @@ Only keys with names that match the pattern are refreshed.
.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
refreshed, which are associated with the specified volumes.
associated with the secure AES or HMAC key in the repository. Only those keys
are refreshed, which are associated with the specified volumes.
The volume association also contains the device-mapper name, separated by a
colon, used with \fBdm\-crypt\fP. 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.
colon, used with \fBdm\-crypt\fP or \fBdm\-integrity\fP. 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.
.TP
.BR \-t ", " \-\-volume\-type\~\fItype\fP
Specifies the volume type of the associated volumes used with \fBdm\-crypt\fP.
Possible values are \fBplain\fP and \fBluks2\fP. Only keys with the specified
volume type are refreshed.
Specifies the volume type of the associated volumes used with \fBdm\-crypt\fP or
\fBdm\-integrity\fP. Possible values are \fBplain\fP and \fBluks2\fP. Only keys
with the specified volume type are refreshed.
.TP
.BR \-K ", " \-\-key\-type\~\fItype\fP
Specifies the key type of the secure key. Possible values are
@@ -2210,19 +2215,21 @@ key repository.
Specifies a comma-separated list of volumes (block devices) which are
associated with the protected virtualization secret in the repository. These
volumes are to be encrypted using \fBdm\-crypt\fP with the protected
virtualization secret. The volume association also contains the device-mapper
name, separated by a colon, used with \fBdm\-crypt\fP. A specific volume can
only be associated with a single key.
virtualization secret, or are to be integrity protected using
\fBdm\-integrity\fP with the protected virtualization secret. The volume
association also contains the device-mapper name, separated by a colon, used
with \fBdm\-crypt\fP or \fBdm\-integrity\fP. A specific volume can only be
associated with a single key.
.TP
.BR \-S ", " \-\-sector\-size\~\fIbytes\fP
Specifies the sector size in bytes used with \fBdm\-crypt\fP. It must be a power
of two and in the range of 512 to 4096 bytes. If omitted, the system default
sector size is used.
Specifies the sector size in bytes used with \fBdm\-crypt\fP or
\fBdm\-integrity\fP. It must be a power of two and in the range of 512 to 4096
bytes. If omitted, the system default sector size is used.
.TP
.BR \-t ", " \-\-volume\-type\~\fItype\fP
Specifies the volume type of the associated volumes used with \fBdm\-crypt\fP.
Possible values are \fBplain\fP and \fBluks2\fP. If omitted, \fBluks2\fP is
used.
Specifies the volume type of the associated volumes used with \fBdm\-crypt\fP or
\fBdm\-integrity\fP. Possible values are \fBplain\fP and \fBluks2\fP. If
omitted, \fBluks2\fP is used.
.TP
.BR \-\-gen\-dummy\-passphrase
Generate a dummy passphrase randomly and associate it with the protected

209
zkey/zkey.c
View File

@@ -40,7 +40,7 @@
* Program configuration
*/
static const struct util_prg prg = {
.desc = "Manage secure AES keys",
.desc = "Manage secure AES and HMAC keys",
.command_args = "COMMAND [SECURE-KEY-FILE]",
.args = "",
.copyright_vec = {
@@ -196,31 +196,33 @@ static struct util_opt opt_vec[] = {
{
.option = { "keybits", required_argument, NULL, 'k'},
.argument = "SIZE",
.desc = "Size of the AES key to be generated in bits. "
"Valid sizes are 128, 192, and 256 bits. Secure keys "
"for use with the XTS cipher mode can only use keys "
" of 128 or 256 bits. Default is 256 bits",
.desc = "Size of the AES or HMAC key to be generated in bits. "
"Valid sizes for AES keys are 128, 192, and 256 bits. "
"Secure keys for use with the XTS cipher mode can only "
"use keys of 128 or 256 bits. Valid sizes for HMAC "
"keys are 256 and 512 bits. Default is 256 bits",
.command = COMMAND_GENERATE,
},
{
.option = { "clearkey", required_argument, NULL, 'c'},
.argument = "CLEAR-KEY-FILE",
.desc = "Name of a file containing the clear AES key in "
"binary. If option --keybits/-k is omitted, then the "
"size of the CLEAR-KEY-FILE determines the size "
"of the AES key. If option --keybits/-k is specified, "
"then the size of the CLEAR-KEY-FILE must match the "
"specified key size. Valid file sizes are 16, 24, or "
"32 bytes, and 32, or 64 bytes for keys to be used "
"with XTS mode ciphers",
.desc = "Name of a file containing the clear AES or HMAC key "
"in binary. If option --keybits/-k is omitted, then "
"the size of the CLEAR-KEY-FILE determines the size "
"of the AES or HMAC key. If option --keybits/-k is "
"specified, then the size of the CLEAR-KEY-FILE must "
"match the specified key size. Valid file sizes for "
"AES keys are 16, 24, or 32 bytes, and 32, or 64 bytes "
"for keys to be used with XTS mode ciphers. For HMAC "
"keys, valid file sizes are 32 or 64 bytes",
.command = COMMAND_GENERATE,
},
{
.option = { "name", required_argument, NULL, 'N'},
.argument = "NAME",
.desc = "Name of the secure AES key in the repository. If "
.desc = "Name of the secure key in the repository. If "
"option --name/-N is specified, then the generated "
"secure AES key is stored in the repository. Parameter "
"secure key is stored in the repository. Parameter "
"SECURE-KEY-FILE is not used when option --name/-N is "
"specified",
.command = COMMAND_GENERATE,
@@ -228,7 +230,7 @@ static struct util_opt opt_vec[] = {
{
.option = { "description", required_argument, NULL, 'd'},
.argument = "DESCRIPTION",
.desc = "Textual description of the secure AES key in the "
.desc = "Textual description of the secure key in the "
"repository",
.command = COMMAND_GENERATE,
},
@@ -236,7 +238,7 @@ static struct util_opt opt_vec[] = {
.option = { "volumes", required_argument, NULL, 'l'},
.argument = "VOLUME:DMNAME[,...]",
.desc = "Comma-separated pairs of volume and device-mapper "
"names that are associated with the secure AES key in "
"names that are associated with the secure key in "
"the repository",
.command = COMMAND_GENERATE,
},
@@ -244,7 +246,7 @@ static struct util_opt opt_vec[] = {
.option = { "apqns", required_argument, NULL, 'a'},
.argument = "CARD.DOMAIN[,...]",
.desc = "Comma-separated pairs of crypto cards and domains "
"that are associated with the secure AES key in the "
"that are associated with the secure key in the "
"repository",
.command = COMMAND_GENERATE,
},
@@ -252,17 +254,17 @@ static struct util_opt opt_vec[] = {
.option = {"no-apqn-check", 0, NULL, OPT_NO_APQN_CHECK},
.desc = "Do not check if the specified APQN(s) are available. "
"Use this option to associate APQN(s) with a secure "
"AES key that are currently not available.",
"key that are currently not available.",
.command = COMMAND_GENERATE,
.flags = UTIL_OPT_FLAG_NOSHORT,
},
{
.option = { "sector-size", required_argument, NULL, 'S'},
.argument = "bytes",
.desc = "The sector size used with dm-crypt. It must be a power "
"of two and in range 512 - 4096 bytes. If this option "
"is omitted, the system default sector size (512) is "
"used",
.desc = "The sector size used with dm-crypt or dm-integrity. "
"It must be a power of two and in range 512 - 4096 "
"bytes. If this option is omitted, the system default "
"sector size (512) is used",
.command = COMMAND_GENERATE,
},
{
@@ -354,14 +356,14 @@ static struct util_opt opt_vec[] = {
},
{
.option = {"to-new", 0, NULL, 'n'},
.desc = "Re-enciphers a secure AES key that is currently "
.desc = "Re-enciphers a secure key that is currently "
"enciphered with the master key in the CURRENT "
"register with the master key in the NEW register",
.command = COMMAND_REENCIPHER,
},
{
.option = {"from-old", 0, NULL, 'o'},
.desc = "Re-enciphers a secure AES key that is currently "
.desc = "Re-enciphers a secure key that is currently "
"enciphered with the master key in the OLD register "
"with the master key in the CURRENT register",
.command = COMMAND_REENCIPHER,
@@ -375,14 +377,14 @@ static struct util_opt opt_vec[] = {
},
{
.option = {"in-place", 0, NULL, 'i'},
.desc = "Forces an in-place re-enchipering of a secure AES "
.desc = "Forces an in-place re-enchipering of a secure "
"key. Re-enciphering from OLD to CURRENT is performed "
"in-place per default",
.command = COMMAND_REENCIPHER,
},
{
.option = {"staged", 0, NULL, 's'},
.desc = "Forces that the re-enciphering of a secure AES key is "
.desc = "Forces that the re-enciphering of a secure key is "
"performed in staged mode. Re-enciphering from CURRENT "
"to NEW is performed in staged mode per default",
.command = COMMAND_REENCIPHER,
@@ -390,7 +392,7 @@ static struct util_opt opt_vec[] = {
{
.option = { "name", required_argument, NULL, 'N'},
.argument = "NAME",
.desc = "Name of the secure AES keys in the repository that "
.desc = "Name of the secure keys in the repository that "
"are to be re-enciphered. You can use wild-cards to "
"select the keys to re-encipher.",
.command = COMMAND_REENCIPHER,
@@ -399,7 +401,7 @@ static struct util_opt opt_vec[] = {
.option = { "apqns", required_argument, NULL, 'a'},
.argument = "CARD.DOMAIN[,...]",
.desc = "Comma-separated pairs of crypto cards and domains "
"that are associated with the secure AES key in the "
"that are associated with the secure key in the "
"repository. Use this option to re-encipher all keys "
"associated with specific crypto cards",
.command = COMMAND_REENCIPHER,
@@ -413,7 +415,7 @@ static struct util_opt opt_vec[] = {
{
.option = { "name", required_argument, NULL, 'N'},
.argument = "NAME",
.desc = "Name of the secure AES keys in the repository that "
.desc = "Name of the secure keys in the repository that "
"are to be validated. You can use wild-cards to select "
"the keys to validate.",
.command = COMMAND_VALIDATE,
@@ -422,7 +424,7 @@ static struct util_opt opt_vec[] = {
.option = { "apqns", required_argument, NULL, 'a'},
.argument = "CARD.DOMAIN[,...]",
.desc = "Comma-separated pairs of crypto cards and domains "
"that are associated with the secure AES key in the "
"that are associated with the secure key in the "
"repository. Use this option to validate all keys "
"associated with specific crypto cards",
.command = COMMAND_VALIDATE,
@@ -442,13 +444,13 @@ static struct util_opt opt_vec[] = {
{
.option = { "name", required_argument, NULL, 'N'},
.argument = "NAME",
.desc = "Name of the imported secure AES key in the repository",
.desc = "Name of the imported secure key in the repository",
.command = COMMAND_IMPORT,
},
{
.option = { "description", required_argument, NULL, 'd'},
.argument = "DESCRIPTION",
.desc = "Textual description of the secure AES key in the "
.desc = "Textual description of the secure key in the "
"repository",
.command = COMMAND_IMPORT,
},
@@ -456,7 +458,7 @@ static struct util_opt opt_vec[] = {
.option = { "volumes", required_argument, NULL, 'l'},
.argument = "VOLUME:DMNAME[,...]",
.desc = "Comma-separated pairs of volume and device-mapper "
"names that are associated with the secure AES key in "
"names that are associated with the secure key in "
"the repository",
.command = COMMAND_IMPORT,
},
@@ -464,7 +466,7 @@ static struct util_opt opt_vec[] = {
.option = { "apqns", required_argument, NULL, 'a'},
.argument = "CARD.DOMAIN[,...]",
.desc = "Comma-separated pairs of crypto cards and domains "
"that are associated with the secure AES key in the "
"that are associated with the secure key in the "
"repository",
.command = COMMAND_IMPORT,
},
@@ -472,17 +474,17 @@ static struct util_opt opt_vec[] = {
.option = {"no-apqn-check", 0, NULL, OPT_NO_APQN_CHECK},
.desc = "Do not check if the specified APQN(s) are available. "
"Use this option to associate APQN(s) with a secure "
"AES key that are currently not available.",
"key that are currently not available.",
.command = COMMAND_IMPORT,
.flags = UTIL_OPT_FLAG_NOSHORT,
},
{
.option = { "sector-size", required_argument, NULL, 'S'},
.argument = "512|4096",
.desc = "The sector size used with dm-crypt. It must be power "
"of two and in range 512 - 4096 bytes. If this option "
"is omitted, the system default sector size (512) is "
"used",
.desc = "The sector size used with dm-crypt or dm-integrity. "
"It must be a power of two and in range 512 - 4096 "
"bytes. If this option is omitted, the system default "
"sector size (512) is used",
.command = COMMAND_IMPORT,
},
{
@@ -540,7 +542,7 @@ static struct util_opt opt_vec[] = {
{
.option = { "name", required_argument, NULL, 'N'},
.argument = "NAME",
.desc = "Name of the secure AES key in the repository that is "
.desc = "Name of the secure key in the repository that is "
"to be exported",
.command = COMMAND_EXPORT,
},
@@ -553,7 +555,7 @@ static struct util_opt opt_vec[] = {
{
.option = { "name", required_argument, NULL, 'N'},
.argument = "NAME",
.desc = "Name of the secure AES keys in the repository that "
.desc = "Name of the secure keys in the repository that "
"are to be listed. You can use wild-cards to select "
"the keys to list.",
.command = COMMAND_LIST,
@@ -562,7 +564,7 @@ static struct util_opt opt_vec[] = {
.option = { "volumes", required_argument, NULL, 'l'},
.argument = "VOLUME[:DMNAME][,...]",
.desc = "Comma-separated pairs of volume and device-mapper "
"names that are associated with the secure AES key in "
"names that are associated with the secure key in "
"the repository. Use this option to list all keys "
"associated with specific volumes. The device-mapper "
"name (DMNAME) is optional. If specified, only those "
@@ -574,7 +576,7 @@ static struct util_opt opt_vec[] = {
.option = { "apqns", required_argument, NULL, 'a'},
.argument = "CARD.DOMAIN[,...]",
.desc = "Comma-separated pairs of crypto cards and domains "
"that are associated with the secure AES key in the "
"that are associated with the secure key in the "
"repository. Use this option to list all keys "
"associated with specific crypto cards",
.command = COMMAND_LIST,
@@ -592,9 +594,9 @@ static struct util_opt opt_vec[] = {
.argument = "type",
.desc = "The type of the key. Possible values are '"
KEY_TYPE_CCA_AESDATA "', '" KEY_TYPE_CCA_AESCIPHER
"', '" KEY_TYPE_EP11_AES "', and '"
KEY_TYPE_PVSECRET_AES "'. Use this option to list all "
"keys with the specified key type.",
"', '" KEY_TYPE_EP11_AES "', '" KEY_TYPE_PVSECRET_AES
"', and '" KEY_TYPE_PVSECRET_HMAC " . Use this option "
"to list all keys with the specified key type.",
.command = COMMAND_LIST,
},
{
@@ -618,7 +620,7 @@ static struct util_opt opt_vec[] = {
{
.option = { "name", required_argument, NULL, 'N'},
.argument = "NAME",
.desc = "Name of the secure AES key in the repository that is "
.desc = "Name of the secure key in the repository that is "
"to be removed",
.command = COMMAND_REMOVE,
},
@@ -636,14 +638,14 @@ static struct util_opt opt_vec[] = {
{
.option = { "name", required_argument, NULL, 'N'},
.argument = "NAME",
.desc = "Name of the secure AES key in the repository that is "
.desc = "Name of the secure key in the repository that is "
"to be changed",
.command = COMMAND_CHANGE,
},
{
.option = { "description", required_argument, NULL, 'd'},
.argument = "DESCRIPTION",
.desc = "Textual description of the secure AES key in the "
.desc = "Textual description of the secure key in the "
"repository",
.command = COMMAND_CHANGE,
},
@@ -651,7 +653,7 @@ static struct util_opt opt_vec[] = {
.option = { "volumes", required_argument, NULL, 'l'},
.argument = "[+|-]VOLUME:DMNAME[,...]",
.desc = "Comma-separated pairs of volume and device-mapper "
"names that are associated with the secure AES key in "
"names that are associated with the secure key in "
"the repository. To add pairs of volume and device-"
"mapper names to the key specify '+VOLUME:DMNAME[,...]'. "
"To remove pairs of volume and device-mapper names "
@@ -662,7 +664,7 @@ static struct util_opt opt_vec[] = {
.option = { "apqns", required_argument, NULL, 'a'},
.argument = "[+|-]CARD.DOMAIN[,...]",
.desc = "Comma-separated pairs of crypto cards and domains "
"that are associated with the secure AES key in the "
"that are associated with the secure key in the "
"repository. To add pairs of crypto cards and domains "
"to the key specify '+CARD.DOMAIN[,...]'. To remove "
"pairs of crypto cards and domains from the key "
@@ -673,16 +675,17 @@ static struct util_opt opt_vec[] = {
.option = {"no-apqn-check", 0, NULL, OPT_NO_APQN_CHECK},
.desc = "Do not check if the specified APQN(s) are available. "
"Use this option to associate APQN(s) with a secure "
"AES key that are currently not available.",
"key that are currently not available.",
.command = COMMAND_CHANGE,
.flags = UTIL_OPT_FLAG_NOSHORT,
},
{
.option = { "sector-size", required_argument, NULL, 'S'},
.argument = "0|512|4096",
.desc = "The sector size used with dm-crypt. It must be power "
"of two and in range 512 - 4096 bytes. Specify 0 to "
"use the system default sector size (512)",
.desc = "The sector size used with dm-crypt or dm-integrity. "
"It must be a power of two and in range 512 - 4096 "
"bytes. If this option is omitted, the system default "
"sector size (512) is used",
.command = COMMAND_CHANGE,
},
{
@@ -740,14 +743,14 @@ static struct util_opt opt_vec[] = {
{
.option = { "name", required_argument, NULL, 'N'},
.argument = "NAME",
.desc = "Name of the secure AES key in the repository that is "
.desc = "Name of the secure key in the repository that is "
"to be renamed",
.command = COMMAND_RENAME,
},
{
.option = { "new-name", required_argument, NULL, 'w'},
.argument = "NEW-NAME",
.desc = "New name of the secure AES key in the repository",
.desc = "New name of the secure key in the repository",
.command = COMMAND_RENAME,
},
/***********************************************************/
@@ -759,21 +762,21 @@ static struct util_opt opt_vec[] = {
{
.option = { "name", required_argument, NULL, 'N'},
.argument = "NAME",
.desc = "Name of the secure AES key in the repository that is "
.desc = "Name of the secure key in the repository that is "
"to be copied",
.command = COMMAND_COPY,
},
{
.option = { "new-name", required_argument, NULL, 'w'},
.argument = "NEW-NAME",
.desc = "New name of the secure AES key in the repository",
.desc = "New name of the secure key in the repository",
.command = COMMAND_COPY,
},
{
.option = { "volumes", required_argument, NULL, 'l'},
.argument = "VOLUME:DMNAME[,...]",
.desc = "Comma-separated pairs of volume and device-mapper "
"names that are associated with the copied secure AES "
"names that are associated with the copied secure "
"key in the repository. If option '--volumes/-l' is "
"omitted, no volumes are associated with the copied "
"key, because only one key can be associated to a "
@@ -969,7 +972,7 @@ static struct util_opt opt_vec[] = {
{
.option = { "name", required_argument, NULL, 'N'},
.argument = "NAME",
.desc = "Name of the secure AES key in the repository that is "
.desc = "Name of the secure key in the repository that is "
"to be converted",
.command = COMMAND_CONVERT,
},
@@ -1070,7 +1073,7 @@ static struct util_opt opt_vec[] = {
{
.option = { "label", required_argument, NULL, 'B'},
.argument = "LABEL",
.desc = "Label of the secure AES keys as known by the KMS that "
.desc = "Label of the secure keys as known by the KMS that "
"are to be listed. You can use wildcards to select "
"the keys to be listed.",
.command = COMMAND_KMS " " COMMAND_KMS_LIST,
@@ -1078,7 +1081,7 @@ static struct util_opt opt_vec[] = {
{
.option = { "name", required_argument, NULL, 'N'},
.argument = "NAME",
.desc = "Name of the secure AES keys as known by zkey that "
.desc = "Name of the secure keys as known by zkey that "
"are to be listed. You can use wildcards to select "
"the keys to be listed.",
.command = COMMAND_KMS " " COMMAND_KMS_LIST,
@@ -1087,7 +1090,7 @@ static struct util_opt opt_vec[] = {
.option = { "volumes", required_argument, NULL, 'l'},
.argument = "VOLUME[:DMNAME][,...]",
.desc = "Comma-separated pairs of volume and device-mapper "
"names that are associated with the secure AES key in "
"names that are associated with the secure key in "
"the KMS. Use this option to list all keys "
"associated with specific volumes. The device-mapper "
"name (DMNAME) is optional. If specified, only those "
@@ -1112,7 +1115,7 @@ static struct util_opt opt_vec[] = {
{
.option = { "label", required_argument, NULL, 'B'},
.argument = "LABEL",
.desc = "Label of the secure AES keys as known by the KMS that "
.desc = "Label of the secure keys as known by the KMS that "
"are to be imported. You can use wildcards to select "
"the keys to be imported.",
.command = COMMAND_KMS " " COMMAND_KMS_IMPORT,
@@ -1120,7 +1123,7 @@ static struct util_opt opt_vec[] = {
{
.option = { "name", required_argument, NULL, 'N'},
.argument = "NAME",
.desc = "Name of the secure AES keys as known by zkey that "
.desc = "Name of the secure keys as known by zkey that "
"are to be imported. You can use wildcards to select "
"the keys to be imported.",
.command = COMMAND_KMS " " COMMAND_KMS_IMPORT,
@@ -1129,7 +1132,7 @@ static struct util_opt opt_vec[] = {
.option = { "volumes", required_argument, NULL, 'l'},
.argument = "VOLUME[:DMNAME][,...]",
.desc = "Comma-separated pairs of volume and device-mapper "
"names that are associated with the secure AES key in "
"names that are associated with the secure key in "
"the KMS. Use this option to import all keys "
"associated with specific volumes. The device-mapper "
"name (DMNAME) is optional. If specified, only those "
@@ -1170,7 +1173,7 @@ static struct util_opt opt_vec[] = {
{
.option = { "name", required_argument, NULL, 'N'},
.argument = "NAME",
.desc = "Name of the secure AES keys in the repository that "
.desc = "Name of the secure keys in the repository that "
"are to be refreshed. You can use wildcards to select "
"the keys to be refreshed.",
.command = COMMAND_KMS " " COMMAND_KMS_REFRESH,
@@ -1179,7 +1182,7 @@ static struct util_opt opt_vec[] = {
.option = { "volumes", required_argument, NULL, 'l'},
.argument = "VOLUME[:DMNAME][,...]",
.desc = "Comma-separated pairs of volume and device-mapper "
"names that are associated with the secure AES key in "
"names that are associated with the secure key in "
"the repository. Use this option to refresh all keys "
"associated with specific volumes. The device-mapper "
"name (DMNAME) is optional. If specified, only those "
@@ -1206,7 +1209,7 @@ static struct util_opt opt_vec[] = {
},
{
.option = {"refresh-properties", 0, NULL, 'P'},
.desc = "Also refresh the properties of the secure AES key "
.desc = "Also refresh the properties of the secure key "
"and update them with the values from the KMS.",
.command = COMMAND_KMS " " COMMAND_KMS_REFRESH,
},
@@ -1314,10 +1317,10 @@ static struct util_opt opt_vec[] = {
{
.option = { "sector-size", required_argument, NULL, 'S'},
.argument = "512|4096",
.desc = "The sector size used with dm-crypt. It must be a power "
"of two and in range 512 - 4096 bytes. If this option "
"is omitted, the system default sector size (512) is "
"used",
.desc = "The sector size used with dm-crypt or dm-integrity. "
"It must be a power of two and in range 512 - 4096 "
"bytes. If this option is omitted, the system default "
"sector size (512) is used",
.command = COMMAND_PVSECRETS " " COMMAND_PVSECRETS_IMPORT,
},
{
@@ -1614,8 +1617,8 @@ static struct zkey_command zkey_commands[] = {
.abbrev_len = 3,
.function = command_generate,
.need_pkey_device = 1,
.short_desc = "Generate a secure AES key",
.long_desc = "Generate a secure AES key either by "
.short_desc = "Generate a secure AES or HMAC key",
.long_desc = "Generate a secure AES or HMAC key either by "
"random or from a specified clear key and store "
"it either into SECURE-KEY-FILE or into the "
"repository",
@@ -1633,8 +1636,8 @@ static struct zkey_command zkey_commands[] = {
.function = command_reencipher,
/* Will load the CCA or EP11 library on demand */
.need_pkey_device = 1,
.short_desc = "Re-encipher an existing secure AES key",
.long_desc = "Re-encipher an existing secure AES "
.short_desc = "Re-encipher an existing secure key",
.long_desc = "Re-encipher an existing secure "
"key that is either contained in SECURE-KEY-FILE "
"or is stored in the repository with another "
"master key",
@@ -1647,8 +1650,8 @@ static struct zkey_command zkey_commands[] = {
.abbrev_len = 3,
.function = command_validate,
.need_pkey_device = 1,
.short_desc = "Validate an existing secure AES key",
.long_desc = "Validate an existing secure AES key that is "
.short_desc = "Validate an existing secure key",
.long_desc = "Validate an existing secure key that is "
"either contained in SECURE-KEY-FILE or is stored "
"in the repository and print information about "
"the key",
@@ -1660,8 +1663,8 @@ static struct zkey_command zkey_commands[] = {
.command = COMMAND_IMPORT,
.abbrev_len = 2,
.function = command_import,
.short_desc = "Import a secure AES key",
.long_desc = "Import a secure AES key from a file into the "
.short_desc = "Import a secure key",
.long_desc = "Import a secure key from a file into the "
"repository",
.has_options = 1,
.pos_arg = "SECURE-KEY-FILE",
@@ -1671,8 +1674,8 @@ static struct zkey_command zkey_commands[] = {
.command = COMMAND_EXPORT,
.abbrev_len = 2,
.function = command_export,
.short_desc = "Export a secure AES key",
.long_desc = "Export a secure AES key from the repository to "
.short_desc = "Export a secure key",
.long_desc = "Export a secure key from the repository to "
"a file",
.has_options = 1,
.pos_arg = "SECURE-KEY-FILE",
@@ -1683,7 +1686,7 @@ static struct zkey_command zkey_commands[] = {
.abbrev_len = 2,
.function = command_list,
.short_desc = "List keys in the repository",
.long_desc = "List secure AES key in the repository",
.long_desc = "List secure keys in the repository",
.has_options = 1,
.need_keystore = 1,
},
@@ -1691,8 +1694,8 @@ static struct zkey_command zkey_commands[] = {
.command = COMMAND_REMOVE,
.abbrev_len = 3,
.function = command_remove,
.short_desc = "Remove a secure AES key",
.long_desc = "Remove a secure AES key from the repository",
.short_desc = "Remove a secure key",
.long_desc = "Remove a secure key from the repository",
.has_options = 1,
.need_keystore = 1,
.use_kms_plugin = 1,
@@ -1702,8 +1705,8 @@ static struct zkey_command zkey_commands[] = {
.command = COMMAND_CHANGE,
.abbrev_len = 2,
.function = command_change,
.short_desc = "Change a secure AES key",
.long_desc = "Change the properties of a secure AES key in "
.short_desc = "Change a secure key",
.long_desc = "Change the properties of a secure key in "
"the repository",
.has_options = 1,
.need_keystore = 1,
@@ -1713,8 +1716,8 @@ static struct zkey_command zkey_commands[] = {
.command = COMMAND_RENAME,
.abbrev_len = 3,
.function = command_rename,
.short_desc = "Rename a secure AES key",
.long_desc = "Rename a secure AES key in the repository",
.short_desc = "Rename a secure key",
.long_desc = "Rename a secure key in the repository",
.has_options = 1,
.need_keystore = 1,
.use_kms_plugin = 1,
@@ -1723,8 +1726,8 @@ static struct zkey_command zkey_commands[] = {
.command = COMMAND_COPY,
.abbrev_len = 2,
.function = command_copy,
.short_desc = "Copy a secure AES key",
.long_desc = "Copy a secure AES key in the repository",
.short_desc = "Copy a secure key",
.long_desc = "Copy a secure key in the repository",
.has_options = 1,
.need_keystore = 1,
},
@@ -1753,8 +1756,8 @@ static struct zkey_command zkey_commands[] = {
.function = command_convert,
.need_cca_library = 1,
.need_pkey_device = 1,
.short_desc = "Convert a secure AES key",
.long_desc = "Convert an existing secure AES key that is "
.short_desc = "Convert a secure key",
.long_desc = "Convert an existing secure key that is "
"either contained in SECURE-KEY-FILE or is stored "
"in the repository from one key type to another "
"type.",
@@ -2233,7 +2236,7 @@ static int command_reencipher_file(void)
if (rc != 0) {
if (rc == -ENODEV) {
warnx("No APQN found that is suitable for "
"re-enciphering the secure AES volume "
"re-enciphering the secure volume "
"key");
} else {
warnx("Re-encipher from OLD to CURRENT "
@@ -2244,7 +2247,7 @@ static int command_reencipher_file(void)
!is_ep11_aes_key_with_header(secure_key,
secure_key_size))
print_msg_for_cca_envvars(
"secure AES key");
"secure key");
}
rc = EXIT_FAILURE;
goto out;
@@ -2260,7 +2263,7 @@ static int command_reencipher_file(void)
if (rc != 0) {
if (rc == -ENODEV) {
warnx("No APQN found that is suitable for "
"re-enciphering the secure AES volume "
"re-enciphering the secure volume "
"key and has the NEW master key loaded");
} else {
warnx("Re-encipher from CURRENT to NEW "
@@ -2271,7 +2274,7 @@ static int command_reencipher_file(void)
!is_ep11_aes_key_with_header(secure_key,
secure_key_size))
print_msg_for_cca_envvars(
"secure AES key");
"secure key");
}
rc = EXIT_FAILURE;
goto out;
@@ -2846,7 +2849,7 @@ static int command_convert_file(void)
}
if (rc != 0) {
warnx("No APQN found that is suitable for "
"converting the secure AES key in file '%s'", g.pos_arg);
"converting the secure key in file '%s'", g.pos_arg);
rc = EXIT_FAILURE;
goto out;
}
@@ -2873,7 +2876,7 @@ static int command_convert_file(void)
warnx("Converting the secure key from %s to %s has failed",
get_key_type(secure_key, secure_key_size), g.key_type);
if (!selected)
print_msg_for_cca_envvars("secure AES key");
print_msg_for_cca_envvars("secure key");
rc = EXIT_FAILURE;
goto out;
}
@@ -2885,7 +2888,7 @@ static int command_convert_file(void)
warnx("Export restricting the converted secure key "
"has failed");
if (!selected)
print_msg_for_cca_envvars("secure AES key");
print_msg_for_cca_envvars("secure key");
rc = EXIT_FAILURE;
goto out;
}