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

▶ Watch this deck — 8 scenes, ~6 min

01 Signed statements snapd trusts

ASSERTIONS storephoto-editor 42 signed statements snapdcheck signatureassertion database Canonical root keybuilt into snapd identity and storeaccount · account-key · store snapssnap-declaration · snap-revision devicesmodel · serial · system-user confdb and messagesconfdb-schema · request-message install · connect · refresh · register: decisions read from the database
The store sends the photo-editor revision 42 file together with signed statements to snapd, which checks each signature, follows it back to a root key built into snapd, and stores it in the assertion database; four groups of assertion types are read from there for installs, connections, refreshes and registration

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

ON THE WIRE type: account authority-id: canonical account-id: canonical display-name: Canonical timestamp: 2016-04-01T00:00:00.0Z username: canonical validation: certified sign-key-sha3-384: -CvQKAwRQ5h3Ffn10FILJoEZUXOv6km9FwA80-Rcj-f-6jadQ89VRswHNiEB9Lxk AcLDXAQAAQoABgUCV7UYzwAKCRDUpVvql9g3IK7uH/4udqNOurx5WYVknzXdwekp0ovHCQJ0iBPw … 18 more lines ← type: which of the 26 kinds ← the signer← signing key ← primary key: no / allowed blank line: the headers end here (a body would sit between two blank lines)← signature: base64 of 0x01 + an OpenPGP packet, 76 columns every scalar is a string: in snap sign JSON write "revision": "1", not 1the stored bytes are the signed bytes: change one byte and the signature fails
The canonical account assertion compiled into snapd, with its type, signer, signing key, primary key and signature labelled

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

TRUST ROOTS snapd binary: directly trustedaccount canonicalroot account-keysigns itself store keysigned by canonical brand keysigned by canonical developer keysigned by canonical a key the brand signednot signed by a directly trusted authoritythe brand key still signs models and serials predefined, not trustedgeneric account and its models keybase-declarationmore in: Assertions: identity and store no setting adds a trusted key; only testing builds of snapd add a test root
snapd's binary contains the canonical account and the self-signed root account-key; store, brand and developer keys are all signed by Canonical; a key signed by a brand is refused; the generic account and base-declaration are built in but not trusted

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

THE CHAIN photo-editor_42.snapSHA3-384 of the filesnap-revisionsnap-sha3-384 = that hash · revision 42 snap-declarationaccount examplepublisher and developergrey line: needed first store account-keywhite line: signed by the fetcher1 prerequisites first2 then the signing key3 then save account canonicalroot account-key · built into snapd: the walk stops adding to the databasenever fetches
A chain from the photo-editor revision 42 file through its SHA3-384 hash to its snap-revision, the snap-declaration and the example account, then the store account-key that signed them, ending at the root account-key built into snapd; a side panel shows the fetcher's order and that adding to the database never fetches

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

THREE WAYS IN from the store$ snap install \photo-editorassertions fetched and checkedRev Publisher42 example file plus assertions$ snap download photo-editorInstall the snap with:snap ack photo-editor_42.assertsnap install photo-editor_42.snap $ snap install photo-editor_42.snapcannot find signatures withmetadata for snap/component … $ snap ack photo-editor_42.assert$ snap install photo-editor_42.snaprevision 42, publisher exampleack installs nothing and fetches nothing --dangerous$ snap install --dangerous \./photo-editor_42.snapRev Publisherx1 - no assertions, so:a local revisionno publisherno refreshes from the storeexample output · snap known <type> lists what snapd has stored
Three ways to install photo-editor: from the store with assertions fetched and checked; snap download, then snap ack, then snap install of the file, which gives store revision 42 and the publisher example; and --dangerous, which gives local revision x1, no publisher and no store refreshes

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

THREE WAYS IN storedownload-snapvalidate-snaprest of the install hash file · fetch snap-revision and prerequisites (unlocked for the fetch)CrossCheck: size, snap-id, revision · provenance snap acksnap ackPOST /v2/assertionsBatch: never fetches, commits in prerequisite ordercannot resolve prerequisite assertion snap install ./x.snapDeriveSideInfolocal lookup by hash · size checkstore revision and snap-id --dangerousunsafeReadSnapInfoSideInfo has only RealName: local revision, no snap-idifacestate: minimal installation check only --devmode tries DeriveSideInfo and falls back to the dangerous path · validate-snap has no undo: added assertions stay
Three lanes inside snapd: the store lane with download-snap and validate-snap; the ack lane with POST /v2/assertions, a prechecked batch and DeriveSideInfo; and the dangerous lane with unsafeReadSnapInfo and no snap-id

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

THE DATABASE /var/lib/snapd/assertions/asserts-v0/snap-declaration/16/<snap-id>/active …/active.Na revision in a newer format, stored beside the old one trusted (in memory)predefined (in memory)diskevery lookup, snap known included, searches the three in this order stored:revision 3 revision 4replaces it revision 3same: a no-op, so acking again succeeds revision 2older: also a no-op, the stored revision 3 stays no delete: revocation is a newer revision, for example a snap-declaration with an empty snap-namea primary key that clashes with a built-in assertion is refused
The assertion database on disk, the three backstores searched in order, and what happens to a higher, equal and older revision of a stored assertion

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

ROADS the types Identity and storeaccounts and keys Snapsdeclaration and revision Devicesmodel and serial Confdb and messagesschemas and messages neighboursWhy snapsthe publisher owns it How interfaces areimplementeddeclarations as policy The storewhere they come from The overlordvalidate-snap as a task
Roads from the assertions overview: four decks on assertion types and four neighbouring decks

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

PartRule
Layoutheaders, 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 linename: value; multi-line text, lists ( - item) and maps ( key: value) follow name: on indented lines and may nest
Valuesevery scalar is a string. revision, format and body-length are decimal strings without leading zeros; times are RFC 3339
Meta headerstype, format, authority-id, revision, body-length, sign-key-sha3-384
Header order when signingtype, 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 keynon-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 limitsbody 2 MiB, headers 128 KiB, signature 128 KiB
Signaturebase64 of the byte 0x01 followed by an OpenPGP signature packet, wrapped at 76 columns; SHA-512 digest; RSA keys
Key IDSHA3-384 of 0x01 and the public key packet, in unpadded base64url
Built-in assertionsthe signature is the literal $builtin and there is no sign-key-sha3-384
JSON bodyonly 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:

TypeSigned by
account-key-requestthe key it asks the store to certify
serial-requestthe new device key it asks a serial for
device-session-requestthe device key named in the serial
confdb-controlthe device key named in the serial
response-messagethe 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

ItemValue
Directory/var/lib/snapd/assertions
Assertionsasserts-v0/<type>/<primary key values>/active, or active.<format> for a format above 0
Non-default optional keyan extra path component 0:<value>
Device keysprivate-keys-v1/
Search ordertrusted (in memory), predefined (in memory), disk
Built in, trustedthe canonical account; the canonical root account-key, revision 2, since 2016-04-01, no until
Built in, not trustedthe 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 addResult
a higher revisionreplaces the stored one
the same revisionno change; snap ack succeeds
an older revisionno change; snap ack succeeds
a newer format, with an older one storedstored beside it; an older snapd keeps reading the format it understands
a store copy of a built-in assertionrefused: 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>.snapsnap install --dangerous ./<file>.snap
Assertionsfetched from the store and checkedread from the local database onlynone
Revisionstore revisionstore revisionlocal, x1, x2 and so on
Publishershownshown-
Interface rules of the snap-declarationapplyapplydo not apply; only the minimal installation check
Refreshes from the storeyesyesno
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

StepWhere
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 handleroverlord/assertstate/assertmgr.go
the state lock is released around the network fetch onlyoverlord/assertstate/helpers.go
POST /v2/assertions: decode into a Batch, precheck in a stacked database, commit in prerequisite orderdaemon/api_asserts.go, asserts/batch.go
DeriveSideInfo for a file installdaemon/api_sideload_n_try.go, asserts/snapasserts
auto-refresh of assertions: snap-declarations, then validation sets, then confdb schemasoverlord/assertstate/assertstate.go

Messages you may meet

MessageMeaning
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 foundthe 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 known with 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

RUNNING SNAPS

  • The overlord — validate-snap is a task in the install change

ASSERTIONS · signed statements snapd trusts