Skip to content

Operator-key authorization

Every action that changes what the verifier trusts is attributable to a specific operator, and the verifier decides whether that operator may perform it. This chapter covers how an operator's identity is established, what a role permits, and how the first one comes into existence.

There is no key file

Earlier releases authorized operators with a --key file passed on the command line. That path is gone. Identity is now bound to the kernel UID of whoever is talking to the daemon over its Unix socket:

etminan-verifier op whoami

A UID cannot be copied to a laptop, pasted into a ticket, or left in shell history. The daemon reads it from the socket peer credentials — the caller cannot assert it.

Why this is the stronger design

A key file answers "who holds this file". A socket peer UID answers "which account on this machine is calling right now", and it is the kernel that answers, not the caller. The custody problem does not disappear — it moves to account management, where your organization already has controls.

Roles

Role Intent
viewer Read the fleet's state; change nothing
operator Day-to-day attestation work, scoped to the hosts assigned to them
admin The registry itself — who exists, what they may do

A scope narrows an operator to a subset of hosts; admin actions on the registry are not scoped. Which role may attempt which action is enforced at a single authorization choke point, so there is one place to reason about rather than a check scattered across commands. See RBAC.

Managing identities

# who exists today
etminan-verifier op identity list

# map a UID to a role and scope (admin)
etminan-verifier op identity add --uid 1007 --role operator \
    --scope prod --label "a.schmidt"

# revoke it (admin)
etminan-verifier op identity revoke --uid 1007

Registry changes can require four eyes

identity add and identity revoke are exactly the actions the operator-key dual-control token covers — a change to who may act at all. Where that policy is in force, a second admin must co-sign. See Dual control.

Identities are added, never rewritten: a signed historical row keeps the role it was signed with, so op verify-signatures can still verify actions taken under an authorization that has since changed.

Bootstrapping the first admin

An empty registry has nobody who may add anybody — so there is exactly one one-time exception:

sudo etminan-verifier op bootstrap --uid 1001 --label "r.jung"

It must run as root, and it installs the first admin. Once an admin exists, this path is closed; further identities go through op identity add under the normal rules.

This is the highest-value moment in the deployment

Bootstrapping decides who controls the trust root. Do it deliberately, on the verifier's console, with the person present — not over a shared session, and not as a step in an unattended provisioning script.

Optional second factor

TOTP can be required per role:

etminan-verifier op enroll-totp                      # enrol your own second factor
etminan-verifier op login [--code <NNNNNN>]          # open a 2FA session
etminan-verifier op logout                           # close it
etminan-verifier op totp-policy --role admin --required true   # admin

A UID establishes which account; a second factor establishes that the person is present. For admin roles on a shared jump host, that difference matters.

Everything is audited

Each action records the acting identity and lands in the hash-chained audit log, and op verify-signatures checks the chain and the registry together. An action that cannot be attributed to an authorized identity does not verify.

Next steps