Core Concepts

Objects

The first concept that we will present is the Object. Any persistently stored and self-contained piece of information present in a YubiHSM 2 is an Object. This is intentionally a very generic and broad definition which can be easily rephrased as everything is an Object. Objects have associated properties that characterize them and give them different meanings. Regardless of the kind and the specific properties, any YubiHSM 2 device can store up to 256 Objects. Their combined size cannot exceed 126 KB.

Object Type

To identify what an Object can and cannot do, we define an attribute called Object Type, or simply Type. A Type is not enough to uniquely identify an Object, but it defines the set of operations that can be performed with or on it. The following types are defined:

Name	Value	yubihsm-shell name
Opaque	0x01	opaque
Authentication Key	0x02	authentication-key
Asymmetric Key	0x03	asymmetric-key
Wrap Key	0x04	wrap-key
HMAC Key	0x05	hmac-key
Template	0x06	template
OTP AEAD Key	0x07	otp-aead-key
Symmetric Key	0x08	symmetric-key
Public Wrap Key	0x09	public-wrap-key

Authentication Key

An Authentication Key is one of the most fundamental Objects there are. Authentication Keys can be used to establish a Session with a device. See Create and Authenticate a Session. An Authentication Key is basically two long-lived AES keys: an encryption key and a MAC key. When establishing a Session, the long-lived keys are used to generate three session keys:

• An encryption key used to encrypt the messages exchanged with the device
• A MAC key used to create an authentication tag for each message sent to the device
• A response MAC key used to create an authentication tag for each response message sent by the device

The session keys are temporary and are destroyed when the Session is no longer in use.

Asymmetric Key

An Asymmetric Key Object is what the YubiHSM 2 uses to represent an asymmetric key-pair where only the private key can be used to perform cryptographic operations.

HMAC Key

An HMAC Key is a secret key used when computing and verifying HMAC signatures.

Opaque

An Opaque Object is an unchecked kind of Object, normally used to store raw data in the device. No specific restrictions (besides size limitations) are imposed to this type of Object.

OTP AEAD Key

An OTP AEAD Key Object is a secret key used to decrypt Yubico OTP values for further verification by a validation process.

Symmetric Key

Available with firmware version 2.3.1 or later.

A Symmetric Key Object is a secret key used when encrypting and decrypting AES.

Object Types are encoded as an 8-bit value.

Template

A Template Object is a binary template used for example to validate SSH certificate requests.

Wrap Key

A Wrap Key Object is a secret key used to wrap and unwrap Objects during the export and import process.

Object Types are encoded as an 8-bit value.

Public Wrap Key

A Public Wrap Key Object is an RSA public key used to wrap Objects and (a)symmetric keys during the export process.

ALGORITHMS

Name	Value	yubihsm-shell name	EC Curve	Usage
RSA PKCS1 SHA1	1	rsa-pkcs1-sha1		RSA sign with PKCS1.5
RSA PKCS1 SHA256	2	rsa-pkcs1- sha256		RSA sign with PKCS1.5
RSA PKCS1 SHA384	3	rsa-pkcs1- sha384		RSA sign with PKCS1.5
RSA PKCS1 SHA512	4	rsa-pkcs1- sha512		RSA sign with PKCS1.5
RSA PSS SHA1	5	rsa-pss-sha1		RSA sign with PSS
RSA PSS SHA256	6	rsa-pss-sha256		RSA sign with PSS
RSA PSS SHA384	7	rsa-pss-sha384		RSA sign with PSS
RSA PSS SHA512	8	rsa-pss-sha512		RSA sign with PSS
RSA 2048	9	rsa2048		Generate RSA key
RSA 3072	10	rsa3072		Generate RSA key
RSA 4096	11	rsa4096		Generate RSA key
EC P256	12	ecp256	secp256r1	Generate EC key
EC P384	13	ecp384	secp384r1	Generate EC key
EC P521	14	ecp521	secp521r1	Generate EC key
EC K256	15	eck256	secp256k1	Generate EC key
EC BP256	16	ecbp256	brainpool256r1	Generate EC key
EC BP384	17	ecbp384	brainpool384r1	Generate EC key
EC BP512	18	ecbp512	brainpool512r1	Generate EC key
HMAC SHA1	19	hmac-sha1		Generate HMAC key
HMAC SHA256	20	hmac-sha256		Generate HMAC key
HMAC SHA384	21	hmac-sha384		Generate HMAC key
HMAC SHA512	22	hmac-sha512		Generate HMAC key
ECDSA SHA1	23	ecdsa-sha1		ECDSA sign
EC ECDH	24	ecdh
RSA OAEP SHA1	25	rsa-oaep-sha1		RSA decrypt with OAEP
RSA OAEP SHA256	26	rsa-oaep- sha256		RSA decrypt with OAEP
RSA OAEP SHA384	27	rsa-oaep- sha384		RSA decrypt with OAEP
RSA OAEP SHA512	28	rsa-oaep- sha512		RSA decrypt with OAEP
AES128 CCM WRAP	29	aes128-ccm- wrap		Generate Wrap key
Opaque Data	30	opaque-data		Store raw data as an opaque object
Opaque X509 Certificate	31	opaque-x509- certificate		Store X509Certificate as an opaque object
MGF1 SHA1	32	mgf1-sha1		RSA sign with PSS and RSA decrypt with OAEP
MGF1 SHA256	33	mgf1-sha256		RSA sign with PSS and RSA decrypt with OAEP
MGF1 SHA384	34	mgf1-sha384		RSA sign with PSS and RSA decrypt with OAEP
MGF1 SHA512	35	mgf1-sha512		RSA sign with PSS and RSA decrypt with OAEP
SSH Template	36	template-ssh		Store an SSH template (a binary object used to restrict how and when an SSH CA private key should be used)
Yubico OTP AES128	37	aes128-yubico -otp		Generate OTP AEAD key
Yubico AES Authentication	38	aes128-yubico- authentication		Store authentication key
Yubico OTP AES192	39	aes192-yubico -otp		Generate OTP AEAD key
Yubico OTP AES256	40	aes256-yubico -otp		Generate OTP AEAD key
AES192 CCM WRAP	41	aes192-ccm- wrap		Generate and store wrap key
AES256 CCM WRAP	42	aes256-ccm- wrap		Generate and store wrap key
ECDSA SHA256	43	ecdsa-sha256		ECDSA sign
ECDSA SHA384	44	ecdsa-sha384		ECDSA sign
ECDSA SHA512	45	ecdsa-sha512		ECDSA sign
ED25519	46	ed25519		Generate ED key
EC P224	47	ecp224	secp224r1	Generate EC key
AES KWP	55	aes-kwp		Internal use only

Attestation

Asymmetric keys in the YubiHSM can be attested by another Asymmetric key. The attestation process creates a new x509 certificate for the attested key.

The device comes pre-loaded with an attestation key and certificate referenced by ID 0. It is possible to use your own key and certificate for attestation, these then must have the same ID and the key has to have the sign-attestation-certificate Capability set.

Details

• Serial is a random 16 byte integer
• Issuer is the subject of the attesting certificate
• Dates is copied from the attesting certificate
• Subject is the string YubiHSM Attestation id 0x with the attested ID appended
• If the attesting key is RSA the signature is SHA256-PKCS#1v1.5
• If the attesting key is EC the signature is ECDSA-SHA256

Certificate Extensions

Some certificate extensions are added in the generated certificate and/or the pre-loaded certificate:

OID	Description	Data Type	Generated/Pre-loaded
1.3.6.1.4.1.41482.4.1	Firmware version	Octet String	Both
1.3.6.1.4.1.41482.4.2	Serial number	Integer	Both
1.3.6.1.4.1.41482.4.3	Origin	Bit String	Generated
1.3.6.1.4.1.41482.4.4	Domain	Bit String	Generated
1.3.6.1.4.1.41482.4.5	Capability	Bit String	Generated
1.3.6.1.4.1.41482.4.6	Object ID	Integer	Generated
1.3.6.1.4.1.41482.4.9	Label	Utf8String	Generated
1.3.6.1.4.1.41482.4.10	FIPS	Integer	Pre-loaded
1.3.6.1.4.1.41482.4.12	FIPS	Boolean	Generated

Pre-Loaded Certificates

The pre-loaded certificate can be fetched as an opaque object with ID 0. This will in turn be signed by an intermediate CA which is signed by a Yubico root CA.

Intermediates:

E45DA5F361B091B30D8F2C6FA040DB6FEF57918E.pem

Capability

A Capability is an attribute that can be given to an Objects allowing specific operations to be performed on or with it. Commands like digital signature generation and data decryption require (and check) for a predetermined set of Capabilities to be present on an Object. Further below is the list of existing Capabilities.

It is important to know that there are no restrictions on which Capabilities can be set on an Object. Specifically, this means that it is possible to assign meaningless Capabilities to Objects that will never be able to use them, for example it is possible to have an Asymmetric Object with the Capability verify-hmac. Such a Capability only makes sense for HMAC Key objects, but the device allows defining a superset. Lack of Capabilities required for a specific operation causes a command requiring that Capability to fail.

Delegated Capabilities

Every Object stored on the device has an associated set of Capabilities. There is a second set of so-called Delegated Capabilities that only Authentication Keys and Wrap Keys have. This is used to capture the indirection that Authentication Keys and Wrap Keys can be used as a means of storing more Objects on a device. In both cases Delegated Capabilities are used as a filter.

For Authentication Keys, Delegated Capabilities define the set of Capabilities that can be set or “bestowed” onto an Object created by the Authentication Key. Any operation attempting to create Objects with a Capability outside of this set fails.

For Wrap Keys, Delegated Capabilities define the set of Capabilities that an Object can have when imported or exported using the Wrap Key. A larger set of Capabilities causes the import operation to fail.

Protocol Details

A Set of Capabilities is an 8-byte value. Each Capability is identified by a specific bit, as shown in the Hex Mask column below.

Name	Hex Mask	Applicable Objects	Description
—————————Asymmetric Keys——————————–
delete-asymmetric -key	0x0000020000000000	authentication -key	Delete Asymmetric Key Objects
generate-asymmetric -key	0x0000000000000010	authentication -key	Generate Asymmetric Key Objects
put-asymmetric-key	0x0000000000000008	authentication -key	Write Asymmetric Key Objects
—————————Authentication Keys—————————-
delete-authen- tication-key	0x0000010000000000	authentication -key	Delete Authentication Key Objects
put-authentication -key	0x0000000000000004	authentication -key	Write Authentication Key Objects
change- authentication-key	0x0000400000000000	authentication -key	Replace Authentication Key Objects
——————————–Certificate——————————-
sign-attestation- certificate	0x0000000400000000	authentication -key, asymmetric-key	Attest properties of Asymmetric Key Objects
sign-ssh-certificate	0x0000000002000000	authentication -key, asymmetric-key	Sign SSH certificates
———————————–Data———————————–
decrypt-cbc	0x0010000000000000	authentication -key, symmetric-key	Decrypt data using AES CBC mode. Available with firmware version 2.3.1 or later.
decrypt-ecb	0x0004000000000000	authentication -key, symmetric-key	Decrypt data using AES ECB mode. Available with firmware version 2.3.1 or later.
decrypt-oaep	0x0000000000000400	authentication -key, asymmetric-key	Decrypt data using RSA-OAEP
decrypt-pkcs	0x0000000000000200	authentication -key, asymmetric-key	Decrypt data using RSA-PKCS1v1.5
encrypt-cbc	0x0020000000000000	authentication -key, symmetric-key	Encrypt data using AES CBC mode. Available with firmware version 2.3.1 or later.
encrypt-ecb	0x0008000000000000	authentication -key, symmetric-key	Encrypt data using AES ECB mode. Available with firmware version 2.3.1 or later.
———————————–ECDH———————————–
derive-ecdh	0x0000000000000800	authentication -key, asymmetric-key	Perform ECDH
———————————–Global———————————
get-option	0x0000000000040000	authentication -key	Read device- global options
set-option	0x0000000000020000	authentication -key	Write device- global options
———————————–HMAC———————————–
delete-hmac-key	0x0000080000000000	authentication -key	Delete HMAC Key Objects
generate-hmac-key	0x0000000000200000	authentication -key	Generate HMAC Key Objects
put-mac-key	0x0000000000100000	authentication -key	Write HMAC Key Objects
sign-hmac	0x0000000000400000	authentication -key, hmac-key	Compute HMAC of data
verify-hmac	0x0000000000800000	authentication -key, hmac-key	Verify HMAC of data
—————————————Log——————————–
get-log-entries	0x0000000001000000	authentication -key	Read the Log Store
———————————–Opaque———————————
delete-opaque	0x0000008000000000	authentication -key	Delete Opaque Objects
get-opaque	0x0000000000000001	authentication -key	Read Opaque Objects
put-opaque	0x0000000000000002	authentication -key	Write Opaque Objects
———————————–OTP————————————
create-otp-aead	0x0000000040000000	authentication -key, otp-aead-key	Create OTP AEAD
decrypt-otp	0x0000000020000000	authentication -key, otp-aead-key	Decrypt OTP
delete-otp-aead-key	0x0000200000000000	authentication -key	Delete OTP AEAD Key Objects
generate-otp-aead -key	0x0000001000000000	authentication -key	Generate OTP AEAD Key Objects
put-otp-aead-key	0x0000000800000000	authentication -key	Write OTP AEAD Key Objects
randomize-otp-aead	0x0000000080000000	authentication -key, otp-aead-key	Create OTP AEAD from random data
rewrap-from-otp- aead-key	0x0000000100000000	authentication -key, otp-aead-key	Rewrap AEADs from one OTP AEAD Key Object to another
rewrap-to-otp- aead-key	0x0000000200000000	authentication -key, otp-aead-key	Rewrap AEADs to one OTP AEAD Key Object from another
———————————–Random———————————
get-pseudo-random	0x0000000000080000	authentication -key	Extract random bytes
————————————–Reset——————————-
reset-device	0x0000000010000000	authentication -key	Perform a factory reset on the device
———————————–Signatures—————————–
sign-ecdsa	0x0000000000000080	authentication -key, asymmetric-key	Compute digital signatures using ECDSA
sign-eddsa	0x0000000000000100	authentication -key, asymmetric-key	Compute digital signatures using EDDSA
sign-pkcs	0x0000000000000020	authentication -key, asymmetric-key	Compute signatures using RSA- PKCS1v1.5
sign-pss	0x0000000000000040	authentication -key, asymmetric-key	Compute digital signatures using using RSA-PSS
———————————–Template——————————-
delete-template	0x0000100000000000	authentication -key	Delete Template Objects
get-template	0x0000000004000000	authentication -key	Read Template Objects
put-template	0x0000000008000000	authentication -key	Write Template Objects
———————————–Wrap ———————————-
delete-wrap-key	0x0000040000000000	authentication -key	Delete Wrap Key Objects
export-wrapped	0x0000000000001000	authentication -key, wrap-key	Export other Objects under wrap
exportable-under -wrap	0x0000000000010000	all	Mark an Object as exportable under wrap
generate-wrap-key	0x0000000000008000	authentication -key	Generate Wrap Key Objects
import-wrapped	0x0000000000002000	authentication -key, wrap-key	Import wrapped Objects
put-wrap-key	0x0000000000004000	authentication -key	Write Wrap Key Objects
unwrap-data	0x0000004000000000	authentication -key, wrap-key	Unwrap user- provided data
wrap-data	0x0000002000000000	authentication -key, wrap-key	Wrap user- provided data
—————————–Public Key Wrap —————————–
put-public-wrap -key	0x0040000000000000	authentication -key, wrap-key	Write RSA Public Wrap Key
delete-public-wrap -key	0x0080000000000000	authentication -key, wrap-key	Delete RSA Public Wrap Key
——————————Symmetric Keys —————————–
generate-symmetric -key	0x0001000000000000	authentication -key	Generate AES key. Available with firmware version 2.3.1 or later.
put-symmetric-key	0x0000800000000000	authentication -key	Import AES key. Available with firmware version 2.3.1 or later.
delete-symmetric-key	0x0002000000000000	authentication -key	Delete AES key. Available with firmware version 2.3.1 or later.

Domain

A Domain is a logical partition that can be conceptually mapped to a container. In a YubiHSM 2 there are 16 independent Domains; an Object can belong to one or more Domains.

Note

Authentication Keys are Objects and thus can belong to multiple Domains.

Domains serve as a means to secure Objects so that they cannot be addressed by independent applications running on the same device. This is achieved by specifying the Object’s Domain. Only users or applications that belong to the same Domain as an Object can access it or use it.

The details involved in accessing an Object are explained in the Effective Capabilities (Tying It All Together) page.

Protocol Details

Domains are encoded as 16-bit values, where each Domain is represented by a bit

Domain Number	Hex Mask
1	0x0001
2	0x0002
3	0x0004
4	0x0008
5	0x0010
6	0x0020
7	0x0040
8	0x0080
9	0x0100
10	0x0200
11	0x0400
12	0x0800
13	0x1000
14	0x2000
15	0x4000
16	0x8000

Effective Capabilities (Tying It All Together)

This document describes how Object-related concepts interact with each another.

Let us assume that we are establishing a Session with Authentication Key 0xabcd so that the Session can use the Asymmetric Key 0x1234 to sign some data. We are assuming that Asymmetric Key 0x1234 is an RSA 2048-bit key and that we would like to generate a signature using RSASSA-PSS.

Create and Authenticate a Session

Creating and authenticating a Session requires knowledge of what the long-lived keys are (or what the associated derivation password is).

When a valid Session is established, certain properties of the Authentication Key used to create the Session are inherited by the Session itself. These are:

• The Domain(s) to which the Authentication Key belongs (for more information, see Domain),
• The Capabilities of the Authentication Key (see Capability) and
• The Delegated Capabilities (see Capability) associated with Authentication Key 0xabcd .

The Session’s inherited properties serve to ensure that the only Objects stored in the HSM 2 that we can see and access are those that belong to the same Domain(s) as Authentication Key 0xabcd.

Generate a Signature

The required capability must be set on both the Authentication Key used to establish the Session (Authentication Key 0xabcd) and the target Object used to perform the operation (Asymmetric Key 0x1234).

Assuming that Asymmetric Key 0x1234 is in one such Domain, we can now continue and ask the HSM 2 to generate a signature. To do so we will send the Sign Data command over the Session. It will not execute successfully unless the arguments of the command are valid, i.e., no malformed data can be sent to the device or an error will occur.

Both Authentication Key 0xabcd and Asymmetric Key 0x1234 must have the Capability sign-pss set.

Effective Capabilities and Role Definition

The overlap between

• The Capabilities of the Authentication Key used to establish the Session and
• The Capabilities of the target Object involved in the operation

defines the Effective Capabilities. An operation on a given target Object over a given Session can succeed only if the Capabilities required by the operation are included in the Effective Capabilities.

The interaction between Domains and Effective Capabilities enables flexible setup and role definition. For example,

• It is possible to assign a set of Capabilities to an Object, and then distribute those Capabilities across different Authentication Keys so that each key is enabled to perform only a single operation on the target Object, and no key performs the same operation as any other key.
• Similarly, it is possible to disable specified operations by not assigning the requisite Capabilities to an Authentication Key. For example, an “Administrator” Authentication Key could be enabled only to create keys while a “User” Authentication Key could be enabled only to use those same keys.

Workflow

1. Determine which Objects will have operations performed on them

2. Determine which Authentication Keys you will use

3. Determine which operations will be performed

4. Use a spreadsheet (if necessary) to map out the interaction between the first three items

5. With the aid of the spreadsheet, create domains to enable the interaction.

   Note

   Authentication Keys are Objects and thus can belong to multiple Domains.

6. You could construct your domains:

   • per operation - put an Object and an Authentication Key into each domain, or
   • per Object - put the Authentication Key(s) for all the operations to be performed on each Object into a single domain
   • per Authentication Key - put the requisite Object(s) into each Domain.

   For example, if you wanted Jan to do the signing and Ola to do the importing, you could adopt any of the above options, but the Effective Capabilities enable you to assign far more complex webs of responsibilities.

7. Use the spreadsheet to set the Capabilities and Delegated Capabilities appropriately, “appropriateness” being determined by the Objects and operations to be performed on them.

Errors

Below are error codes returned by a YubiHSM device.

Name	Value	Description
OK	0x00	Success
INVALID COMMAND	0x01	Unknown command
INVALID DATA	0x02	Malformed data for the command
INVALID SESSION	0x03	The session has expired or does not exist
AUTHENTICATION FAILED	0x04	Wrong Authentication Key
SESSIONS FULL	0x05	No more available sessions
SESSION FAILED	0x06	Session setup failed
STORAGE FAILED	0x07	Storage full
WRONG LENGTH	0x08	Wrong data length for the command
INSUFFICIENT PERMISSIONS	0x09	Insufficient permissions for the command
LOG FULL	0x0a	The log is full and force audit is enabled
OBJECT NOT FOUND	0x0b	No object found matching given ID and Type
INVALID ID	0x0c	Invalid ID
SSH CA CONSTRAINT VIOLATION	0x0e	Constraints in SSH Template not met
INVALID OTP	0x0f	OTP decryption failed
DEMO MODE	0x10	Demo device must be power-cycled
OBJECT EXISTS	0x11	Unable to overwrite object

FIPS

Note

This section applies to YubiHSM 2 FIPS devices only.

The YubiHSM 2 is available in a FIPS-capable version called YubiHSM 2 FIPS.

The YubiHSM 2 FIPS is certified at FIPS 140-2 Level 3, which means it can be used in solutions that are meant to comply with FIPS 140-2 requirements.

The YubiHSM 2 FIPS can be configured in an approved mode and a non-approved mode of operation. In the approved mode, only FIPS-approved algorithms are supported. In the non-approved mode, additional non-approved algorithms such as rsa-pkcs1-sha1 are supported.

FIPS-approved mode can be configured only after a device reset by enabling the fips-mode option and immediately changing the default Authentication key.

For instructions on configuring the YubiHSM 2 FIPS in FIPS-approved mode, see FIPS Mode Support Guide.

A key attestation generated on a YubiHSM 2 FIPS device will have an X.509 extension present with OID 1.3.6.1.4.1.41482.4.12. If the key attestation was generated in FIPS-approved mode, this extension will have the BOOLEAN value TRUE. Otherwise, it will have the BOOLEAN value FALSE.

The pre-loaded certificate of a YubiHSM 2 FIPS device will have an X.509 extension present with OID 1.3.6.1.4.1.41482.4.10. This extension will have an INTEGER value encoding its FIPS certificate. Currently, the value 6 refers to the YubiHSM 2 FIPS certificate for firmware version 2.2.

Label

A Label is a sequence of bytes that can be used to add a mnemonic reference to Objects.

Protocol Details

Labels are 40 bytes long. As far as the YubiHSM is concerned, the label is only a string of raw bytes and is not restricted to printable characters or valid UTF-8 glyphs.

Logs

A YubiHSM 2 device maintains a list of recently executed commands in a portion of non-volatile memory known as the Log Store. This allows logging commands across different power cycles. Specific commands are used to extract logs from the device. Since the Log Store uses non-volatile memory, it can only store up to 62 different entries. When the Log Store is full, it is used as a circular buffer, meaning that the least recently used entry is overwritten.

It is possible to set the device in Force Audit mode. When this is done entries from the Log Store must be retrieved or commands that cannot be logged will fail. Together with individual commands, power-on and reboot events are also logged.

The establishment of a session is logged like any other operation; however those commands are always allowed, independent of the current status of the Log Store. This is so that it is always possible to retrieve logs and free up the Log Store, even when the device is in Force Audit mode and the Log Store is full. However, the number of unlogged authentication and power-up events is stored in a counter that is retrieved as part of the log retrieval.

Entries in the Log Store are organized to form a chain of hashes. This enables auditors to verify that a given set of entries has not been tampered with after extraction, and that all entries are present. More details on the format of log entries can be found in the protocol description document for GET LOG ENTRIES Command.

Object ID

The ID property is used to identify an Object of a given Type. This means that to uniquely identify an Object stored on a YubiHSM 2, the couple (Type, ID) is required. There can be more than one Object with a given ID and more than one Object with a given Type, but only one Object with a specific ID and Type. This is so that logical connections between Objects can be established by giving a set of connected Objects of different Types the same ID.

An Object ID can have values in the range [0-65535] or [0x0000-0xffff] in hexadecimal. Note that this range is larger than the maximum number of Objects that can be stored in the device (256). Regardless of the type, ID 0x0000 and 0xffff are reserved for internal Objects.

Protocol Details

Object IDs are encoded as 16-bit values.

Options

Options are device-global settings. The following Options are defined:

Option Name	Hex Value
force-audit	0x01
command-audit	0x03

The data payload is Option-specific.

Force Audit

This Option is used to enable Force Audit mode which prevents the device from performing additional operations when the Logs is full.

The Option accepts three different values:

• 0x00: Option disabled
• 0x01: Option enabled
• 0x02: Option permanently enabled (only possible to turn off through factory reset)

Command Audit

This Option is used to enable or disable logging of specific commands. Logging commands impacts performance. By default logging is enabled for all operations.

The Option accepts three different values:

• 0x00: Option disabled
• 0x01: Option enabled
• 0x02: Option permanently enabled (only possible to turn off through factory reset)

Multiple commands can be specified at once with the syntax C1 V1, C2 V2, ..., Cn Vn where Ci is the Command Code and Vi is the Option Value. An example of this syntax can be found at the SET OPTION Command description.

Origin

The Origin is a one-byte value that is part of the metadata associated with an asymmetric key object. The origin indicates whether the asymmetric key was generated on a YubiHSM 2 device or generated externally and subsequently imported. If a key was imported, the origin also indicates whether the key was imported in plaintext or using a wrap key.

Origins are also used when generating a key attestation. The attestation certificate will contain the key’s origin as an X.509 extension. See Attestation.

Protocol Details

Origins are encoded as 8-bit values, where each defined origin is represented by a bit according to the following table:

Name	Hex Mask
generated	0x0001
imported	0x0002
imported_wrapped	0x0010

Note that not all combinations of these bits are valid. In practice, only the combinations 0x0001, 0x0002, and 0x0011, 0x0012 can occur.

Sequence

The Sequence is a one-byte value that is part of the metadata associated with an Object. The Sequence describes how many times an Object with a given ID and Type has been written. This is mostly useful for caching to determine if new data needs to be fetched from the device.

Protocol Details

Sequence is 8 bits long and will wrap.

Session

A Session is not a property of a specific Object, but rather it is used to describe a logical connection between an application and a device. Sessions are end-to-end encrypted and authenticated using Session Keys. These keys are derived from long-lived, pre-shared Authentication Key Objects as part of the sessions authentication process. The Session creation and authentication protocol is based on Global Platform SCP03.

On a single YubiHSM 2 it is possible to establish up to 16 independent and concurrent Sessions. Note that while multiple concurrent Sessions can be active at a given time, the device still serves as a rendezvous point. This means that time-consuming operations such as generating a long RSA key will block commands in other Sessions. Sessions are addressed with a number in the range [0-15].

Sessions have an expiration period of 30 seconds of inactivity in order to prevent resource starvation. After 30 seconds, the device will consider a Session inactive and will move it to the pool of re-usable Sessions. Whenever a command is executed on a given Session, the inactivity timer is reset, meaning that if a Session is being constantly used, it will not expire.

Some of the operations that can be performed on a YubiHSM 2 do not require a Session. The implication is that the command and its response will travel unencrypted to and from the device. These commands are only generic status commands, making Sessions required for any meaningful operation.

The long-lived keys required to derive Sessions can be explicitly used in the relevant commands. However, there are built-in functionalities to derive those keys from a password using 10,000 iterations of PBKDF2 with the salt Yubico, making the process more human-friendly. Every new or factory-reset YubiHSM 2 has a default Authentication Key with ID 1 and all Capabilities and all Domains set. This is equivalent to a superuser or an administrator. The long-lived keys for this Object are derived using the process previously described with the password password.

Warning

It is crucial to delete this well-known Authentication Key before deployment.