Supported Java key attributes
This topic describes how to use a proprietary extension for the JCE provider to set key attributes. Use this extension to set supported key attributes and their values during these operations:
Key generation
Key import
For examples of how to use key attributes, see Code samples for the AWS CloudHSM software library for Java.
Understanding attributes
Use key attributes to specify what actions are permitted on key objects, including public, private or secret keys. Key attributes and values are defined during key object creation operations.
The Java Cryptography Extension (JCE) does not specify how you should set values on key attributes, so most actions were permitted by default. In contrast, the PKCS# 11 standard defines a comprehensive set of attributes with more restrictive defaults. Starting with the JCE provider 3.1, AWS CloudHSM provides a proprietary extension that enables you to set more restrictive values for commonly used attributes.
Supported attributes
You can set values for the attributes listed in the following table. As a best practice, only set values for attributes you wish to make restrictive. If you don’t specify a value, AWS CloudHSM uses the default value specified in the table below. An empty cell in the Default Value columns indicates that there is no specific default value assigned to the attribute.
| Attribute | Default Value | Notes | ||
|---|---|---|---|---|
| Symmetric Key | Public Key in Key Pair | Private Key in Key Pair | ||
DECRYPT |
TRUE |
TRUE |
True indicates you can use the key to decrypt any buffer. You generally set this to FALSE for a key whose WRAP is set to true. | |
DERIVE |
Allows a key to be used to derive other keys. | |||
ENCRYPT |
TRUE |
TRUE |
True indicates you can use the key to encrypt any buffer. | |
EXTRACTABLE |
TRUE |
TRUE |
True indicates you can export this key out of the HSM. | |
ID |
|
|
A user-defined value used to identify the key. | |
KEY_TYPE |
Used to identify the type of key (AES, DESede, generic secret, EC, or RSA). | |||
LABEL |
A user-defined string allowing you to conveniently identify keys on your HSM. To follow best practice, use a unique label for each key so it is easier to find later. | |||
LOCAL |
Indicates a key generated by the HSM. | |||
OBJECT_CLASS |
Used to identify the Object Class of a key (SecretKey, PublicKey or PrivateKey). | |||
PRIVATE |
TRUE |
TRUE |
TRUE |
True indicates that a user may not access the key until the user is authenticated. For clarity, users cannot access any keys on AWS CloudHSM until they are authenticated, even if this attribute is set to FALSE. |
SIGN |
TRUE |
TRUE |
True indicates you can use the key to sign a message digest. This is generally set to FALSE for public keys and for private keys that you have archived. | |
SIZE |
An attribute that defines the size of a key. For more details about supported key sizes, refer to Supported mechanisms for Client SDK 5. | |||
TOKEN |
FALSE |
FALSE |
FALSE |
A permanent key which is replicated across all HSMs in the cluster and included in backups. TOKEN = FALSE implies an ephemeral key which is automatically erased when the connection to the HSM is broken or logged out. |
UNWRAP |
TRUE |
TRUE |
True indicates you can use the key to unwrap (import) another key. | |
VERIFY |
TRUE |
TRUE |
True indicates you can use the key to verify a signature. This is generally set to FALSE for private keys. | |
WRAP |
TRUE |
TRUE |
True indicates you can use the key to wrap another key. You will generally set this to FALSE for private keys. | |
WRAP_WITH_TRUSTED |
FALSE |
FALSE |
True indicates a key can only be wrapped and unwrapped with keys that have the
TRUSTED attribute set to true. Once a key has WRAP_WITH_TRUSTED set to true, that attribute is read-only and can’t be set to false.
To read about trust wrapping, see Using trusted keys to control key unwraps. |
|
Note
You get broader support for attributes in the PKCS#11 library. For more information, see Supported PKCS #11 Attributes.
Setting attributes for a key
KeyAttributesMap is a Java
Map-like object, which you can use to set attribute values for key objects. The
methods for KeyAttributesMap function similar to the methods used
for Java map manipulation.
To set custom values on attributes, you have two options:
Use the methods listed in the following table
Use builder patterns demonstrated later in this document
Attribute map objects support the following methods to set attributes:
| Operation | Return Value | KeyAttributesMap method |
|---|---|---|
| Get the value of a key attribute for an existing key | Object (containing the value) or null |
get(keyAttribute) |
| Populate the value of one key attribute | The previous value associated with key attribute, or null if there was no mapping for a key attribute |
put(keyAttribute, value) |
| Populate values for multiple key attributes | N/A |
putAll(keyAttributesMap) |
| Remove a key-value pair from the attribute map |
The previous value associated with key attribute, or null if there was no mapping for a key attribute |
remove(keyAttribute) |
Note
Any attributes you do not explicitly specify are set to the defaults listed in the preceding table in Supported attributes.
Setting attributes for a key pair
Use the Java class KeyPairAttributesMap to handle key attributes for a
key pair. KeyPairAttributesMap encapsulates two
KeyAttributesMap objects; one for a public key and one for
a private key.
To set individual attributes for the public key and private key separately, you can use the
put() method on corresponding KeyAttributes
map object for that key. Use the getPublic() method to retrieve the
attribute map for the public key, and use getPrivate() to retrieve the
attribute map for the private key. Populate the value of multiple key attributes
together for both public and private key pairs using the putAll() with
a key pair attributes map as its argument.
