Creating Objects
This article describes the things to keep in mind when creating objects on a Primus HSM. Operations that create objects include:
- Key generation
- Key import
- Certificate import
- Data import
- Copying objects
It is critical to plan the lifecycle of an object before creating it. The choices made during creation affect how objects can be used later.
This page gives an overview of the restrictions that apply to objects after their creation. These are common pitfalls that you should consider when creating an object. Generally, it comes down to choosing the right key attributes at creation time.
Modifiability
The modifiable key attribute defines whether an object's attributes can be modified.
This attribute can only be set during creation.
Exportability
See the Exporting Objects guide for details regarding the restrictions that apply on exporting objects from the HSM.
Destroyability
The destroyable key attribute defines whether an object's attributes can be modified.
This attribute can only be set during creation.
If you create an object with destroyable=false,
the only way to delete the object is to delete the entire Partition.
Labels
Primus HSM enforces that labels are unique. If you have Key Invalidation enabled, you may have keys that have been deleted via the API but are still present in the "trash bin". The labels of these keys cannot be reused until the key is permanently deleted by the Security Officer (SO).
Smart Key Attributes
SKA keys have additional metadata attached to them, such as an SKA policy. You declare if a key is an SKA key at creation time. Afterwards it is not possible to upgrade a normal key to an SKA key or vice versa.
It is also possible to lock yourself out of an SKA key, for example, by defining a never-fulfillable policy, or by losing access to the private keys of the approvers listed in the policy.
Session Objects
Session Objects are temporary objects that are only kept in memory for the duration of a session. They are immediately discarded after the session is closed, and are never written to disk. Session Objects are sometimes called "external", "temporary", or "ephemeral" objects.
For example, this is useful to temporarily generate a child key of a crypto currency wallet. This allows storing only the master key on the HSM, and deriving the child keys and wallet addresses on-demand.
For PKCS#11, use CKA_TOKEN = false to create a session object.
For JCE, see the ExternalKeySample.
Session Objects must be enabled in the Security Configuration of the HSM. For details, see Section 4.6.1.2 "Crypto Policy" of the Primus HSM User Guide.
Troubleshooting
What if you have created an object with the wrong attributes, and now you have an object you would like to modify, but cannot?
The easiest and recommended approach is to delete the object and start again by generating a new one. Your business application should support mechanisms to roll over to a new key. This is recommended, as key rotation is a normal part of the key lifecycle. Keys may need to be rotated for a number of reasons, such as key wearout, key compromise, or regulatory compliance. A well-designed application makes it easy to rotate to a new key.