Skip to content

Core Concepts: Subjects, Roles, and Access Control

The Keyserver enforces strict access control for every signing and administrative operation.
This section describes the core entities used to define permissions and explain how access is managed throughout the system.

Operations

While not a central element of the access control system, operations still have a role in it. Operations are tickets on which cryptographic actions a bound. An Operation contains:

  • Expiry time
  • A Set of keys and the number of time they can each be used
  • A description of the purpose of this "operation"-ticket (so approvers can see what they approve).

An operation is considered approved when each key has been approved the sufficient number of approvers

Subjects

A subject is any entity that interacts with the Keyserver. Subjects fall into two categories:

Users

A user is a human who authenticates interactively through the user interface.
Users typically perform administrative tasks, inspect audit log or approve signing operations.

Clients

A client is a non-interactive system—such as a CI/CD pipeline — that authenticates using a OAuth2 Client Credentials Flow.
Clients request signing operation-"tickets" programmatically through the REST API or via PKCS#11.

Authentication Differences

  • Users authenticate via Authorization Code Flow (with optional PKCE).
  • Clients authenticate via Client Credentials Flow.

Both authentication methods produce OAuth2 access tokens that the Keyserver validates before allowing API access.

Roles

A role defines a set of permissions. Permissions grant a subject access to specific API methods, UI features, or cryptographic actions on signing keys.

Roles are the primary method of expressing what a subject is allowed to do.

Types of Roles

Adding permissions to each role should primarily be done by using the Natures metatypes. Only in rare cases using lowlevel API/Key permissions directly.

There are natures reflecting the most common role types:

User

MUST be added to any role that is meant for users, providing fundamental access that the remaining builds on.

Admin (User / Keys)

Administrators configure the Keyserver: - Create or edit subjects and associate roles - Create or edit roles
- Create or modify keys and adjust approval requirements - View audit log

Administrative actions require an administrative session (explained later).

Orderer (Code signing / Device Certificates)

An orderer can perform cryptographic actions with one or more keys on approved operation-"tickets" Most clients belong to at least one orderer role.

Orderers cannot approve operation-"tickets"—they can only create them.

Approver

An approver reviews and authorizes operation-"tickets" on which cryptographic actions can be performed. The approval workflow depends on the configuration of each key. For example, dev-keys and some test-keys may require no approval.

Reviewer

A reviewer has read-only access to the administration system including audit logs.
Reviewers cannot perform or approve actions.

Key-Scoped Roles

Certain permissions apply to a specific signing key. For example:

  • order:key2 — may request signing actions using key2.
  • approve:key4 — may approve operation-"tickets" involving key4.

This allows organizations to separate workflows such as:

  • Operation-"ticket" creation
  • Development signing (dev/test keys configured with no approval requirement)
  • Operation-"ticket" approval (production keys)
  • Production firmware signing using approved operation-"tickets" (production keys)
  • Production device certificate issuance using approved operation-"tickets" (production keys)

A subject may be associated with any number of key-scoped permissions.

Administrative Sessions

All changes in the administration area require explicit authorization from a configurable number of administrators.
This mechanism is known as an administrative session.

Purpose

Administrative sessions ensure: - Sensitive changes follow the “four-eyes principle” - No single administrator can unilaterally modify security settings
- All administrative changes are audit logged on administration session ID and easily traceable in the Audit area

Workflow

  1. An administrator creates a new administrative session and provides a description.
  2. Other administrators authorize the session until the required number of approvals is met.
  3. While the session is active, the administrator may perform changes.
  4. When finished, the session is closed explicitly or expires automatically.

Roles themselves define which subjects may create and/or approve administrative sessions.

How Access Control Works

Access control in the Keyserver is evaluated in three steps:

1. Authentication

The subject (user/client) provides a valid OAuth2 access token issued by the configured authorization server. This token is mapped to a registered subject in the Keyserver.

2. Permission Evaluation

The Keyserver determines which permissions (obtained from a union of it's roles) the accessing subject has, including: - Key-agnostic permissions (Admin role permissions, Reviewer role permissions) - Key-scoped permissions (order:key2, approve:key3)

3. Operation Enforcement

For each API call: - The subject must have the required permission for the accessed API - If the call involves a key, the subject must have the required key-scoped permission.
- If the call involves a valid operation "ticket" the operation "ticket" must be associated with the involved key and be sufficiently approved.

This allows fine-grained control while keeping the permission model understandable and predictable.

Summary

  • Subjects represent users or automated clients.
  • Roles define sets of permissions, both key specific and key agnostic.
  • Orderers first create operations; Approvers authorize them. Afterwards orderers perform signing operations
  • Admins configure the system through a protected and audited administrative session.
  • Reviewers inspect setup/configuration and audit log but cannot change anything
  • The access control system ensures only authorized entities can create, approve, or perform cryptographic actions.

This foundation supports secure signing workflows and minimizes the risk of key misuse.