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

▶ Watch this deck — 8 scenes, ~6 min

01 Who signs for a device

DEVICES acme account-keyissued by Canonicalmodelacme-gateway, signed by acme serialserial-authoritysystem-usersystem-user-authoritypreseedpreseed-authority device keygenerated on the device device-session-requeststore sessionconfdb-controlexperimentalresponse-messageexperimental repairchecked by snap-repairagainst its own root hardware-identityclusternew; cluster experimental
acme's account-key signs the acme-gateway model; the model names the signers of serial, system-user and preseed; the serial binds the device key, which signs device-session-request, confdb-control and response-message; repair has its own root; hardware-identity is new and cluster is experimental

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

MODEL illustrative, signers only type: model authority-id: acme series: 16 brand-id: acme model: acme-gateway base: core24 grade: signed serial-authority: - acme-factory snaps: … sign-key-sha3-384: … must match acme is added too headeracceptsserial-authoritylist · brand added · no *preseed-authoritylist · brand added · no * system-user-authoritylist, or * for anyoneabsent: brand only a new signer needs a new model revisionsigned by acme: a remodel
An illustrative acme-gateway model with authority-id equal to brand-id and serial-authority listing the invented account acme-factory, beside a table of serial-authority, system-user-authority and preseed-authority, and a note that a new signer needs a new model revision

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

REGISTRATION change become-operational · "Initialize device"run-hook [prepare-device]→generate-device-key→request-serialthe hook is optional, from the gadget deviceservicePOST …/request-idrequest-id POST …/serial or …/devicesbrand-id · model · request-id · device-keyserial-request, signed by the new device key 200: serial, must match brand, model and key id202: poll later, retry in 60 s, same request $ snap model --serialbrand-id: acmemodel: acme-gatewayserial: <serial>saved with the model to ubuntu-savestore.access=offline (no device-service.url):a device key but no serial
The become-operational change runs the optional prepare-device hook, generate-device-key and request-serial; the device fetches a request-id, sends a serial-request signed by the new key, and gets a serial on 200 or polls again in 60 seconds on 202

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 KEY serialacme · acme-gateway · serial→ device-key devicestorePOST …/auth/noncesnonce POST …/auth/sessionsdevice-session-requestnonce · timestamp · signed by the device key+ serial-assertion + model-assertion device session macaroonlater store requests carry Snap-Device-Authorization no serial: no device sessionstore requests go out anonymously the same device key also signsconfdb-controlexperimentalresponse-messageexperimentalnext: confdb and messages
The serial binds the device key; snapd fetches a nonce from the store, sends a device-session-request signed by the device key with the serial and model, and gets a device session; without a serial there is no session and store requests are anonymous; the same key signs confdb-control and response-message

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

SYSTEM-USER USB stickauto-import.assert type: system-userauthority-id: acmebrand-id: acmeemail: field@acme.exampleusername: fieldpassword: $6$…models:- acme-gatewaysince: …until: … snap auto-importsnap ackcreate-user (automatic)run by snapd.autoimport.serviceonly on Ubuntu Core with no users yetusers.create.automatic=false turns it off checked when the user is createdsigner in system-user-authorityseries, model and serial matchvalid now no models: until at most 365 days after sinceserials: waits for the device's serial $ sudo snap ack user.assert$ sudo snap create-user --known field@acme.example
An illustrative system-user assertion signed by acme for the acme-gateway model; auto-import.assert on a USB stick goes through snap auto-import and snap ack to automatic user creation 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

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

REPAIR snapd.snap-repair.timer5,11,17,23:00 + up to 2 hsnap-repair run api.snapcraft.io/v2…/repairs/canonical/1…/repairs/canonical/2…/repairs/canonical/3… until one is not foundonly brand canonical is walked embedded in snap-repairaccount-key repair-rootsnapd's trusted roots applies only if the headers matchseries · models · architecturesbases · modesbody: a script run as rootr<rev>.script · 30 min timeoutrepair done | skip | retry $ snap repairsRepair Rev Status Summaryno snap-repair on classic
A timer runs snap-repair, which fetches canonical repairs 1, 2, 3 until not found, verifies them against its embedded repair-root key rather than snapd's roots, filters by headers and runs the body as a script that reports done, skip or retry; snap repairs lists them

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

NEW TYPES traditionally: an API key built into a whole batch of images (Ubuntu Core docs) hardware-identityissuer-id = authority-idmanufacturer · hardware-namehardware-idhardware-id-key (PEM, RSA or ECDSA)hardware-id-key-sha3-384 prepare-serial-request hookwrites registration.body withhardware-id-key-sha3-384, request-id-signature→ the model service verifies it snapd itself consumes nothing clusterexperimentalcluster-id · sequencedevices: <serial>.<model>.<brand-id>subclusters: name · devices · snapsclustered | evacuated | removed experimental.clustering → cluster managerchange apply-cluster-subclusterno API, CLI or store path installs one today
Two new types, after a note that registration has used an API key built into a whole batch of images: hardware-identity, whose key hash and request-id signature the prepare-serial-request hook puts in the registration body for the serial service to verify, and cluster, experimental and read only by the cluster manager behind experimental.clustering

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 Assertions: devices Assertionschecked and storedThe modelsnaps, grade, remodel Device hooksprepare-device and moreConfdb and messageswhat the device key signs Snaps and validationvalidation sets enforcedIdentity and storebrand accounts and keys snapctl modelthe model inside a snapBoot and recoverywhere the model is read
Roads from the devices deck: assertions, the model, device hooks, confdb and messages, validation sets, identity and store, snapctl model, and boot and recovery

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

AssertionDecided by
modelthe type
serialthe model
system-userthe model, checked when the user is created
preseedthe model, checked when the seed is installed
serial-requestthe request itself
device-session-request, confdb-control, response-messagethe serial
repairsnap-repair
hardware-identitythe type
clusterthe 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

StepDetail
Changebecome-operational, summary Initialize device
Tasksrun-hook (prepare-device, when the gadget has it), generate-device-key, request-serial
Device servicethe 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-devicedevice-service.url, device-service.headers, device-service.access, registration.body, registration.proposed-serial
First requestPOST request-id; the answer is a nonce
Second requestPOST a serial-request with brand-id, model, request-id, device-key, optional serial, and the body from registration.body
HTTP 200the serial, optionally followed by other assertions; it must match brand, model and device key
HTTP 202asked again after 60 seconds with the same request
HTTP 202 after a prepare-serial-request hookthe retry re-reads registration.body as a string and is expected to fail (suspected snapd bug, findings/review/BUGS.md #28)
No networkretried after 30 seconds
Other failuresretried up to 15 times, then the change fails
Savedthe model and serial also go to the assertion database on ubuntu-save
No serial requestedstore.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

StepDetail
NoncePOST api/v1/snaps/auth/nonces
SessionPOST api/v1/snaps/auth/sessions with the device-session-request, the serial and the model
Uselater store requests carry the session in Snap-Device-Authorization
No serialno session; the device talks to the store anonymously

System users

ConditionEffect
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=falseturns automatic creation off
classicsystem user administration via snapd is not allowed on this system
snap create-user --known on a device with userscannot create user: device already managed unless --force-managed
no models headeruntil at most 365 days after since
serials header before the device has a serialcreation waits for registration
an existing usernameskipped
grade dangeroussystems/<label>/auto-import.assert in the seed is also read, once

Repairs

ItemValue
Timersnapd.snap-repair.timer: 05:00, 11:00, 17:00 and 23:00, each with up to 2 hours' random delay
Fetchedhttps://api.snapcraft.io/v2/repairs/canonical/<n>, n = 1, 2, 3 … until one is not found; only brand canonical
Trustthe repair-root account-key built into snap-repair, not snapd's roots
Filtersseries, models, architectures, bases, modes (run, recover); disabled: true skips
Bodya script run as root, at most 30 minutes; it reports repair done, repair skip or repair retry
Listsnap repairs
Classiccannot use snap-repair on a classic system

Further reading

Roads from here

SNAPCTL · the snap's API into snapd

ASSERTIONS · signed statements snapd trusts

HOOKS · code snapd runs inside a snap

UBUNTU CORE · boot

UBUNTU CORE · install and recovery