Access Control and Role Definition

The YubiHSM 2 does not have a traditional login system with fixed user accounts or named roles like “admin” or “user.” Instead, access control is built entirely from three interlocking concepts: Domains, and Capabilities and Delegated Capabilities. Together, they let you define precisely who can do what, and to which objects. A good comparison would be a key card system in an office building, but instead of just opening doors, each key card also specifies exactly which actions the holder is allowed to perform once inside.

Authentication Key as a Credential Holder

An Authentication Key Object is a special object stored on the YubiHSM 2 that an application or person uses to open a Session with the device. It plays the role of a credential: without a valid Authentication Key, meaningful communication with the device is not possible at all.

A new YubiHSM 2 comes with one default Authentication Key pre-installed (ID 0x0001, password password). This default key has full access to everything — it is effectively a superuser credential — and must be replaced or deleted as part of any real deployment.

Multiple Authentication Keys can be stored on the device at the same time. Each one can be configured independently with its own password or ECP256 asymmetric key, its own set of permissions (aka. Capabilities), and its own scope of access (aka. Domains). This is how different roles are defined: by creating different Authentication Keys tailored for different purposes.

Access Control Components

Domains: Controlling the Scope

Domains are a way to group objects on the device into up to 16 logical compartments, numbered 1 through 16. Every object (a key, a certificate, etc.) belongs to one or more domains. Every Authentication Key is also assigned to one or more domains.

The rule is simple: a session can only access objects that share at least one domain with the Authentication Key used to open it.

This means that Domains can be used to isolate groups of objects from one another even if they live on the same physical device.

Example: You have two applications, one handles email signing, the other handles database encryption. You put the email signing keys in Domain 1 and the database encryption keys in Domain 2. The Authentication Key for each application is assigned only to its own Domain, so neither application can ever see or touch the other’s keys.

Capabilities: Controlling the Action

Capabilities are granular permissions that define which specific operations are allowed. They apply at two levels:

  1. The Authentication Key Object: what actions a session opened with this key is permitted to perform at all.
  2. Each object: what actions that specific object can be involved in.

Both must agree for an operation to succeed. If a session has permission to sign, but the target key does not have signing enabled, the operation is rejected, and vice versa.

See a list of capabilities in Capabilities.

Caution

Sensitive capabilities like reset-device and put-authentication-key should only be granted to specifically designated administrative keys.

Delegated Capabilities: Controlling What Others Can Create

Authentication Keys also carry a set of Delegated Capabilities. These define the maximum capabilities that can be assigned to any new object created in a session opened with that key.

In other words, a session cannot create an object that has more permissions than the Authentication Key itself is delegated to grant. This prevents a lower-privileged operator from creating keys with higher privileges than their own.

Putting It Together: Defining Roles in Practice

Because the YubiHSM 2 has no built-in named roles, roles are defined by designing Authentication Keys with the right combination of Domains, Capabilities and Delegated Capabilities. Here are some common patterns:

:class: longtable
Role
Domains
Authentication Key
Capabilities
Notes
Administrator All
put-authentication-key, delete-*,
reset-device, set-option
Manages the device itself
Rarely used
Operator /
Application
Specific
(e.g. 1, 2)
sign-ecdsa, decrypt-pkcs,
generate-asymmetric-key
 Day-to-day cryptographic work
Auditor All get-log-entries Read-only access to audit logs
Key Custodian All export-wrapped, import-wrapped Manages key backup and transfer

Each of these is simply an Authentication Key Object configured with the appropriate Domains and Capabilities. There is nothing special about them beyond that.

A Working Example

A way to understand how the YubiHSM 2 controls access is to walk through a realistic example from beginning to end. The scenario below introduces two people with different responsibilities and shows exactly how Authentication Keys, Domains, and Capabilities work together to enforce the right level of access at each step.

A company uses a YubiHSM 2 to protect the private signing keys for their code-release pipeline. Two people interact with the device:

  • Alice is the security administrator. She sets up the device, manages who has access, and controls key backup and transfer. She works infrequently and always in a controlled environment.
  • Bob is the build-system operator. His automated system uses the YubiHSM 2 every day to sign software releases. He should only be able to sign and nothing else.

Step 1: Setting Up Access Control

When the YubiHSM 2 arrives, it has a single default Authentication Key (ID 0x0001, password password) with full access to everything. Alice’s first job is to replace this with properly scoped keys.

Alice’s Administrator Key

Alice creates a dedicated administrator Authentication Key for herself. It is assigned to all domains so she can reach any object on the device, but its capabilities are carefully limited to the administrative tasks she actually needs:

  • Type: Authentication Key
  • Domains: All
  • Capabilities: put-authentication-key, delete-authentication-key, generate-asymmetric-key, put-asymmetric-key, export-wrapped, import-wrapped, generate-wrap-key, put-wrap-key, get-log-entries, reset-device
  • Delegated Capabilities: sign-ecdsa, exportable-under-wrap

Bob’s Operator Key

Alice then creates a restricted key for Bob’s automated build system. It is assigned only to Domain 1 (where the signing keys will live) and given only the capability to perform ECDSA signatures:

  • Type: Authentication Key
  • Domains: 1
  • Capabilities: sign-ecdsa
  • Delegated Capabilities: None

Now, even if Bob’s credentials were compromised, an attacker could only request signatures using existing keys in Domain 1. They could not generate new keys, export anything, read the audit log, or see objects in any other domain.

Once both keys are in place, Alice deletes the factory default key. From this point on, no one has unrestricted access to the device.

Step 2: Generating and Importing Keys

With access control in place, Alice generates the ECDSA signing key that Bob’s system will use. Because she is using her own Authentication Key (which has generate-asymmetric-key capability), she can do this. Because the key is placed in Domain 1, Bob’s session will be able to use it.

  • Type: Asymmetric Key
  • Domains: 1
  • Capabilities: sign-ecdsa, exportable-under-wrap
  • Delegated Capabilities: None

Bob’s automated build pipeline can now simply open a session using his Authentication Key and requests a signature. If Bob’s session accidentally tries anything else — say, deleting a key or reading audit logs — the device would reject the request immediately, because sign-ecdsa is the only capability his Authentication Key holds.

Step 3: Backing Up and Transferring Keys (Importing Wrapped Objects)

Six months later, the company purchases a second YubiHSM 2 as a backup device. Alice needs to securely copy the signing key from the primary device to the backup without the key material ever being exposed in plaintext.

This is done using a Wrap Key Object, a shared symmetric key that encrypts (“wraps”) objects during transfer so they can only be decrypted inside a device that knows the same Wrap Key.

3a. Create a Wrap Key on Both Devices

Alice generates the same Wrap Key material and loads it onto both the primary and the backup device. The Wrap Key must exist on both ends:

  • Type: Wrap Key
  • Domains: 1
  • Capabilities: export-wrapped, import-wrapped
  • Delegated Capabilities: sign-ecdsa, exportable-under-wrap

The Delegated Capabilities of the Wrap Key acts as a ceiling on what Capabilities any object re-imported through it can be given. Alice sets it to sign-ecdsa,exportable-under-wrap, which matches the signing key’s Capabilities, ensuring that nothing can be imported with unexpected extra permissions.

3b. Export the Signing Key from the Primary Device (Wrapped)

Alice uses the Wrap Key to export the signing key in encrypted form. The result is a blob that is useless without the Wrap Key.

3c. Import the Wrapped Key onto the Backup Device

Alice takes the file containing the wrapped key to the backup device and imports it. The device decrypts the blob using its copy of the Wrap Key and stores the object internally. The key now exists on the backup device with the same properties it was created with.