Key Attestation

Key Attestation is a Primus HSM feature that allows auditors to verify that a key is securely generated and stored inside Primus HSM.

This guide explains how you can create a key attestation using the Primus Tools.

Prerequisites

Before you start, make sure that the Root Key Store is set up on your HSM.

Create Attestation Key

Key attestation requires an attestation key to be created on the Partition. This is the key that will later sign the key attestations.

java -jar primus-tools.jar CreateAttestationKey <HSM connection and credentials> \
    -keyname <keyname> [-keypassword <keypassword>] \
    [-type <type>] [-size <size>] [-curve <curve>]

For example, to create an RSA-4096 attestation key:

java -jar primus-tools.jar CreateAttestationKey <HSM connection and credentials> \
    -keyname attestation-key-rsa-4096 -type RSA -size 4096

For details about the -type, -size, -curve parameters, see the Create Key command.

info

Primus Tools ≤ v2.5.3 only support RSA and EC as attestation keys.

Inspecting the Attestation Key

You can use ListKeyFlags to check that the key has been created as an attestation key:

java -jar primus-tools.jar ListKeyFlags <HSM connection and credentials> \
    -keyname <keyname>

Example output (line wrapping added for clarity):

<keyname> sensitive nonextractable nonmodifiable noncopyable token nonindestructible private nonpublic nonblocked
neverextractable alwayssensitive local nonwrapwithtrusted unique notdecrypt notsign notunwrap notderive notintegrity
attestation nottimestamp notsignrecover decapsulate

Observe that the key has the attestation flag set.

Get Key Attestation

Now that you have an attestation key on the Partition, you can use it to attest a key.

java -jar primus-tools.jar GetAttestation <HSM connection and credentials> \
    -keyname <keyname> [-keypassword <keypassword>] \
    -attestationkeyname <attestationkeyname> [-attestationkeypassword <attestationkeypassword>] \
    [-ca <CA PEM file>] [-out <output file name base>]

Option	Description
-keyname	Label of the key being attested
-keynamepassword	Optional password, if the key is password protected
-attestationkeyname	Name of the key to use to sign the attestation
-attestationkeypassword	Optional password, if the attestation key is password protected
-ca	Certificate of the root CA against which to verify the certificate chain against
-out	Base name for writing the output files. If this is missing, the results are written to stdout.

For convenience, the command automatically verifies the attestation against the provided certificate chain.

danger

If -ca is not provided, the attestation certificate chain is not verified against a trusted source! Only the integrity of the chain itself is checked. You can only detect a fake attestation if you provide an authentic root certificate via the -ca flag.

If -out base is provided, the command produces the following files:

File name	Description
base.xml	The key attributes being attested, in XML format
base.sig	The signature over base.xml, created by the attestation key
base.sig.b64	Same as base.sig, but base64-encoded instead of raw bytes
base.crt	The certificate chain to verify the signature against the Primus HSM Root CA (order: attestation key certificate, device certificate, root certificate)

Verify Key Attestation

Please follow this tutorial to learn how to verify the key attestation using OpenSSL, as an independent, vendor-neutral tool.