Key Attributes
The HSM enforces that a key can only be used for operations that are allowed by the key's attributes.
For example, a key that has only the sign attribute set cannot be used for decryption.
This makes key attributes useful to enforce the principle of key separation.
You can set the two types of attributes on a key: access and capability attributes.
Capability
Capability attributes restrict what kind of operations can be done with a key.
| Attribute | Description |
|---|---|
| encrypt | Whether the key can be used to encrypt data. |
| decrypt | Whether the key can be used to decrypt data. |
| sign | Whether the key can be used to sign data and create MAC tags. |
| verify | Whether the key can be used to verify signatures and MAC tags. |
| wrap | Whether the key can be used to wrap (encrypt) other keys for secure transmission or storage. This attribute is only supported for symmetric keys. |
| unwrap | Whether the key can be used to unwrap (decrypt) encrypted keys. |
| derive | Whether the key can be used to derive other keys. |
| bip32 | If true, key derivation is done using BIP32. This option can only be true if the key's algorithm is EC or ED and the derive attribute is true. |
| slip10 | If true, key derivation is done using SLIP10. This option can only be true if the key's algorithm is EC or ED and the derive attribute is true. |
Internal capabilities
The following capability attributes are used to mark special keys. They are explicitly generated by the user. However, these keys cannot be used by a user to perform operations, only by the HSM itself. They require the root key store to be set up.
| Attribute | Description |
|---|---|
attestation | Key is used to sign attestations. This key has a corresponding certificate chain leading up to the Securosys root certificate. |
timestamp | Key is used to sign timestamps. This key has a corresponding certificate chain leading up to the Securosys root certificate. |
integrity | Key is used to sign integrity statements. Using this attribute and this type of key is no longer recommended. Use a key with the attestation attribute instead. |
Access
Access attributes relate to key management: how the key metadata can be changed, whether the key can be exported, deleted, and so on.
Some of the access attributes are not (easily) reversible.
For example, once a key is set to be non-extractable, an application cannot set it back to extractable.
See the table below for which transitions are allowed for a given attribute.
You can find the same table in section 14.8 of the Primus HSM User Guide.
Generally, applications can only set attributes to become stricter. Applications cannot weaken attributes. This protects against compromised applications. However, attributes can be weakened again by restoring the HSM to a backup that was taken before the attributes were strengthened. This requires Security Officer (SO) intervention, and is thus a conscious choice by the operator.
The table below shows the meaning of the attributes. The "allowed changes" show which transitions applications are allowed to perform.
Not all attributes are relevant for and exposed by all API providers.
| Attribute | Meaning of true | Meaning of false | Allowed changes | Comments |
|---|---|---|---|---|
sensitive | Key can only be exported in encrypted format. | Key can be exported in plaintext or encrypted. | False → True | Export still needs to be allowed by extractable. |
extractable | Key is eligible for export. | Key is NOT eligible for export. | True → False | For SKA keys this must be false. |
modifiable | Key attributes and key name can be changed. | Key attributes and key name can NOT be changed. | Any | Does NOT apply to the SKA policy. |
copyable | Key can be copied to external storage (via session objects). | Key can NOT be copied to external storage. | True → False | |
token | The key is stored and synchronized in the cluster. | The key is a session object. It is not synchronized in the cluster and available only for the lifetime of the current session. | Can only be set during key creation | |
indestructible | Key can NOT be deleted (and NOT invalidated). | Key can be deleted (and invalidated). | Can only be set during key creation. | Inverse of destroyable. |
destroyable | Key can be deleted (and invalidated). | Key can NOT be deleted (and NOT invalidated). | Can only be set during key creation. | Inverse of indestructible. |
private | Key is accessible only after PKCS#11 private session login. | Key is public. | Any | |
public | Key is accessible in a public PKCS#11 session. | Key is private. | Any | |
blocked | Key can NOT be used for crypto operations. Key can NOT be deleted. | Key can be used. | False → True | |
no-public-key | When generating a key pair, the public key is not returned (it does not leave the HSM). The public key can be obtained later when creating a signature. | The public key is returned by key generation. | Flag for key creation. | Used in blockchain use cases (to not expose the public key until a signature is made). |
never-extractable | Key was created inside HSM and was never extractable. | Key was imported or marked as extractable at some point. | Set by HSM. Not user-modifiable. | |
always-sensitive | Key was always marked sensitive. | Key was marked as sensitive=false at some point. | Set by HSM. Not user-modifiable. | |
local | Key was created inside the HSM. | Key was imported. | Set by HSM. Not user-modifiable. | |
unique | Key is unique. It could never be copied (not imported, not copyable, not a session object). | There could exist a copy of the key. | Set by HSM. Not user-modifiable. | |
sam-approved | SKA key can be used for SAM approval. | SKA key can NOT be used for SAM approval. Or SAM not activated. | Set by HSM. Not user-modifiable. | Signature Application Module (SAM) for eIDAS use cases. |
Using key attributes in your code
With PKCS#11: call C_GetAttributeValue and C_SetAttributeValue.
With JCE: call PrimusKeyAttributes.getKeyAccessFlag, PrimusKeyAttributes.setKeyAccessFlag
PrimusKeyAttributes.getKeyCapabilityFlags, and PrimusKeyAttributes.setKeyCapabilityFlag.
See this code sample.
Key attestation
Primus HSMs support attestation. An attestation is a signed statement containing, among other things, all attributes of a key. This signed statement allows auditors to verify that a key is securely stored inside a Securosys Primus HSM and what attributes the key has.
The signature is created using a key that has the attestation attribute set.
Such a key has a certificate chain that leads back to the
Securosys root certificates.
The attestation feature requires a license and requires the Root Key Store to be set up on the HSM. Additionally, the attestation key needs to be explicitly created by the user. See the attestation sample for how to obtain attestations from Java.