Warrant format

Overall format

A warrant is a marshalled DDDS list containing, in order:

  • A root key name which defines which key must be used to verify the first certificate

  • Zero or more Warrant Delegation Certificates

  • One of either a Smartcard Information Certificate or Module Information Certificate

The root key name is a DDDS symbol. Each individual certificate is a DDDS map.

Warrant certificates

All warrant certificates have the following structure.

{
  'Signature': ByteBlock(...),
  'Payload': ByteBlock(...)
}

The value of 'Signature' is a signature on the payload. The cryptographic key and mechanism used to verify this signature is not encoded in the certificate itself; it must be known out-of-band. For nShield warrants, only ECDSA signatures on NISTP521 are used, represented by the concatenation of the signature components in bigendian format, i.e. I2OSP(r, 66) || I2OSP(s, 66). I2OSP(n, l) refers to the representation of integer n as a big-endian l-length octet string.

The value of 'Payload' is itself a marshalled DDDS map. All nShield warrant certificates are identified by the presence of the 'WarrantCertificateType' member in the payload with the value of either 'Delegation', 'SmartcardInformation', 'ModuleInformation' or 'FieldUpgradeModuleInformation'. Note that any 'FieldUpgradeModuleInformation' certificates depend on signatures made using legacy DSA-1024 keys, limiting their security. The remaining certificate types are defined in further sections.

Warrant Delegation Certificates

A Warrant Delegation Certificate is a certificate whose payload is:

{
  'WarrantCertificateType': 'Delegation',
  'DelegateKey': <keydata>,
  'SigMech': <mech>
}

'DelegateKey' and 'SigMech' define the key and mechanism used for verification of the next certificate in the warrant.

For nShield warrants, only NISTP521 ECC public keys are used as the 'DelegateKey', which have the following format:

['ECDSA', 'Public', 'NISTP521', [ByteBlock(x), ByteBlock(y)]]

For nShield warrants, only ECDSA with SHA512 is used for the 'SigMech', which has the following format:

['ECDSA', ['EMSA1', 'SHA512']]

Smartcard Information Certificates

A Smartcard Information Certificate is a certificate whose payload is:

{
  'WarrantCertificateType': 'SmartcardInformation',
  'CardPub': <keydata>,
  'CardMech': <mech>,
  'SerialNumber': ByteBlock(...)
}

'CardPub' is the public half of a key held by the smartcard.

'SerialNumber' is the 9-byte serial number of the smartcard.

'CardMech' is the key agreement mechanism the card will use. As in the Warrant Delegation Certificates, the only mechanism used in nShield warrants is ECDSA with SHA512.

Module Information Certificates

A Module Information Certificate is a certificate whose payload is:

{
  'WarrantCertificateType': 'ModuleInformation',
  'KLF<KLF number>pub': <keydata>,
  'KLF<KLF number>mech': <mech>,
  'Approvals': [<approval>, ...],
  'ElectronicSerialNumber': "ABCD-ABCD-ABCD",
  'PhysicalSerialNumber': "01-234567"
}

'KLF<KLF number>pub' is the public half of the module’s long-term signing key. Existing warrant formats always use NISTP521 ECC public keys.

'KLF<KLF number>mech' is the signature mechanism to be used when verifying messages signed by a module’s KLF<KLF number>. Existing warrant formats always use ECDSA with SHA512.

'ElectronicSerialNumber' and 'PhysicalSerialNumber' are the electronic and physical serial numbers of the module to which the warrant refers.

'Approvals' is a possibly empty list of approvals which declare the security properties of the hardware platform associated with the given module.

<KLF number> can be either 2 or 3, for example:

{
  'WarrantCertificateType': 'ModuleInformation' ,
  'KLF2pub': <keydata>,
  'KLF2mech': <mech>,
  'Approvals': [<approval>, ...],
  'ElectronicSerialNumber': "ABCD-ABCD-ABCD",
  'PhysicalSerialNumber': "01-234567"
}

Hardware approvals

A single module approval is a DDDS list whose first item is a symbol defining the remaining items of the list. Only one symbol is defined so far: 'FIPS140'. Such an approval has the following form:

['FIPS140', int(version), int(level), '<kind>']

version indicates the version of the targetted FIPS140 standard.

level indicates the FIPS140 security level the hardware platform can achieve.

kind indicates the FIPS140 hardware profile which best describes the platform. For current hardware, this is either 'MultiChipEmbedded', or 'MultiChipStandalone'.

Therefore ['FIPS140' , int(2), int(3), 'MultiChipEmbedded'] declares that, at the time the warrant was created, the hardware was approved to FIPS140-2 level 3.

Other kinds of approval are to be defined.

Verifying a warrant

A real nShield HSM warrant might look like the DDDS-marshalled form of the following:

[
  'KWARN-1',                                                # root key name
  {'Signature': ByteBlock(...), 'Payload': ByteBlock(...)}, # warrant delegation certificate
  {'Signature': ByteBlock(...), 'Payload': ByteBlock(...)}  # module information certificate
]

Verifying any nShield warrant means working through the certificates in order. The first must be verified under the root key specified, the second is verified under the key from the payload of the first, and so on. After the last has been verified, the device public key and identity can be extracted from it, and the relationship between them can be trusted (to the extent that you trust the root key). The root key used for nShield module warrants is defined in nShield root key.