Skip to main content

Key Attestation

Tip

In the European Union such as eIDAS, it is often the case that the issuance of qualified digital certificates (QTSP) comply with specific legal and regulatory requirements. The ability to generate CSRs through a REST API helps streamline the certificate issuance process and ensures compliance with relevant standards and regulations.

Key Attestation procedure​

Using the TSB / REST API the following sequence must be followed in order the create a CSR.

  • Create Key Attestation key --> This is inherently done, if working with TransactionSecurityBroker / Rest-API
  • Create Signing key
  • Generate CSR
  • Export Key Attestation
  • Verify Key Attestation
  • Submit CSR and Key Attestation File to the QTSP

1. Create a signing key​

Take care

IMPORTANT: A sample request to create a RSA-Key is shown here if you are generating keys for qualified Signature / Document signing / sealing) the following key flags are important and must be set: sign=true, extractable=false, sensitive=true)

POST: /v1/key, Create key request.

Replace <keyname> and password. The password is optional and can be deleted completely.

{
    "label": "<keyname>",
    "password": [ "R","E","P","L","A","C","E" ],
    "algorithm": "RSA",
    "keySize": 2048,
    "attributes": {
        "sign": true,
        "extractable": false,
        "modifiable": true,
        "destroyable": true,
        "sensitive": true,
        "decrypt": false,
        "unwrap": false
    }
}

2. Generate a CSR​

For CSR generation please follow the guide Create a CSR

3. Export Key Attestation​

POST: /v1/key/keyAttestation

Description: Generate key attestation files for a key

Replace <keyname> and password. The password is optional and can be deleted completely.

{
  "label": "<keyname>",
  "password": null
}

4. Verify Key Attestation (Optional)​

Tip

The the previosly downloaded attestation zip-file and the CSR are sent to the QTSP. Before issuance of the certificate the QTSP follows the validation steps indicated in the README_PrimusHSM_AuditAndAttestation_AN-E01.md contained in the zip-file. Note: Before sending the request to the QTSP we recommend that the certificate requester is performing the validation checks himself to assure the correctness.

4.1 Validation of the Key Attestation File and CSR by the QTSP​

The Qualified Trust Service Provider validates the CSR and the Key Attestation File by performing the following checks, prior issuing the certificate:

The Key Attestation File can be verified back to the Securosys Primus Root Certificate, which involves proofing the authenticity of:

the certificate chain, and the signature

The Key Attestation File belongs to the signing key from the CSR The signing key has the correct flags, e.g.: “extractable=false” and “never_extractable=true”

For highest assurance and to guarantee that all these checks can be conducted independently from any Securosys tools, we’ll use the OpenSSL software library to perform these verifications. Documentation of all OpenSSL command options can be found on the OpenSSL Documentation

4.2 Verify Authenticity of Key Attestation File​

Verify that the Key Attestation File is authentic and was generated by a Primus HSM with the following command. The option '-untrusted' is used to include the intermediate device certificate to construct a certificate chain from the subject certificate to the trust-anchor e.g., Primus-RootCertificate.crt. The Primus Root certificate can be downloaded under: PrimusHSM Root Certificate for Key-Attestation For productive Clusters download the hsm_rsa_root.crt file and place it alongside the Attestation files.

openssl verify -CAfile hsm_rsa_root.crt -untrusted PrimusHSM_Attestation.crt PrimusHSM_Attestation.crt
Example of positive response:
<SigningKeyAttestationFile>.crt: OK

Example of negative response:
<SigningKeyAttestationFile>.certificatechain: C = CH, ST = ZH, L =Zurich, O = Securosys, CN = SECUROSYS_ROOTKEY_DEV error 19 at 2 depth lookup:self signed certificate in certificate chain

By the response “OK” you know that the certificate chain was issued by Primus HSM.

4.3 Verify the Signature of the Key Attestation File​

Next you want to verify that the signature of the Key Attestation File is based on the key of the Key Attestation certificate in the certificate chain, which was verified to be issued by the Primus HSM before.

Now, verify the SHA256 signature using the public key from the attestation certificate chain from the message digest of the <KeyName>.

openssl dgst -verify PrimusHSM_Attestation_PublicKey.pem -sha256 -signature <KeyName>.sig <KeyName>.xml
Example of positive response:
Verified OK

Example of negative response:
Verified Failure
With the response “Verified OK”, there is evidence that the Key Attestation File, signature, and certificate chain belong together and are authentic.

4.4 Verify that the Key Attestation belongs to the CSR​

For the verification that the Key Attestation File and the CSR belong together, different intermediate steps must be performed. This allows further processing using the OpenSSL software library. First, extract the public key part of the certificate signing request file. The output file has the PEM format.

openssl req -in <KeyName>.csr -noout -pubkey -out SigningKeyCsrPubKey.pem

Second, convert this public key from PEM to DER format so it can be compared later.

openssl asn1parse -noout -in SigningKeyCsrPubKey.pem -out SigningKeyCsrPubKey.der

Then, extract the public key from the Key Attestation File.

grep public_key <KeyName>.xml | sed -e 's,[^>]*>,,' -e's,<.*,,' | base64 -d > SigningKeyAttestationFilePubKey.der

Now, compare the two public keys.

cmp SigningKeyCsrPubKey.der SigningKeyAttestationFilePubKey.der && echo Verified OK
Example of positive response:
Verified OK

Example of negative response:
Any other response

With the response “Verified OK” there is proof that the CSR and the Key Attestation File match with each other.

4.5 Verify Key Attributes​

After the authenticity of the Key Attestation File has been verified, it is time to verify if the signing key fulfills the requirements imposed by the regulation. The evidence that the signing key was generated on the HSM and was never exported is provided by the key flag “never_extractable=true”. This flag is set by the HSM automatically at key creation and indicates that the key was never outside of the HSM, and thus must have been generated inside the HSM. The flag “extractable=false” proves that this key can never be exported from the HSM. Open the key attestation File, e.g., <SigningKeyAttestationFile>.xml and verify both flags: • extractable: false • never_extractable: true

Any XML parser may help you in reading the attestation file.

5 Issuance of certificate by QTSP​

If all verification steps are positive, there is proof that the signing key, referred to in the certificate signing request file, is securely generated inside a Primus HSM and that it can never be exported from the HSM.

For further reading reference please consider reading: PrimusHSM_AuditAndAttestation_AN-E01.pdf (29.5.2023)

What's next?​