Assertions: how they work
assertions overview for users for app developers for Ubuntu Core developers for snapd developers for administrators
An assertion is a signed text document of headers and an optional body. snapd checks every assertion against an account-key that chains to one of two assertions compiled into snapd, stores it in its assertion database, and uses it to decide what a snap file is, who published it and what it may do.
On the map: assertions district
01 Signed statements snapd trusts
An assertion is a signed statement. snapd checks each signature, keeps what passes in its assertion database, and decides installs, connections, refreshes and registration from what is stored. Store and brand signatures lead back to a key built into snapd. The district has one deck per group of types.
You install photo editor from the store, and snap list shows revision 42, from the publisher example. How does your laptop know that? The file can't vouch for itself. So with every snap, the store also sends signed statements, called assertions. Snapd checks the signature on each one before it keeps it in its assertion database. Follow the signatures back, and every store and brand signature ends at a key that's built into snapd itself. There are twenty six types, in four groups: identity and store, snaps, devices, and confdb and messages. When snapd installs, connects, refreshes or registers a device, it reads its answers from that database.
02 Anatomy of an assertion for app developers for Ubuntu Core developers for snapd developers for administrators
Headers, an optional body, then the signature. authority-id names the signer and sign-key-sha3-384 the key. Header values are strings, or lists and maps of strings. The stored bytes are the signed bytes: edit one and the signature no longer verifies.
So what does a signed statement look like? Ask snap known for the canonical account, and you get this. Each header is a name, a colon and a value. Type says which of the twenty six kinds it is. authority-id names the signer, and sign-key-sha3-384 names the key it signed with. account-id is the primary key, and a primary key value can't contain a slash. After a blank line comes the signature. Every value is a string, or a list or map of strings, and the stored bytes are the signed bytes. Change one, and the signature fails.
03 Two assertions are built into snapd
The trusted set is the canonical account and its self-signed root account-key. Every other account-key must be signed by a directly trusted authority, so Canonical issues brand and developer keys. Testing builds of snapd add a test root; production builds cannot.
Every signature is checked with a key, and that key is itself an assertion. So who signs the first one? Snapd carries two assertions it trusts directly: the canonical account, and the root account-key, which signs itself. An account-key is accepted only when a directly trusted authority signed it. So a brand or a developer can't sign a key for itself. Canonical's store issues it. A brand still signs its own models with its key. The generic account and the base declaration are built in too, but they can't sign keys. And no setting adds a root key; only testing builds of snapd carry another one.
04 From a snap file to the root key for app developers for Ubuntu Core developers for snapd developers for administrators
From the file's hash to the snap-revision, the snap-declaration, the accounts and the store account-key, ending at the built-in root. The fetcher saves prerequisites first; adding to the database never fetches.
Let's walk the chain for photo editor revision 42. It starts with one fact: the SHA3-384 hash of the file. Snapd asks the store for the snap-revision with that hash. That statement needs two others first, the snap-declaration and the developer's account, and it's signed by a store account-key. Snapd's fetcher follows those links for you: prerequisites first, then the signing key, then it saves. The store key is signed by the root key, which is built in, so the walk stops there. Adding to the database never fetches anything, though. A missing link is an error, which is why snap ack needs a complete file.
05 Three ways to install a snap file general version
snap install photo-editor fetches and checks. snap download, then snap ack, then snap install ./file.snap gives the same result offline. --dangerous skips the assertions: a local revision such as x1, no publisher and no store refreshes.
Your laptop won't always be online. From the store, snapd fetches and checks the assertions itself. To carry photo editor to another machine, snap download writes the snap and an .assert file, and tells you what to run. Install the file alone and it's refused: snapd can't find signatures for it. Snap ack adds the assertions. It installs nothing and fetches nothing, so the .assert file has to be complete. After that, the install looks just like one from the store: revision 42, publisher example. --dangerous skips all of this. You get a local revision such as x1, no publisher, and no refreshes from the store.
06 Three ways in, inside snapd for snapd developers in place of the general version
Store: validate-snap fetches and runs CrossCheck; it has no undo. Ack: a prechecked Batch that never fetches, then DeriveSideInfo from the local database. --dangerous: no lookup, no snap-id. --devmode tries the lookup and falls back.
Here are photo editor's three paths, as the code sees them. For a store download, snapstate adds validate-snap right after download-snap. It hashes the file, fetches the snap-revision and its prerequisites, unlocking the state only for the network part, and cross-checks size, snap-id and revision. Snap ack posts to the assertions endpoint. The daemon adds the file as one batch, which never fetches, in prerequisite order, and a missing prerequisite fails the lot. Installing the snap then derives the SideInfo from the local database alone. --dangerous skips that lookup, and devmode tries it first.
07 A newer revision replaces the old one for administrators for Ubuntu Core developers for snapd developers
One current assertion per primary key in asserts-v0. A higher revision wins; acking an equal or older one is a no-op. Nothing is deleted: a newer revision revokes, for example a snap-declaration with an empty snap-name. Built-in assertions cannot be overridden.
Say the store gives photo editor an automatic alias. It doesn't edit the old snap-declaration; it signs a new revision with the same primary key. Snapd keeps verified assertions under asserts-v0, one directory per type and primary key, and every lookup checks the built-in ones first. A higher revision replaces the stored one. Acking an equal or older one is a silent no-op: snap ack succeeds and the stored one stays. A revision in a newer format is kept beside the old, so an older snapd still reads what it understands. Nothing is deleted. A newer revision revokes, and the built-in roots can't be replaced.
08 Where to go from here
The type decks: identity and store, snaps, devices, confdb and messages. Neighbours: why snaps, how interfaces are implemented, the store and the overlord.
So that's how snapd knows what photo editor is: signed statements, checked back to a key it carries. Four decks cover what each group says. Identity and store has accounts and keys, and how a developer gets a key the store accepts. Snaps has the declaration and revision behind every install, and validation sets. Devices has the model, the serial, and who may sign for a device. Confdb and messages has schemas and remote management. Next door, why snaps explains why the publisher owns the package, how interfaces are implemented shows declarations as policy, the store deck shows where assertions come from, and the overlord runs validate-snap.
Read more
for app developers for Ubuntu Core developers for snapd developers for administrators
How an assertion is encoded
| Part | Rule |
|---|---|
| Layout | headers, then an optional body after a blank line, then a blank line and the signature. The last blank line in the text separates the signed content from the signature |
| Header line | name: value; multi-line text, lists ( - item) and maps ( key: value) follow name: on indented lines and may nest |
| Values | every scalar is a string. revision, format and body-length are decimal strings without leading zeros; times are RFC 3339 |
| Meta headers | type, format, authority-id, revision, body-length, sign-key-sha3-384 |
| Header order when signing | type, format (if above 0), authority-id, revision (if above 0), the primary key headers, the other headers sorted by name, body-length, sign-key-sha3-384 |
| Primary key | non-empty, no /; on disk each value is URL-escaped into a directory name. An optional primary key such as provenance is left out when it has its default value |
| Size limits | body 2 MiB, headers 128 KiB, signature 128 KiB |
| Signature | base64 of the byte 0x01 followed by an OpenPGP signature packet, wrapped at 76 columns; SHA-512 digest; RSA keys |
| Key ID | SHA3-384 of 0x01 and the public key packet, in unpadded base64url |
| Built-in assertions | the signature is the literal $builtin and there is no sign-key-sha3-384 |
| JSON body | only confdb-schema requires one, indented by two spaces with keys sorted |
Highest format snapd understands: snap-declaration 7, system-user 2, account-key 1, every other type 0. An assertion in a newer format is decoded but not accepted: proposed "<type>" assertion has format <n> but <m> is latest supported.
for app developers for Ubuntu Core developers for snapd developers for administrators
Types without an authority
Five types have no authority-id and do not lead back to the root key:
| Type | Signed by |
|---|---|
account-key-request | the key it asks the store to certify |
serial-request | the new device key it asks a serial for |
device-session-request | the device key named in the serial |
confdb-control | the device key named in the serial |
response-message | the device key named in the serial |
repair assertions are checked by snap-repair against its own repair-root key, not against snapd's roots.
for app developers for Ubuntu Core developers for snapd developers for administrators
What is checked when an assertion is added
In order, for a type with an authority:
1. The format is supported. 2. The signing key is found: trusted, then predefined, then disk. 3. The key is valid now: assertion is signed with expired public key .... 4. authority-id equals the key's account-id, the key's constraints allow the headers, and the signature verifies. 5. The assertion's timestamp lies within the key's validity: <type> assertion timestamp "<t>" outside of signing key validity .... 6. The type's own consistency check, for example that its prerequisites are stored. 7. The primary key does not clash with a trusted or predefined assertion. 8. The revision is higher than the stored one.
Nothing is checked again when an assertion is read.
for app developers for Ubuntu Core developers for snapd developers for administrators
The database on disk
| Item | Value |
|---|---|
| Directory | /var/lib/snapd/assertions |
| Assertions | asserts-v0/<type>/<primary key values>/active, or active.<format> for a format above 0 |
| Non-default optional key | an extra path component 0:<value> |
| Device keys | private-keys-v1/ |
| Search order | trusted (in memory), predefined (in memory), disk |
| Built in, trusted | the canonical account; the canonical root account-key, revision 2, since 2016-04-01, no until |
| Built in, not trusted | the generic account, its models account-key and the generic-classic model; the base-declaration; the system confdb-schema |
Deleting files under asserts-v0 by hand bypasses every check.
for app developers for Ubuntu Core developers for snapd developers for administrators
Revisions
| You add | Result |
|---|---|
| a higher revision | replaces the stored one |
| the same revision | no change; snap ack succeeds |
| an older revision | no change; snap ack succeeds |
| a newer format, with an older one stored | stored beside it; an older snapd keeps reading the format it understands |
| a store copy of a built-in assertion | refused: cannot add "<type>" assertion with primary key clashing with a trusted assertion (or a predefined assertion) |
A snap-declaration with an empty snap-name is revoked; installing that snap fails with cannot install snap "<name>" with a revoked snap declaration.
Three ways to install a file
snap install <name> | snap ack then snap install ./<file>.snap | snap install --dangerous ./<file>.snap | |
|---|---|---|---|
| Assertions | fetched from the store and checked | read from the local database only | none |
| Revision | store revision | store revision | local, x1, x2 and so on |
| Publisher | shown | shown | - |
| Interface rules of the snap-declaration | apply | apply | do not apply; only the minimal installation check |
| Refreshes from the store | yes | yes | no |
| Error without assertions | — | cannot find signatures with metadata for snap/component "<file>" | — |
--devmode looks the assertions up and, when none are found, installs like --dangerous.
for snapd developers
Inside snapd
| Step | Where |
|---|---|
validate-snap added after download-snap, summary Fetch and check assertions for snap "<name>" | overlord/snapstate/snapstate.go |
hash the file, fetch the snap-revision and its prerequisites, CrossCheck, provenance check; no undo handler | overlord/assertstate/assertmgr.go |
| the state lock is released around the network fetch only | overlord/assertstate/helpers.go |
POST /v2/assertions: decode into a Batch, precheck in a stacked database, commit in prerequisite order | daemon/api_asserts.go, asserts/batch.go |
DeriveSideInfo for a file install | daemon/api_sideload_n_try.go, asserts/snapasserts |
| auto-refresh of assertions: snap-declarations, then validation sets, then confdb schemas | overlord/assertstate/assertstate.go |
Messages you may meet
| Message | Meaning |
|---|---|
cannot find signatures with metadata for snap/component "<file>" | install of a file whose snap-revision is not stored; run snap ack first or use --dangerous |
cannot resolve prerequisite assertion: ... | snap ack of a file that lacks a statement it depends on |
cannot verify snap "<name>", no matching signatures found | the store has no snap-revision for the downloaded file |
assertion is signed with expired public key ... | the signing key's validity has ended, or the clock is wrong |
cannot query remote assertion: must provide primary key: ... | snap known --remote needs every primary key header |
Further reading
- Assertions: the format, the list of types and
snap knownwith example output. - Assertions reference: one page per type, with every header and an example.
- account-key: the fields of the key assertion that every signature is checked against.
- snap-revision: the statement that ties a file's hash to a revision.
Roads from here
START HERE
- Why snaps — why the publisher owns the package
GETTING SNAPS
- The store — the store that sends assertions with every snap
INTERFACES AND CONFINEMENT
- How interfaces are implemented — the declarations as interface policy and what --dangerous skips there
RUNNING SNAPS
- The overlord — validate-snap is a task in the install change
ASSERTIONS · signed statements snapd trusts
- Assertions: identity and store — accounts and keys and how a developer gets a key the store accepts
- Assertions: snaps and validation — the snap-declaration and snap-revision behind every install and validation sets
- Assertions: devices — the model and serial and who may sign for a device
- Assertions: confdb and messages — confdb schemas and remote management messages