Approve machines for sealed secrets#
Only machines an admin approved can decrypt a workspace's sealed secrets. Approving a machine is a signature: your device signs the machine's key fingerprint after you compared it with what the machine itself prints. This page shows how to approve the first machine (which makes the workspace key), approve more, manage the devices allowed to approve, revoke a machine and rotate the key.
Before you begin#
- You need the admin role in the workspace (organisation admins are admins of every workspace). Editors and viewers see the machines and their state but cannot approve.
- You need a shell on the machine you approve, to read its fingerprint.
- The machine runs the agent's credentials part
(
astraeus-agent-credentials, installed by default) of a release with sealed secrets. An older agent reports no key: update it from the console (see Update, drain and remove). - The machine belongs to the workspace's organisation. Approve the machines
your runs that use sealed secrets can be placed on: a worker on a machine
that is not approved waits in
Preparing. - For
astra, install and sign in. For the API, setTOKENandAPIas in Drives.
Read a machine's fingerprint#
On the machine, as root:
This is the first 128 bits of the SHA-256 of the machine's public key, in
eight groups. The key is made the first time the credentials agent starts
(/var/lib/astraeus/credentials/sealing.key, mode 0600) and never leaves
the machine. Compare every group: a fingerprint that differs is not your
machine's key.
Approve the first machine#
The first approval in a workspace makes the workspace key, on the machine you approve, and makes your device the workspace's first approver.
- Open Secrets in the workspace. Machines that can open secrets lists the organisation's machines that reported a key, with their Key fingerprint, whether their Agent is up, and their Approval.
- Click Approve on the machine. The dialog shows its fingerprint in large type.
- Compare it with what the machine printed. If it matches, tick It matches what the machine printed.
- Click Sign and approve. Your browser makes its approver key (kept in this browser profile; it cannot be exported), registers itself under Approvers, and signs the approval.
- Within seconds, if the machine is online, Approval turns to Approved with Made the workspace key w…, and the workspace is Ready.
$ astra secrets machines
Workspace key: none yet (NoKey)
No machine is approved for this workspace's secrets yet: approve one (it makes the workspace key).
MACHINE FINGERPRINT ONLINE APPROVAL
gpu-01 9C41 07E2 5BDA 3F18 C6A0 72D4 E915 0B6F yes not approved
gpu-02 41D8 CD98 F00B 204E 9800 998E CF84 27E0 yes not approved
Approvers:
none yet (the first device to approve a machine becomes one)
$ astra secrets trust gpu-01
Machine gpu-01's key: 9C41 07E2 5BDA 3F18 C6A0 72D4 E915 0B6F
Check it is what the machine itself prints: astraeus-agent credentials --fingerprint
Approve gpu-01 for this workspace's secrets? [y/N] y
gpu-01: Waiting Approved; waiting for a machine that holds the workspace key
astra makes its approver key on first use,
~/.config/astra/approver.p8 ($XDG_CONFIG_HOME/astra/approver.p8),
readable by you only. --yes (-y) skips the question: use it only
when you compared the fingerprint another way.
A few seconds later:
$ astra secrets machines
Workspace key: w5e0c8a71d24b9f63 (Ready)
Key w5e0c8a71d24b9f63 ready; held by 1 machine
MACHINE FINGERPRINT ONLINE APPROVAL
gpu-01 9C41 07E2 5BDA 3F18 C6A0 72D4 E915 0B6F yes Granted: Made the workspace key w5e0c8a71d24b9f63
gpu-02 41D8 CD98 F00B 204E 9800 998E CF84 27E0 yes not approved
Approvers:
7A3B 0C55 91E4 D2F8 6B10 A9C7 3E52 F084 approver astra on laptop (this device)
GET $API/sealing/self returns the workspace's state, its key, the
machines with their public_key and fingerprint, and the approvers.
An approval is a request your device signs:
- Register your device's ECDSA P-256 public key (uncompressed point,
unpadded base64url):
POST $API/sealing/self/approverswith{"public_key": "<key>", "label": "<what to call it>"}. - Sign, with that key (ECDSA P-256, SHA-256, the 64-byte
r ‖ sform, base64url), the textastraeus-sealing-approval/v1\nnamespace\nmachine\nthe machine's full fingerprint (64 hex digits), where namespace is thenamespacethatGET $API/sealing/selfreturns. POST $API/sealing/self/approvalswith{"node": "gpu-01", "public_key": "<the machine's public_key>", "approver_public_key": "<your key>", "signature": "<signature>"}. It answers202 Acceptedwith the workspace view.
The first approver is trusted on first use: whoever approves first in a workspace becomes its approver. Approve the first machine yourself, soon after the workspace has machines.
Keep two approved machines and two approver devices
The workspace private key exists only on approved machines. If no machine
that holds it is left, nothing can decrypt the workspace's secrets or
give the key to a new machine. In the same way, a browser profile whose
site data is cleared loses its approver key. Approve at least two
machines and make a second device an approver (for example astra and
your browser).
Approve another machine#
Once the workspace has a key, approve each further machine the same way:
read its fingerprint on it, then Approve in the console or
astra secrets trust <machine>. Your device must already be an approver of
the workspace (see Approver devices).
A machine that holds the key passes it on to the new machine, after checking
your signature against the workspace's approver list. The new machine's
approval goes from Waiting to Approved (Granted, Holds workspace key
w… (wrapped by machine gpu-01)). That needs a machine holding the key to be
online; until one is, the approval waits and Secrets says which machine
it waits for.
| Approval | astra |
Meaning |
|---|---|---|
| Waiting | Waiting |
Approved; waiting for a machine that holds the key, or (first machine) for it to make the key. |
| Approved | Granted |
The machine holds the workspace key. |
| Failed | Refused |
The machine's key changed since it was approved. Compare its new fingerprint and approve it again. |
The workspace's own state:
State (API, astra) |
Meaning |
|---|---|
NoKey |
No machine is approved yet. |
WaitingForMachine |
Approved machines wait for one to come online and make the key. |
Ready |
Values can be written and decrypted. |
Rotating |
A rotation is under way; runs keep working. |
Approver devices#
An approver is a device whose signature lets a machine have the key: a
browser profile or an astra installation. A device that approves for the
first time registers itself; until an existing approver endorses it, its
approvals do not count.
Approvers lists each Device, its Fingerprint, its State (Active: an approver; Waiting: registered, not endorsed; Pending: endorsed, being confirmed; Terminating: being removed) and when it was Added. Your own browser is marked this browser.
To make another device an approver:
- On the new device, try to approve a machine. It is refused with This browser is not an approver of this workspace yet, and the device appears under Approvers, with its fingerprint.
- On a device that is an approver, click Endorse on the new device, after comparing its fingerprint with the one the new device shows. Your browser signs the endorsement.
- A machine holding the workspace key confirms it; the device becomes Active. Approve the machine again from the new device.
Remove takes a device off the approvers.
On the new device, approving a machine registers it and fails with what to do:
$ astra secrets trust gpu-02
Machine gpu-02's key: 41D8 CD98 F00B 204E 9800 998E CF84 27E0
Check it is what the machine itself prints: astraeus-agent credentials --fingerprint
Approve gpu-02 for this workspace's secrets? [y/N] y
astra: This device is not an approver of the workspace yet. On a device that is, run: astra secrets approvers trust D2F86B10A9C73E52F0847A3B0C5591E4
On an approver device:
$ astra secrets approvers trust D2F86B10
Device D2F8 6B10 A9C7 3E52 F084 7A3B 0C55 91E4 (astra on workstation)
Make it an approver of this workspace (it can then approve machines)? [y/N] y
Endorsed; it becomes an approver once a machine holding the workspace key confirms.
A fingerprint can be given whole or by a unique beginning; spaces are
ignored. astra secrets approvers (or approvers list) lists them:
approver, pending (not endorsed), endorsed, confirming,
being removed. astra secrets approvers remove <fingerprint> takes a
device off.
| Request | What it does |
|---|---|
POST $API/sealing/self/approvers |
Register a device: {"public_key", "label"}. |
POST $API/sealing/self/approvers/<fingerprint>/endorse |
Endorse a device: {"approver_public_key", "signature"}, the signature of an approver over astraeus-sealing-approver/v1 \n namespace \n the device's full fingerprint. |
DELETE $API/sealing/self/approvers/<fingerprint> |
Remove a device. |
A fingerprint in a path may be a unique beginning of at least 8 characters.
The last approver cannot be removed (409 LAST_APPROVER): endorse another
device first. A workspace has at most 256 approver devices.
Revoke a machine#
Revoke a machine you no longer trust with the workspace's secrets, or before you give it away.
In Secrets, click Revoke on the machine and confirm.
The machine stops receiving secrets at once. If it held the workspace key, the key is rotated so that what it held decrypts nothing new. Removing a machine from the cluster does the same.
A revoked machine keeps what it already decrypted
Rotation stops the machine from decrypting new values. Values it already received for its runs may still be on it. If that matters, change those values at their source and set them again.
Rotate the workspace key#
Rotation makes a new workspace key on an approved machine, gives it to every machine still approved, re-encrypts every sealed secret of the workspace to it, and retires the old key. Runs keep working throughout. It happens by itself when a machine that held the key is revoked, removed, or reports a new key (a reinstalled machine). To rotate at any time:
In Secrets, click Rotate key above the machines, and confirm. The button reads Rotating… until it is done.
The second sentence is the workspace's state when you asked;
astra secrets machines shows the rotation's progress.
A rotation needs an approved machine that holds the key to be online. The
workspace shows Rotating with Re-encrypting secrets from key w… to w…
until every secret is re-encrypted, then Ready with the new key. A write
made during a rotation is encrypted to the new key. Rotation changes the key,
not your values.
Limits#
| Limit | Value |
|---|---|
| Approved machines per workspace | 256 |
| Approver devices per workspace | 256 |
| Retired keys remembered | The last 20 |
| A machine's answer to a key operation | 30 s; then the next attempt |
Troubleshooting#
| Symptom | Cause | Fix |
|---|---|---|
The machine is not listed; astra secrets trust: machine gpu-01 has not reported a sealing key (update its agent from the console: an older agent cannot open sealed secrets) |
Its agent is older than sealed secrets, or its credentials agent is not running. | Update the agent from the console; check systemctl status astraeus-agent-credentials on the machine. |
409 APPROVER_NOT_TRUSTED: This device (…) is not an approver of this workspace yet: an approver endorses it first. |
Your browser or astra is not an approver of a workspace that already has a key. |
An approver endorses your device; then approve again. |
| Approval Waiting: Approved from a device that is not an approver of this workspace: approve again from one that is, or have one endorse it | The approval was signed before your device was an approver. | Have it endorsed, then approve the machine again. |
| Approval Waiting, workspace message waiting for an approved machine (gpu-01) to come online | No machine that holds the key is online. | Bring one online; the approval completes by itself. |
409 FINGERPRINT_CHANGED: machine gpu-01's key is … now, not the one approved: compare again |
The machine reported a new key after you read its fingerprint. | Read the fingerprint on the machine again and approve again. |
| Approval Failed: The machine's sealing key changed since it was approved (reinstalled?) | The machine's sealing.key was replaced, for example by a reinstall. The key was rotated. |
Compare the new fingerprint and approve again. |
409 LAST_APPROVER |
You tried to remove the only approver. | Endorse another device first. |
409 SEALING_NOT_READY: This workspace has no key to rotate yet. |
Rotation was asked before any machine made the key. | Approve a machine first. |
409 SEALING_BUSY |
The workspace's approvals kept changing during your request. | Retry. |