diff --git a/zkey/keystore.c b/zkey/keystore.c index bbf64fe6..cab6f769 100644 --- a/zkey/keystore.c +++ b/zkey/keystore.c @@ -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; diff --git a/zkey/keystore.h b/zkey/keystore.h index 510c4a51..0cc3fd81 100644 --- a/zkey/keystore.h +++ b/zkey/keystore.h @@ -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" diff --git a/zkey/pkey.c b/zkey/pkey.c index 5343b071..6e954da1 100644 --- a/zkey/pkey.c +++ b/zkey/pkey.c @@ -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 * diff --git a/zkey/pkey.h b/zkey/pkey.h index a13e08a2..93c506bf 100644 --- a/zkey/pkey.h +++ b/zkey/pkey.h @@ -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); diff --git a/zkey/pvsecrets.c b/zkey/pvsecrets.c index 2c07f666..b326447c 100644 --- a/zkey/pvsecrets.c +++ b/zkey/pvsecrets.c @@ -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", diff --git a/zkey/zkey-cryptsetup.1 b/zkey/zkey-cryptsetup.1 index caf8d758..e962cfd4 100644 --- a/zkey/zkey-cryptsetup.1 +++ b/zkey/zkey-cryptsetup.1 @@ -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 diff --git a/zkey/zkey-cryptsetup.c b/zkey/zkey-cryptsetup.c index 632d3c2e..0a5ec5f2 100644 --- a/zkey/zkey-cryptsetup.c +++ b/zkey/zkey-cryptsetup.c @@ -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; diff --git a/zkey/zkey.1 b/zkey/zkey.1 index 3dbe41ff..395425b9 100644 --- a/zkey/zkey.1 +++ b/zkey/zkey.1 @@ -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=\fP or run command \fBzkey crypttab \-\-volumes \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 \-\-volume\-key\-file -\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 +\-\-volume\-key\-file \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 diff --git a/zkey/zkey.c b/zkey/zkey.c index 90d3e907..a08fac1b 100644 --- a/zkey/zkey.c +++ b/zkey/zkey.c @@ -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; }