Core Concepts
The concepts presented here are required knowledge to be successful with operating the HSM.
Session
All communication with a YubiHSM 2 device occurs within the context of a Session. A Session is established by authenticating with an Authentication Key Object stored on the device.
There can be up to 16 concurrent Sessions established with a YubiHSM 2 device. Each Session has its own set of temporary session keys used to encrypt and authenticate the messages exchanged with the device.
Session Protocol Details
Sessions are encoded as 8-bit values.
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 Object | 0x01 | opaque |
| Authentication Key Object | 0x02 | authentication-key |
| Asymmetric Key Object | 0x03 | asymmetric-key |
| Wrap Key Object | 0x04 | wrap-key |
| HMAC Key Object | 0x05 | hmac-key |
| Template Object | 0x06 | template |
| OTP AEAD Key Object | 0x07 | otp-aead-key |
| Symmetric Key Object | 0x08 | symmetric-key |
| Public Wrap Key Object | 0x09 | public-wrap-key |
Authentication Key Object
An Authentication Key is one of the most fundamental Objects there are. Authentication Keys are used to establish an encrypted Session with the device. See CREATE SESSION Command. 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 Object
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 Object
An HMAC Key is a secret key used when computing and verifying HMAC signatures.
Opaque Object
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 Object
An OTP AEAD Key Object is a secret key used to decrypt Yubico OTP values for further verification by a validation process.
Public Wrap Key Object
A Public Wrap Key Object is an RSA public key used to wrap Objects and (a)symmetric keys during the export process.
Symmetric Key Object
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 Object
A Template Object is a binary template used for example to validate SSH certificate requests.
Wrap Key Object
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.
Capabilities
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.
Capability 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.
|
Domains
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 Access Control and Role Definition page.
Domain 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 |
Label
A Label is a sequence of bytes that can be used to add a mnemonic reference to Objects.
Label 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.
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.
Object ID Protocol Details
Object IDs are encoded as 16-bit values.
Algorithms
Following table describes algorithm names to be used with YubiHSM Shell for the algorithms supported by YubiHSM 2. The table includes the externally common name, YubiHSM shell name, and common usage.
| Name | yubihsm-shell name | EC Curve | Value | Usage |
|---|---|---|---|---|
| AES 128 | aes128 | |||
| AES 192 | aes192 | |||
| AES 256 | aes256 | |||
| AES CBC | aes-cbc | |||
| AES ECB | aes-ecb | |||
| AES128 CCM WRAP | aes128-ccm-wrap | 29 | Generate Wrap key | |
| AES192 CCM WRAP | aes192-ccm-wrap | 41 | Generate and
store wrap key
|
|
| AES256 CCM WRAP | aes256-ccm-wrap | 43 | Generate and
store wrap key
|
|
| AES KWP | aes-kwp | 55 | Internal use only | |
| EC BP256 | ecbp256 | brainpool256r1 | 15 | Generate EC key |
| EC BP384 | ecbp384 | brainpool384r1 | 16 | Generate EC key |
| EC BP512 | ecbp512 | brainpool512r1 | 17 | Generate EC key |
| EC ECDH | ecdh | 24 | ||
| EC K256 | eck256 | secp256k1 | 15 | Generate EC key |
| EC P224 | ecp224 | secp224r1 | 12 | Generate EC key |
| EC P256 | ecp256 | secp256r1 | 13 | Generate EC key |
| EC P384 | ecp384 | secp384r1 | 14 | Generate EC key |
| EC P521 | ecp521 | secp521r1 | 47 | Generate EC key |
| ECDSA SHA1 | ecdsa-sha1 | 23 | ECDSA sign | |
| ECDSA SHA256 | ecdsa-sha256 | 43 | ECDSA sign | |
| ECDSA SHA384 | ecdsa-sha384 | 44 | ECDSA sign | |
| ECDSA SHA512 | ecdsa-sha512 | 45 | ECDSA sign | |
| ED25519 | ed25519 | 46 | Generate ED key | |
| HMAC SHA1 | hmac-sha1 | 19 | Generate HMAC key | |
| HMAC SHA256 | hmac-sha256 | 20 | Generate HMAC key | |
| HMAC SHA384 | hmac-sha384 | 21 | Generate HMAC key | |
| HMAC SHA512 | hmac-sha512 | 22 | Generate HMAC key | |
| MGF1 SHA1 | mgf1-sha1 | 32 | RSA sign with
PSS and RSA
decrypt with OAEP
|
|
| MGF1 SHA256 | mgf1-sha256 | 33 | RSA sign with
PSS and RSA
decrypt with OAEP
|
|
| MGF1 SHA384 | mgf1-sha384 | 34 | RSA sign with
PSS and RSA
decrypt with OAEP
|
|
| MGF1 SHA512 | mgf1-sha512 | 35 | RSA sign with
PSS and RSA
decrypt with OAEP
|
|
| Opaque Data | opaque-data | 30 | Store raw data
as an opaque
object
|
|
| Opaque X509 Certificate | opaque-x509-certificate | 31 | Store
X509Certificate
as an opaque
object
|
|
| RSA 2048 | rsa2048 | 9 | Generate RSA key | |
| RSA 3072 | rsa3072 | 10 | Generate RSA key | |
| RSA 4096 | rsa4096 | 11 | Generate RSA key | |
| RSA OAEP SHA1 | rsa-oaep-sha1 | 25 | RSA decrypt with
OAEP
|
|
| RSA OAEP SHA256 | rsa-oaep-sha256 | 26 | RSA decrypt with
OAEP
|
|
| RSA OAEP SHA384 | rsa-oaep-sha384 | 27 | RSA decrypt with
OAEP
|
|
| RSA OAEP SHA512 | rsa-oaep-sha512 | 28 | RSA decrypt with
OAEP
|
|
| RSA PKCS1 SHA1 | rsa-pkcs1-sha1 | 1 | RSA sign with
PKCS1.5
|
|
| RSA PKCS1 SHA256 | rsa-pkcs1-sha256 | 2 | RSA sign with
PKCS1.5
|
|
| RSA PKCS1 SHA384 | rsa-pkcs1-sha384 | 3 | RSA sign with
PKCS1.5
|
|
| RSA PKCS1 SHA512 | rsa-pkcs1-sha512 | 4 | RSA sign with
PKCS1.5
|
|
| RSA PSS SHA1 | rsa-pss-sha1 | 5 | RSA sign with PSS | |
| RSA PSS SHA256 | rsa-pss-sha256 | 6 | RSA sign with PSS | |
| RSA PSS SHA384 | rsa-pss-sha384 | 7 | RSA sign with PSS | |
| RSA PSS SHA512 | rsa-pss-sha512 | 8 | RSA sign with PSS | |
| SSH Template | template-ssh | 36 | Store an SSH
template (a
binary object
used to restrict
how and when an
SSH CA private
key should be
used)
|
|
| Yubico AES Authentication | aes128-yubico-authentication | 38 | Store
authentication
key
|
|
Yubico Asymmetric
Authentication
|
ecp256-yubico-authentication | |||
| Yubico OTP AES128 | aes128-yubico-otp | 37 | Generate OTP AEAD
key
|
|
| Yubico OTP AES192 | aes192-yubico-otp | 39 | Generate OTP AEAD
key
|
|
| Yubico OTP AES256 | aes256-yubico-otp | 40 | Generate OTP AEAD
key
|
Algorithm Protocol Details
Algorithms are encoded as 8-bit values.
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.
Origin 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.
Sequence Protocol Details
Sequence is 8 bits long and will wrap.
Options
Options are device-global settings. The following Options are defined:
| Option Name | Hex Value | Notes |
|---|---|---|
| force-audit | 0x01 | |
| command-audit | 0x03 | |
| algorithm-toggle | 0x04 | Only available with firmware version 2.2 and higher |
| fips-mode | 0x05 | Only available on FIPS certified YubiHSM 2 devices |
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 Log Store 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 Set Command Audit Option.
Algorithm Toggle
This Option is used to enable and disable algorithms. On non-FIPS YubiHSMs, all algorithms are enabled by default but can be disabled individually by setting the algorithm-toggle option.
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 algorithms can be specified at once with the syntax C1 V1, C2 V2, ..., Cn Vn where Ci is the Algorithm
Value and Vi is the Option Value. An example of this syntax can be found at Set Algorithm Toggle Option.
FIPS Mode
This Option is used to turn FIPS mode On or Off. Enabling and disabling FIPS mode can only be done on an empty YubiHSM 2, for example, after a factory reset.
The Option accepts two different values:
- 0x00: Option disabled
- 0x01: Option enabled
An example of how to turn FIPS mode ON and OFF can be found at Set FIPS Mode.
Attestation
Asymmetric keys generated 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 Object ID 0. It is possible to use another asymmetric key and certificate for attestation, these then must have the same Object 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 0xwith 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 | Domains | Bit String | Generated |
| 1.3.6.1.4.1.41482.4.5 | Capabilities | 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 certified | Integer | Pre-loaded |
| 1.3.6.1.4.1.41482.4.12 | FIPS certified | 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
Log Store
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.
Error Codes
Below are error codes returned by a YubiHSM device.
| Value | Name | Description |
|---|---|---|
| 0x00 | OK | Success |
| 0x01 | INVALID COMMAND | Unknown command |
| 0x02 | INVALID DATA | Malformed data for the command |
| 0x03 | INVALID SESSION | The session has expired or does not exist |
| 0x04 | AUTHENTICATION FAILED | Wrong Authentication Key |
| 0x05 | SESSIONS FULL | No more available sessions |
| 0x06 | SESSION FAILED | Session setup failed |
| 0x07 | STORAGE FAILED | Storage full |
| 0x08 | WRONG LENGTH | Wrong data length for the command |
| 0x09 | INSUFFICIENT PERMISSIONS | Insufficient permissions for the command |
| 0x10 | DEMO MODE | Demo device must be power-cycled |
| 0x11 | OBJECT EXISTS | Unable to overwrite object |
| 0x0a | LOG FULL | The log is full and force audit is enabled |
| 0x0b | OBJECT NOT FOUND | No object found matching given ID and Type |
| 0x0c | INVALID ID | Invalid ID |
| 0x0e | SSH CA CONSTRAINT
VIOLATION
|
Constraints in SSH Template not met |
| 0x0f | INVALID OTP | OTP decryption failed |
Access Control and Role Definition
Almost every operation performed by the YubiHSM 2 is performed within a session authenticated using an Authentication Key Object.
The domains of the Authentication Key used to establish an authenticated session determine which objects can be accessed, while the Capabilities and the Delegated Capabilities of that Authentication Key determine which operations can be performed during the session.
The Session’s inherited properties based on the Authentication Key properties serve to ensure that the only Objects stored on the YubiHSM 2 that are accessible within a session are those that belong to the same Domain(s) as the Authentication Key and the only operations that can be performed are those that the Authentication Key is allowed to perform.
The Effective Capabilities are defined by 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
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.
Access Setup Workflow
Determine which Objects will have operations performed on them
Determine which Authentication Keys you will use
Determine which operations will be performed
Use a spreadsheet (if necessary) to map out the interaction between the first three items
With the aid of the spreadsheet, create domains to enable the interaction.
Note
Authentication Keys are Objects and thus can belong to multiple Domains.
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.
Use the spreadsheet to set the Capabilities and Delegated Capabilities appropriately, “appropriateness” being determined by the Objects and operations to be performed on them.
Access Control Components
Domains
To perform a specific operation inside the YubiHSM2, both the Authentication Key used to authenticate the session and the operational key must exist in at least one common domain.
Example:
Assume the following keys exist in the YubiHSM2:
| Object ID | Object Type | Object Domains |
|---|---|---|
0x0001 |
Authentication Key | 2,3 |
0x0002 |
Authentication Key | 2 |
0x1234 |
Asymmetric Key | 4,8 |
0xabcd |
Asymmetric Key | 3 |
When listing existing object inside a session authenticated with 0x0001, the keys 0x0001, 0x0002 and 0xabcd are
listed but not 0x1234 as there are no common domains with 0x0001 to operate on.
When listing existing object inside a session authenticated with 0x0002, only 0x0001 and 0x0002 are listed.
Capabilities
To use an object, both the Authentication Key used to authenticate the session and the object involved in the operation must have the necessary capabilities to perform that specific operation.
Example:
Assume the following keys exist in the YubiHSM2:
| Object ID | Object Type | Object Capabilities |
|---|---|---|
0x0001 |
Authentication Key | sign-ecdsa |
0x0002 |
Authentication Key | derive-ecdh |
0x0003 |
Authentication Key | sign-ecdsa,derive-ecdh |
0x1234 |
Asymmetric Key | sign-ecdsa,derive-ecdh |
0xabcd |
Asymmetric Key | decrypt-oaep |
- When authenticating a session with
0x0001, the only operation that can be performed is an ECDSA signing. Since the Asymmetric Key0x1234also has the capabilitysign-ecdsa, it can be used to perform ECDSA signatures but cannot be used to derive ECDH since the authentication key does not have this capability. - When authenticating a session with
0x0002, the only operation that can be performed is ECDH derivation. Since the Asymmetric Key0x1234also has the capabilityderive-ecdh, it can be used to derive ECDH values but cannot be used for performing ECDSA signatures since the authentication key does not have this capability. - When authenticating a session with
0x0003, the Asymmetric Key0x1234can be used to perform both ECDSA signature and ECDH derivation since the authentication key has both these capabilities. - The Asymmetric Key
0xabcdcannot be used in any of the above sessions because none of those authentication keys have thedecrypt-oaepcapability.
Delegated Capabilities
Delegated capabilities are relevant when new objects are created:
- When generating or importing raw objects, the new object can only have capabilities that are in the list of the delegated capabilities of the Authentication Key used to authenticate the session
- When export/import wrapped objects, the object can only have capabilities that are in the list of the delegated capabilities of the Wrap Key used to wrap/unwrap the object
However, when exporting an (a)symmetric key using a public RSA Wrap Key (aka. exporting only the key material, not the object as a whole), neither the delegated capabilities of the Wrap Key nor the Authentication Key are relevant.
Generating and Importing New Objects
When creating new objects, either through generation or import:
- The Authentication Key used to authenticate the session must have capability to create such an object. For example,
generate-asymmetric-keyorput-asymmetric-key - The Authentication Key used to authenticate the session must have delegated capabilities that include all capabilities assigned to the new object. For example, if the new object is assigned the capabilities
sign-ecdsaandderive-ecdh, the Authentication Key must have both these capabilities in its list of delegated capabilities. - The new object maintains the domains it has in common with the Authentication Key
Example:
Assume the following keys exist in the YubiHSM2:
Object
ID
|
Object
Type
|
Object
Domains
|
Object
Capabilities
|
Object
Delegated Capabilities
|
|---|---|---|---|---|
0x0001 |
Authentication Key | 2,3 |
generate-asymmetric-key |
sign-ecdsa,sign-pkcs |
0x0002 |
Authentication Key | 2,4 |
put-asymmetric-key |
sign-ecdsa,sign-pkcs |
0x0003 |
Authentication Key | 3,6 |
generate-asymmetric-key,put-asymmetric-key |
decrypt-pkcs,decrypt-oaep,sign-ecdsa |
When generating an asymmetric key with domains 2,3,6,8 and the capabilities sign-ecdsa,derive-ecdh:
- If the session is authenticated with either
0x0001or0x0003, the operation fails because neither0x0001nor0x0003hasderive-ecdhas a delegated capability - If the session is authenticated with
0x0002, the operation fails because0x0002does not have thegenerate-asymmetric-keycapability
When importing an asymmetric key with domains 2,3,6,8 and the sign-ecdsa capability:
- If the session is authenticated with
0x0001, the operation fails because0x0001does not have theput-asymmetric-keycapability - If the session is authenticated with
0x0002, the operation succeeds and the imported asymmetric key only has domain2because0x0002cannot access domains3,6or8 - If the session is authenticated with
0x0003, the operation succeeds and the imported asymmetric key only has domains3,6because0x0003cannot access domains2or8
Importing Wrapped Objects
When importing wrapped objects:
- Both the Authentication Key and the Wrap Key must have the capability
import-wrapped - All capabilities of the wrapped object must be in the lists of the Wrap Key delegated capabilities
- The Wrap Key must have domain(s) in common with the imported object
Example:
Assume the following keys exist in the YubiHSM2:
| Object ID | Object Type | Object Domains | Object Capabilities | Object Delegated Capabilities |
|---|---|---|---|---|
0x0001 |
Authentication Key | 1,3,7,8 |
put-asymmetric-key |
sign-ecdsa,derive-ecdh |
0x0002 |
Authentication Key | 2,3,7,8 |
import-wrapped |
sign-ecdsa,sign-pkcs |
0x0003 |
Authentication Key | 3,4,7,8 |
import-wrapped |
sign-ecdsa,sign-pkcs,derive-ecdh |
0x1000 |
Wrap Key | 1,2,3,4 |
export-wrapped |
sign-ecdsa,derive-ecdh |
0x2000 |
Wrap Key | 2,3,4,5 |
export-wrapped,import-wrapped |
sign-ecdsa,sign-pkcs |
0x3000 |
Wrap Key | 3,4,5,6 |
export-wrapped,import-wrapped |
sign-ecdsa,sign-pkcs,derive-ecdh |
0x4000 |
Wrap Key | 1,6,12,13 |
export-wrapped,import-wrapped |
sign-ecdsa,sign-pkcs,derive-ecdh |
When importing a wrapped asymmetric key object with domains 1,2,5,6,7 and the capabilities sign-ecdsa,derive-ecdh:
- Using Authentication Key
0x0001and Wrap Key0x1000fails because the Authentication Key does not have theimport-wrappedcapability - Using Authentication Key
0x0002and Wrap Key0x1000succeeds. The imported asymmetric key has the domains1,2 - Using Authentication Key
0x0003and Wrap Key0x1000fails because the Wrap Key does not have theimport-wrappedcapability - Using Authentication Key
0x0003and Wrap Key0x2000fails because the Wrap Key does not havederive-ecdhas a delegated capability - Using Authentication Key
0x0003and Wrap Key0x3000succeeds. The imported asymmetric key will have the domains5,6 - Using Authentication Key
0x0003and Wrap Key0x4000fails because the Wrap Key does not have a common domain with the Authentication Key and thus will not be accessible to use