Assertions: devices
assertion group for Ubuntu Core developers for snapd developers for administrators
The brand signs the model and the model names who else may sign for the device through serial-authority, system-user-authority and preseed-authority. The device generates its own key, proves it in a serial-request and receives a serial; from then on the device key signs device-session-request, confdb-control and response-message. snap-repair has its own root of trust; hardware-identity is new and unused by snapd; cluster is experimental.
On the map: assertions district
01 Who signs for a device
The brand signs the model; the model's *-authority headers name other signers. The serial binds a device key that then signs device-session-request, confdb-control and response-message. repair has its own root; hardware-identity is new and unused by snapd; cluster is experimental.
Who vouches for an acme-gateway? Not only the store. The brand, acme, signs the model, with a key that Canonical issued. The model names who else may sign for this device: who issues its serial, who may create system users, and who may sign preseed data. The gateway makes its own key and gets a serial binding that key to acme, the model and a serial number. From then on, the device key signs what the gateway says about itself: store sessions, confdb-control and replies to operators. Repairs have their own root of trust. Two types are new: snapd doesn't act on hardware-identity, and cluster is experimental.
02 The model names other signers for Ubuntu Core developers for snapd developers for administrators
Illustrative; acme-factory is invented. authority-id must equal brand-id. serial-authority and preseed-authority list extra signers (brand always included, no *); system-user-authority may be *. A new signer needs a new model revision.
Here's the acme-gateway model, cut down to its signers. It's signed by its brand, and the authority and the brand must be the same account. serial-authority lets another account issue serials as well, here acme's factory account. serial-authority and preseed-authority are lists, the brand is always added, and neither accepts a star. Preseed data must be signed by an account in the preseed-authority. system-user-authority may be a list, or a star for anyone. Leave it out and only the brand may sign system users. The model changes only through a new revision signed by acme, so adding a signer means a remodel.
03 Registration in two requests for Ubuntu Core developers for snapd developers for administrators
generate-device-key, then request-serial: a request-id, then a serial-request signed by the new key. 202 means poll again in 60 s. The returned serial must match brand, model and key, and is saved to ubuntu-save too.
A new gateway boots. Where does its serial come from? Snapd starts one change, initialize device. The gadget's prepare-device hook may run first, to point at acme's own device service. Snapd makes the device key, then sends two requests. The first fetches a nonce, the request-id. The second sends a serial-request, signed by the new key to prove the gateway holds it. A 200 answer carries the serial, which must match brand, model and key. A 202 means ask again in sixty seconds, with the same request. With store.access=offline, and no device service of the gadget's own, there's a key but no serial.
04 The device key signs for the device for Ubuntu Core developers for snapd developers
device-session-request (nonce, timestamp) is signed by the device key and sent with the serial and model to get a store session. The same key signs confdb-control and response-message, both experimental.
The gateway has its serial. What's it good for? The key named in it now speaks for the device. When the store wants a device session, snapd fetches a nonce, then sends a device-session-request signed by the device key, along with the serial and the model. The store answers with a session, and snapd attaches it to later store requests. Without a serial there is no session, and the gateway talks to the store anonymously. The same key also signs confdb-control and the replies to remote management messages. Both are experimental, and the next deck covers them.
05 A user from a USB stick for administrators for Ubuntu Core developers for snapd developers
Illustrative. auto-import.assert on a USB stick is acked and creates the user automatically on a Core device with no users. The signer must be allowed by system-user-authority. By hand: snap ack, then snap create-user --known.
A technician arrives at a fresh acme-gateway with a USB stick. There's no account to log in with yet. On the stick is an auto-import..assert file holding a system-user assertion: a username, a password hash and ssh-keys. snap auto-import acks it, and the user is created automatically, but only on Ubuntu Core, and only while the gateway has no users. The signer must be allowed by the model's system-user-authority, and series, model and serial must match. Without a models list, the assertion can be valid for a year at most. By hand, it's snap ack, then snap create-user --known.
06 Repairs have their own root of trust for Ubuntu Core developers for snapd developers for administrators
snap-repair walks repairs/canonical/N, verifies against its embedded repair-root key, filters by headers and runs the body as a script that answers done, skip or retry. Not on classic.
What if snapd itself can't fix the gateway? Repairs, in snapd's words, run repair code to fix up broken systems, and they come through a separate program, snap-repair, on its own timer. It runs four times a day, with a random delay. It walks Canonical's repair sequence, one, two, three, until a number isn't found. It trusts one key built into snap-repair, the repair-root, and not snapd's roots. Each repair says which series, models, architectures, bases and modes it applies to. Its body is a script, run as root, that reports done, skip or retry. Snap repairs lists what ran. Classic systems have no snap-repair.
07 New types: hardware-identity and cluster for snapd developers for Ubuntu Core developers
hardware-identity has no feature flag and feeds a server-side check through the prepare-serial-request hook; snapd consumes none. cluster is experimental and read only by the cluster manager behind experimental.clustering, with no way to install one yet.
How does a gateway prove at registration that it's really acme's hardware? Traditionally, the Ubuntu Core docs say, with an API key built into a whole batch of images. hardware-identity is the newer answer. It binds a hardware key to a manufacturer and a hardware name, and its issuer signs it. The gadget's prepare-serial-request hook puts that key's hash and a signature of the request-id into the registration.body, and the model service checks them. Snapd itself reads none of it. Cluster describes devices grouped into subclusters, with the snaps each should run. Only the experimental cluster manager reads it, and nothing can install one yet.
08 Where to go from here
Roads: how assertions work, the model, device hooks, confdb and messages, validation sets, identity and store, snapctl model, and boot and recovery.
So an acme-gateway is vouched for by acme's model, its own key and the serial that binds the two. Here's where to go next. Assertions: how they work shows how any statement is checked and stored. The model deck covers the gateway's snaps, grade and remodelling. The device hooks deck covers prepare-device and prepare-serial-request. Confdb and messages shows what the device key signs next. Snaps and validation covers the validation sets a model enforces, and identity and store covers brand accounts and keys. Finally, snapctl model reads the model from inside a snap, and boot and recovery is where the model is first read.
Read more
Who decides the signer
| Assertion | Decided by |
|---|---|
model | the type |
serial | the model |
system-user | the model, checked when the user is created |
preseed | the model, checked when the seed is installed |
serial-request | the request itself |
device-session-request, confdb-control, response-message | the serial |
repair | snap-repair |
hardware-identity | the type |
cluster | the cluster manager |
serial-authority and preseed-authority are lists and always include the brand; * is refused. system-user-authority is a list or *; without it only the brand may sign. A cluster update must keep the same signer and cluster-id and raise sequence.
Registration
| Step | Detail |
|---|---|
| Change | become-operational, summary Initialize device |
| Tasks | run-hook (prepare-device, when the gadget has it), generate-device-key, request-serial |
| Device service | the store, https://api.snapcraft.io/api/v1/snaps/auth/ with request-id and devices; or the gadget's device-service.url with request-id and serial |
Gadget options set by prepare-device | device-service.url, device-service.headers, device-service.access, registration.body, registration.proposed-serial |
| First request | POST request-id; the answer is a nonce |
| Second request | POST a serial-request with brand-id, model, request-id, device-key, optional serial, and the body from registration.body |
| HTTP 200 | the serial, optionally followed by other assertions; it must match brand, model and device key |
| HTTP 202 | asked again after 60 seconds with the same request |
| HTTP 202 after a prepare-serial-request hook | the retry re-reads registration.body as a string and is expected to fail (suspected snapd bug, findings/review/BUGS.md #28) |
| No network | retried after 30 seconds |
| Other failures | retried up to 15 times, then the change fails |
| Saved | the model and serial also go to the assertion database on ubuntu-save |
| No serial requested | store.access=offline while the store is the device service, or the gadget's device-service.access=offline |
The prepare-serial-request gadget hook, when present, runs after the request-id is fetched and must write hardware-id-key-sha3-384 and request-id-signature into registration.body; otherwise registration fails with 'prepare-serial-request' hook did not set mandatory field "<field>" in registration body.
for snapd developers for Ubuntu Core developers
Store sessions
| Step | Detail |
|---|---|
| Nonce | POST api/v1/snaps/auth/nonces |
| Session | POST api/v1/snaps/auth/sessions with the device-session-request, the serial and the model |
| Use | later store requests carry the session in Snap-Device-Authorization |
| No serial | no session; the device talks to the store anonymously |
System users
| Condition | Effect |
|---|---|
automatic creation (USB auto-import.assert) | only when the device has no users; with users, nothing is created and no error is shown |
snap set system users.create.automatic=false | turns automatic creation off |
| classic | system user administration via snapd is not allowed on this system |
snap create-user --known on a device with users | cannot create user: device already managed unless --force-managed |
no models header | until at most 365 days after since |
serials header before the device has a serial | creation waits for registration |
| an existing username | skipped |
grade dangerous | systems/<label>/auto-import.assert in the seed is also read, once |
Repairs
| Item | Value |
|---|---|
| Timer | snapd.snap-repair.timer: 05:00, 11:00, 17:00 and 23:00, each with up to 2 hours' random delay |
| Fetched | https://api.snapcraft.io/v2/repairs/canonical/<n>, n = 1, 2, 3 … until one is not found; only brand canonical |
| Trust | the repair-root account-key built into snap-repair, not snapd's roots |
| Filters | series, models, architectures, bases, modes (run, recover); disabled: true skips |
| Body | a script run as root, at most 30 minutes; it reports repair done, repair skip or repair retry |
| List | snap repairs |
| Classic | cannot use snap-repair on a classic system |
Further reading
- model: every model header, including the three authorities.
- serial: the serial assertion's fields.
- system-user: headers and validity rules.
- Add a system user: the USB stick procedure step by step.
- repair: the repair assertion and how scripts report back.
- Secure device onboarding: why hardware-identity exists and the registration stages it adds.
Roads from here
SNAPCTL · the snap's API into snapd
- snapctl: device and system — snapctl model inside a snap
ASSERTIONS · signed statements snapd trusts
- Assertions: how they work — how any assertion is checked and stored
- Assertions: confdb and messages — confdb-control and response-message signed by the device key
- Assertions: snaps and validation — validation sets that a model enforces
- Assertions: identity and store — brand accounts and keys and the store assertion
HOOKS · code snapd runs inside a snap
- Hooks: device setup — the prepare-device and prepare-serial-request gadget hooks
UBUNTU CORE · boot
- Ubuntu Core: how a device boots and recovers — seeding and boot modes where the model is first read
UBUNTU CORE · install and recovery
- Model, gadget and kernel — the model's snaps and grade and remodelling