Attestation bundle format and construction

A key attestation bundle is a JSON object containing all the required data to verify that a key has been generated by an nShield HSM. It is the standard used by the Key Attestation Verifier and is encouraged for any other implementations for verifying nShield keys. All field names, data types and requirements are listed in the table below. For a worked example for retrieving the required fields using Python, nShield libraries and an HSM connection, see Bundle construction example.

All nShield data types (e.g. M_KeyData) are marshaled to byte strings. DDDS objects (e.g. warrants) are marshaled to byte strings. Byte strings are encoded with URL-safe base64 encoding, from RFC4648.

There are no ordering constraints on bundle representation.

Bundle fields

Field	Type	Encoding	Presence	Description
pubkeydata	M_KeyData	marshal+base64	Always	Public key material in nCore format (including any domain parameters)
kcmsg	M_ModCertMsg	marshal+base64	Always	The key generation certificate body (i.e. ModCertType_KeyGen)
kcsig	M_CipherText	marshal+base64	Always	The signature on the key generation certificate under KML
modstatemsg	M_ModCertMsg	marshal+base64	Always	A module state certificate (i.e. ModCertType_StateCert). See below for further requirements.
modstatesig	M_CipherText	marshal+base64	Always	The signature on the module state certificate under KLF2.
warrant	DDDS list	marshal+base64	Always	The DDDS encoding of the generating HSM’s KLF2 warrant.
root	string	none	Always	The name of the warranting root used in this certificate. This will always be KWARN-1 for nShield HSMs.
knsopub	M_KeyData	marshal+base64	Persistent keys	KNSO public key (needed to validate trump ops groups and actions)
hkre	M_KeyHashEx	marshal+base64	Recoverable keys	Hash of KRE (needed to validate recovery blobbing action)
hkra	M_KeyHashEx	marshal+base64	Recoverable keys	Hash of KRA (needed to reconstruct world binding certs)
hkfips	M_KeyHashEx	marshal+base64	Persistent keys in FIPS worlds	Hash of KFIPS (needed to reconstruct world binding certs)
hkmc	M_KeyHashEx	marshal+base64	Persistent keys	Hash of KMC (needed to reconstruct world binding certs)
hkm	M_KeyHashEx	marshal+base64	Persistent keys	Hash of KM (needed to validate module configuration)
CertKMaKMCbKNSO	M_CipherText	marshal+base64	Persistent keys in non-FIPS worlds	Signature on world binding cert
CertKMaKMCaKFIPSbKNSO	M_CipherText	marshal+base64	Persistent keys in FIPS worlds	Signature on world binding cert
CertKREaKRAbKNSO	M_CipherText	marshal+base64	Recoverable keys	Signature on world binding cert
ciphersuite	string	none	Persistent keys	Ciphersuite name for security world from the NFKM_CipherSuite enumeration (e.g. DLf3072s256mAEScSP800131Ar1)

Field

Type

Encoding

Presence

Description

pubkeydata

M_KeyData

marshal+base64

Always

Public key material in nCore format (including any domain parameters)

kcmsg

M_ModCertMsg

marshal+base64

Always

The key generation certificate body (i.e. ModCertType_KeyGen)

kcsig

M_CipherText

marshal+base64

Always

The signature on the key generation certificate under KML

modstatemsg

M_ModCertMsg

marshal+base64

Always

A module state certificate (i.e. ModCertType_StateCert). See below for further requirements.

modstatesig

M_CipherText

marshal+base64

Always

The signature on the module state certificate under KLF2.

warrant

DDDS list

marshal+base64

Always

The DDDS encoding of the generating HSM’s KLF2 warrant.

root

string

none

Always

The name of the warranting root used in this certificate. This will always be KWARN-1 for nShield HSMs.

knsopub

M_KeyData

marshal+base64

Persistent keys

KNSO public key (needed to validate trump ops groups and actions)

hkre

M_KeyHashEx

marshal+base64

Recoverable keys

Hash of KRE (needed to validate recovery blobbing action)

hkra

M_KeyHashEx

marshal+base64

Recoverable keys

Hash of KRA (needed to reconstruct world binding certs)

hkfips

M_KeyHashEx

marshal+base64

Persistent keys in FIPS worlds

Hash of KFIPS (needed to reconstruct world binding certs)

hkmc

M_KeyHashEx

marshal+base64

Persistent keys

Hash of KMC (needed to reconstruct world binding certs)

hkm

M_KeyHashEx

marshal+base64

Persistent keys

Hash of KM (needed to validate module configuration)

CertKMaKMCbKNSO

M_CipherText

marshal+base64

Persistent keys in non-FIPS worlds

Signature on world binding cert

CertKMaKMCaKFIPSbKNSO

M_CipherText

marshal+base64

Persistent keys in FIPS worlds

Signature on world binding cert

CertKREaKRAbKNSO

M_CipherText

marshal+base64

Recoverable keys

Signature on world binding cert

ciphersuite

string

none

Persistent keys

Ciphersuite name for security world from the NFKM_CipherSuite enumeration (e.g. DLf3072s256mAEScSP800131Ar1)

Persistent and recoverable keys

'Recoverable' has its normal nShield meaning:

The key’s ACL has MakeArchiveBlob action permitting blobbing under KRE (recovery key).
The key’s ACL has a 'trump ops' permission group, requiring KNSO (security officer’s key) authorization and permitting any action (generally including ExpandACL and/or ExportAsPlain).

'Persistent' has a special meaning here, not connected to the idea of cardsets being persistent. A persistent key has at least one blobbing action in its ACL, meaning it can be saved to some kind of storage and used long after generation. A non-persistent key has no blobbing actions. Note that recoverable keys are always persistent.