AWS CloudHSM key attribute reference for KMU
The AWS CloudHSM key_mgmt_util commands use constants to represent the attributes of keys in a hardware security module (HSM). This topic can help you to identify the attributes, find the constants that represent them in commands, and understand their values.
You set the attributes of a key when you create it. To change the token attribute, which
indicates whether a key is persistent or exists only in the session, use the setAttribute command in key_mgmt_util. To change the label,
wrap, unwrap, encrypt, or decrypt attributes, use the setAttribute command in
cloudhsm_mgmt_util.
To get a list of attributes and their constants, use listAttributes. To get the attribute values for a key, use getAttribute.
The following table lists the key attributes, their constants, and their valid values.
| Attribute | Constant | Values |
|---|---|---|
| OBJ_ATTR_ALL |
512 |
Represents all attributes. |
| OBJ_ATTR_ALWAYS_SENSITIVE |
357 |
0: False. 1: True. |
| OBJ_ATTR_CLASS |
0 |
2: Public key in a public–private key pair. 3: Private key in a public–private key pair.4: Secret (symmetric) key. |
| OBJ_ATTR_DECRYPT |
261 |
0: False. 1: True. The key can be used to decrypt data. |
| OBJ_ATTR_DERIVE |
268 |
0: False. 1: True. The function derives the key. |
| OBJ_ATTR_DESTROYABLE |
370 |
0: False. 1: True. |
| OBJ_ATTR_ENCRYPT |
260 |
0: False. 1: True. The key can be used to encrypt data. |
| OBJ_ATTR_EXTRACTABLE |
354 |
0: False. 1: True. The key can be exported from the HSMs. |
| OBJ_ATTR_ID |
258 | User-defined string. Must be unique in the cluster. The default is an empty string. |
| OBJ_ATTR_KCV |
371 |
Key check value of the key. For more information, see Additional Details. |
| OBJ_ATTR_KEY_TYPE |
256 | 0: RSA. 1: DSA. 3: EC. 16: Generic secret. 18: RC4. 21: Triple DES (3DES). 31: AES. |
| OBJ_ATTR_LABEL |
3 |
User-defined string. It does not have to be unique in the cluster. |
| OBJ_ATTR_LOCAL |
355 |
0. False. The key was imported into the HSMs. 1: True. |
| OBJ_ATTR_MODULUS |
288 |
The modulus that was used to generate an RSA key pair. For EC keys, this value represents the DER-encoding of ANSI X9.62 ECPoint value "Q" in a hexadecimal format. For other key types, this attribute does not exist. |
| OBJ_ATTR_MODULUS_BITS |
289 |
The length of the modulus used to generate an RSA key pair. For EC keys this represents the ID of the elliptic curve used to generate the key. For other key types, this attribute does not exist. |
| OBJ_ATTR_NEVER_EXTRACTABLE |
356 |
0: False. 1: True. The key cannot be exported from the HSMs. |
| OBJ_ATTR_PUBLIC_EXPONENT |
290 |
The public exponent used to generate an RSA key pair. For other key types, this attribute does not exist. |
| OBJ_ATTR_PRIVATE |
2 |
0: False. 1: True. This attribute indicates whether unauthenticated users can list the attributes of the key. Since the CloudHSM PKCS#11 provider currently does not support public sessions, all keys (including public keys in a public-private key pair) have this attribute set to 1. |
| OBJ_ATTR_SENSITIVE |
259 |
0: False. Public key in a public–private key pair. 1: True. |
| OBJ_ATTR_SIGN |
264 |
0: False. 1: True. The key can be used for signing (private keys). |
| OBJ_ATTR_TOKEN |
1 |
0: False. Session key. 1: True. Persistent key. |
| OBJ_ATTR_TRUSTED |
134 |
0: False. 1: True. |
| OBJ_ATTR_UNWRAP |
263 |
0: False. 1: True. The key can be used to decrypt keys. |
| OBJ_ATTR_UNWRAP_TEMPLATE |
1073742354 |
Values should use the attribute template applied to any key unwrapped using this wrapping key. |
| OBJ_ATTR_VALUE_LEN |
353 |
Key length in bytes. |
| OBJ_ATTR_VERIFY |
266 |
0: False. 1: True. The key can be used for verification (public keys). |
| OBJ_ATTR_WRAP |
262 |
0: False. 1: True. The key can be used to encrypt keys. |
| OBJ_ATTR_WRAP_TEMPLATE |
1073742353 |
Values should use the attribute template to match the key wrapped using this wrapping key.. |
| OBJ_ATTR_WRAP_WITH_TRUSTED |
528 |
0: False. 1: True. |
Additional Details
- Key check value (KCV)
The key check value (KCV) is a 3-byte hash or checksum of a key that is generated when the HSM imports or generates a key. You can also calculate a KCV outside of the HSM, such as after you export a key. You can then compare the KCV values to confirm the identity and integrity of the key. To get the KCV of a key, use getAttribute.
AWS CloudHSM uses the following standard method to generate a key check value:
-
Symmetric keys: First 3 bytes of the result of encrypting a zero-block with the key.
-
Asymmetric key pairs: First 3 bytes of the SHA-1 hash of the public key.
-
HMAC keys: KCV for HMAC keys is not supported at this time.
-
