Assertions: snaps and validation
assertion group for app developers for snapd developers for administrators
snap-declaration binds a snap-id to its name and publisher and carries per-snap policy; snap-revision ties a file's SHA3-384 and size to a revision number; snap-resource-revision and snap-resource-pair do the same for components; validation-set lets an account constrain which snaps and revisions belong together and only enforce mode constrains anything.
On the map: assertions district
01 A snap is bound twice
snap-declaration: snap-id, name, publisher and policy. snap-revision: a file's hash and size to a revision of that snap-id. snap-resource-revision and snap-resource-pair: the same for components. validation-set: an account's list of snaps and revisions that belong together.
The gateway is about to run acme-agent revision 42. Two store signatures stand behind that. The snap-declaration says which name and publisher acme-agent's snap-id has, and carries its per snap policy. The snap-revision says that a file with this hash and size is revision 42 of that snap-id. Bound twice, then: by name and by bytes. Components get the same kind of revision statement, plus a pair that ties each component revision to a snap-revision. And a validation set, which any account can sign for itself, says which snaps and revisions belong together. This deck takes them in that order.
02 The snap-declaration for app developers for snapd developers for administrators
Keyed by series and snap-id; names snap-name and publisher-id; may carry plugs, slots, aliases and revision-authority. A rule here replaces the base-declaration's rule for that interface. Illustrative: IDs and signature are cut.
Here's what the store says about acme-agent. Only a directly trusted signer, the store, may issue a snap-declaration. Its primary key is the series and the snap-id, so a rename changes only the snap name. publisher-id names the owner, acme. If the name no longer matches, installing under the old name is refused. Plugs and slots hold rules for this one snap, and a rule here is used instead of the base declaration's rule for that interface. So the store can let the agent's network-control plug connect automatically, which the base declaration denies. Aliases are automatic aliases, and revision-authority lets other accounts sign revisions.
03 What the download check compares for app developers for snapd developers for administrators
The file's SHA3-384 finds the snap-revision; snap-size, snap-id and snap-revision must match, and so must the provenance in snap.yaml. The default provenance global-upload must be signed by the store. Illustrative: hash and IDs are cut.
The gateway has just downloaded acme-agent 42. Before it's mounted, validate-snap hashes the file with SHA3-384. That hash, with the provenance, is the primary key of the snap-revision, fetched next. The revision states how large the file must be, which snap-id it belongs to and which revision it is, and its provenance must match the one in snap.yaml. No revision fails the task with no matching signatures found. A mismatch says the download or the metadata is broken or tampered. With the default provenance, global-upload, only the store may sign. The same check lets an acked file install with its store revision.
04 Revisions signed outside the store for app developers for snapd developers
revision-authority lets account-id sign revisions for the listed provenance values within min-revision and max-revision, optionally only on-store, on-brand or on-model. The provenance in snap.yaml must match. Illustrative.
Acme builds some agent revisions in its own lab, only for its own gateways. Does the store have to sign those? No. A snap-declaration can delegate signing with revision-authority. Each entry names an account, the provenances it may sign for, an optional revision range, and optionally the stores, brands or models where it holds. acme-agent's snap.yaml names its provenance, and the revision must carry the same one. A revision outside the delegation is refused. A revision that's valid elsewhere but not on this device is refused on this device. And the default provenance, global-upload, can't be written in snap.yaml at all.
05 A component needs a pair for app developers for snapd developers
snap-resource-revision checks the component file's hash, size and revision; snap-resource-pair must link that component revision to the snap revision, or the component is refused. Signers as for snap-revision.
acme-agent ships an optional diagnostics component. A component has its own revision statement, the snap-resource-revision, keyed by snap-id, component name, hash and provenance. The component file is checked for size and revision, just as the snap file is. Then a second statement, the snap-resource-pair, has to tie that component revision to the revision of the snap it'll run with. Diagnostics revision 3 is valid on its own. With agent 42 there's a pair, so it installs. With agent 43 there isn't, so it's refused. Who may sign follows the same rules as for snap revisions.
06 Only enforce constrains for administrators for app developers for snapd developers
A validation-set is signed by its account-id and keyed by series, account, name and sequence. Each snap is required, optional or invalid, with an optional revision. --monitor reports; --enforce constrains and is refused unless the set is met (or --refresh is given).
Here's acme's gateway set as an assertion. Acme signs it, and the signer must be the account that owns the set. Its primary key ends in a sequence number, so a changed set is the next sequence. Each snap has a presence, required by default, optional or invalid, and maybe a revision, which an invalid snap can't carry. Give a snap a revision, and its components need revisions too. A device tracks a set in one of two modes. Monitor only reports, and blocks nothing. Enforce constrains, and it's refused unless the gateway already satisfies the set. Add the --refresh, and snapd installs or refreshes what's needed first.
07 What enforcing refuses for administrators for app developers for snapd developers
Enforcing refuses invalid snaps, other revisions and the removal of required snaps, and steers refreshes to the required revision. --ignore-validation overrides it per snap and is remembered. snap validate --forget is refused for a set the model lists with mode enforce.
With the gateway-set enforced, here's what snapd refuses. Installing the old VPN snap, which the set marks invalid, fails, and the error names the set and its sequence. Removing the agent, which the set requires, fails too. On a refresh, snapd asks the store for the revision the sets require, and leaves the channel and cohort out of the request. A revision the sets don't allow needs --ignore-validation, and snapd remembers that choice for the snap on later refreshes of everything. Parallel instances aren't constrained. snap validate --forget stops enforcing, unless the gateway's model lists the set with mode enforce. Then forgetting is refused.
08 Where to go from here
Roads: validation sets, how assertions work, identity and store, how interfaces are implemented, refresh, devices, snap packaging and the store.
So acme-agent 42 is bound by name and by bytes, and a validation set can hold it to what was tested. Here's where to go next. Validation sets: snaps that belong together explains why a set is worth its cost. Assertions: how they work covers how this chain is fetched and the three ways to install a file. Identity and store covers the accounts and keys that sign it all. How interfaces are implemented shows how a declaration's rules are judged. Refresh shows sets steering a refresh. And the devices, snap packaging and store decks cover the model, components and the store that signs revisions.
Read more
What the download check compares
validate-snap runs after download-snap and before the snap is mounted. It has no undo.
| Check | Failure |
|---|---|
a snap-revision exists for the file's SHA3-384 and expected provenance | cannot verify snap "<name>", no matching signatures found |
snap-size equals the file size | snap "<name>" file does not have expected size according to signatures (download is broken or tampered): <size> != <size> |
snap-id and snap-revision equal what the store said | snap "<name>" does not have expected ID or revision according to assertions (metadata is broken or tampered): ... |
the snap-declaration still has the expected name | cannot install "<name>", snap "<name>" is undergoing a rename to "<new name>" |
the snap-declaration is not revoked (empty snap-name) | cannot install snap "<name>" with a revoked snap declaration |
| a non-default provenance is allowed on this device | snap "<name>" revision assertion with provenance "<p>" is not signed by an authority authorized on this device: <signer> |
| the provenance in snap.yaml equals the assertion's | snap "<file>" has been signed under provenance "<p>" different from the metadata one: "<q>" |
A component goes through validate-component with the same checks against its snap-resource-revision, and then needs a snap-resource-pair for the snap revision: cannot find snap-resource-pair for <component>: ....
Who may sign a revision
| Provenance | Signer of snap-revision, snap-resource-revision and snap-resource-pair |
|---|---|
global-upload (the default, left out of the assertion) | a directly trusted authority: the store |
| any other value | an account listed in the snap-declaration's revision-authority for that provenance |
revision-authority entries:
| Key | Meaning |
|---|---|
account-id | the account allowed to sign |
provenance | a non-empty list of provenances it may sign for |
min-revision | the lowest revision; default 1 |
max-revision | the highest revision; optional |
on-store, on-brand, on-model | limits the delegation to devices of those stores, brands or models (<brand>/<model>) |
A provenance matches ^[a-zA-Z0-9](?:-?[a-zA-Z0-9])*$. snap.yaml cannot name global-upload explicitly: provenance cannot be set to default (global-upload) explicitly.
snap validate
| Command | Effect |
|---|---|
snap validate | lists tracked sets: Validation, Mode, Seq, Current |
snap validate <account>/<name>[=<seq>] | prints valid or invalid |
snap validate --monitor <account>/<name>[=<seq>] | tracks the set and reports; blocks nothing |
snap validate --enforce <account>/<name>[=<seq>] | enforces the set; refused unless it is already met |
snap validate --enforce --refresh <account>/<name> | installs or refreshes snaps to meet the set, then enforces it |
snap validate --forget <account>/<name> | stops tracking the set |
=<seq> pins that sequence; without it the set follows new sequences. --refresh is accepted only with --enforce: --refresh can only be used together with --enforce. A sequence other than the one the model pins fails with only sequence <n> allowed by model.
What an enforced set does
| Action | Result |
|---|---|
install a snap the set marks invalid | cannot install snap "<name>" due to enforcing rules of validation set <series>/<account>/<name>/<seq> |
| install or refresh to another revision than the one required | cannot <install or update> snap "<name>" <...> revision <r> without --ignore-validation, revision <q> is required by validation sets: <sets> |
| remove a required snap | snap "<name>" is required by validation sets: <sets> or snap "<name>" at revision <r> is required by validation sets: <sets> |
| refresh | the store is asked for the required revision; channel and cohort are left out |
--ignore-validation | the snap is installed or refreshed anyway, and later refreshes of all snaps keep ignoring the sets for it |
| parallel instance of a snap | not constrained |
snap validate --forget for a set the model lists with mode: enforce | validation-set is enforced by the model; a prefer-enforce set can be forgotten |
Monitor mode changes none of these. Auto-refresh fetches new sequences of tracked sets first; a new sequence of an enforced set that installed snaps would not meet is not applied and is logged.
for snapd developers
State
| Key | Content |
|---|---|
validation-sets | one entry per <account>/<name>: mode, pinned sequence, current sequence, local-only |
validation-sets-history | the last 50 states of the tracked sets, used to restore them when a change is undone |
The older validation assertion
A snap-declaration may list snap IDs in refresh-control. A refresh of such a snap then needs a validation assertion signed by the gating snap's publisher for the new revision: no validation by "<snap>", or cannot refresh "<snap>" to revision <r>: validation by "<snap>" (id "<id>") revoked. --ignore-validation skips this check too.
Further reading
- Validation sets: what a set is for and its limits.
- Manage validation sets: creating, signing and enforcing a set with commands.
- snap-declaration: every header, including
revision-authority. - snap-revision: the revision statement's fields.
- validation-set: the assertion format with an example.
- Using components: installing and refreshing components.
Roads from here
GETTING SNAPS
- Snap packaging — revisions and components of the snap file
- The store — the store that signs revisions
INTERFACES AND CONFINEMENT
- How interfaces are implemented — the plugs and slots rules of a snap-declaration as interface policy
RUNNING SNAPS
- Refresh — refreshes steered or refused by validation sets
ASSERTIONS · signed statements snapd trusts
- Assertions: how they work — how the chain is fetched and the three ways to install a file
- Assertions: identity and store — the accounts and keys that sign these
- Assertions: devices — the model and serial and who signs for a device
- Validation sets: snaps that belong together — why validation sets exist