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

▶ Watch this deck — 8 scenes, ~6 min

01 A snap is bound twice

SNAPS AND VALIDATION snap-declarationsnap-id ↔ snap-name ↔ publisher-id+ per-snap policysigned by the store snap-idsnap-revisionsha3-384 + size → snap-id, revision 42signed by the storeacme-agent_42.snap snap-resource-revisionsnap-resource-pairthe same for components validation-setaccount-id/name, sequence Neach snap: required · optionalor invalid, optionally a revisionsigned by any account, for itself bound by name and by bytes
For acme-agent revision 42: a snap-declaration binds snap-id to name and publisher, a snap-revision binds a file's hash and size to a revision of that snap-id, components have a resource revision and pair, and a validation-set lists what belongs together

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

SNAP-DECLARATION type: snap-declaration authority-id: canonical series: 16 snap-id: Xq7d… snap-name: acme-agent publisher-id: acme plugs: network-control: allow-auto-connection: true timestamp: … sign-key-sha3-384: … illustrative: IDs and signature cut ← only a directly trusted signer ← primary key: series + snap-ida rename changes only snap-name ← the name and its owner accountcannot install "x", snap "x" is undergoing a rename to "y" ← a rule for this snap onlyused instead of the base-declaration's rule base-declaration: network-control slots deny-auto-connection aliasesautomatic aliasesrevision-authoritywho else signs revisionsrefresh-contrololder refresh gating
An illustrative snap-declaration for acme-agent signed by canonical, with labels for its signer, its primary key of series and snap-id, its name and publisher acme, a plugs rule that lets the network-control plug auto-connect, and the other optional policy headers

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

VALIDATE-SNAP download-snapvalidate-snapFetch and check assertions for snap "acme-agent" acme-agent_42.snapSHA3-384 type: snap-revisionauthority-id: canonicalsnap-sha3-384: <file hash>snap-id: Xq7d…snap-size: 4096000snap-revision: 42developer-id: acmeillustrative: hash, ID and signature cut ✓ snap-size = file size✓ snap-id = expected✓ snap-revision = expected✓ provenance = snap.yaml cannot verify snap "acme-agent", no matching signatures foundsnap "acme-agent" file does not have expected size according to signatures (download is broken or tampered)snap "acme-agent" does not have expected ID or revision according to assertions (metadata is broken or tampered) default provenance global-upload: the signer must be the store snap ack of the same snap-revision lets a local file install with its store revision
validate-snap hashes the downloaded acme-agent revision 42 file, finds the snap-revision with that hash and checks size, snap-id, revision and provenance; a missing revision and mismatches fail with their errors; the default provenance must be signed by the store

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

PROVENANCE revision-authority:-account-id: acmeprovenance:- acme-labmin-revision: 100on-model:- acme/acme-gatewayillustrative: part of acme-agent's snap-declaration snap.yaml provenance: acme-labsnap-revisionprovenance acme-lab · signed by acmesnap-revision: 150 ✓ the signer is the listed account-id✓ acme-lab is a listed provenance✓ 150 ≥ 100, no max-revision✓ this device is an acme-gateway … is not signed by an authorized authorityoutside the list or the range … is not signed by an authority authorized on this devicewrong store, brand or model global-upload cannot be set explicitly in snap.yaml
An illustrative revision-authority entry in acme-agent's snap-declaration lets the account acme sign revisions with provenance acme-lab from revision 100, only on the acme-gateway model; a snap-revision with provenance acme-lab at revision 150 matches it; revisions outside the delegation, or on another device, are refused

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

COMPONENTS acme-agent+diagnosticsSHA3-384snap-resource-revisionsnap-id · resource-name: diagnostics · sha3-384 · sizeresource-revision: 3 acme-agent, revision 42snap-resource-pairdiagnostics 3 works with acme-agent 42 acme-agent, revision 43cannot find snap-resource-pair for diagnosticsno pair for revision 43: the component is refused signer rules as for snap-revision: the store for global-upload, otherwise a matching revision-authority
The acme-agent+diagnostics component file is checked against its snap-resource-revision, and a snap-resource-pair must link that component revision to the installed snap revision; without a pair it is refused

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

VALIDATION-SET type: validation-setauthority-id: acmeseries: 16account-id: acmename: gateway-setsequence: 3snaps: - name: acme-agentid: …revision: 41 - name: acme-diagpresence: optionalrevision: 5 - name: acme-legacy-vpnpresence: invalid… signatureillustrative: IDs and signature cut ← a change is the next sequence no presence: requiredinvalid: no revisionwith a revision, components need one $ snap validate --monitor \acme/gateway-setinvalidmonitor: reports only, nothing is blocked $ snap validate --enforce \acme/gateway-setcannot enforce validation set:validation sets assertions are not met: … $ snap validate --enforce --refresh \acme/gateway-setinstalls or refreshes what is needed, then enforces
An illustrative validation-set assertion acme/gateway-set at sequence 3 signed by acme, listing acme-agent required at revision 41, acme-diag optional at revision 5 and acme-legacy-vpn invalid; snap validate --monitor only reports invalid, and --enforce is refused until the set is met unless --refresh is added

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

ENFORCED $ snap install acme-legacy-vpncannot install snap "acme-legacy-vpn" due to enforcing rules of validation set 16/acme/gateway-set/3 $ snap remove acme-agent… snap "acme-agent" at revision 41 is required by validation sets: 16/acme/gateway-set/3 refresh: the store is asked for the revision the sets require; channel and cohort are left out a revision the sets do not allow needs --ignore-validation, remembered for that snap on later refresh-all parallel instances, such as acme-agent_test, are not constrained $ snap validate --forget acme/gateway-setstops enforcing the setvalidation-set is enforced by the modelwhen the model lists it with mode enforce
With acme/gateway-set enforced: installing acme-legacy-vpn, which the set marks invalid, fails; removing acme-agent, which the set requires at revision 41, fails; refreshes ask the store for the required revision without channel or cohort; --ignore-validation is remembered per snap; parallel instances are not constrained; snap validate --forget is refused for a set the model enforces

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 Snaps and validationValidation setswhy a set is worth it How assertions workfetching, three install paths Identity and storeaccounts and keys How interfaces areimplementeddeclaration rules judged Refreshsteered by sets Devicesthe model and serial Snap packagingrevisions and components The storesigns the revisions
Roads from snaps and validation: validation sets, how assertions work, identity and store, how interfaces are implemented, refresh, devices, snap packaging and the store

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.

CheckFailure
a snap-revision exists for the file's SHA3-384 and expected provenancecannot verify snap "<name>", no matching signatures found
snap-size equals the file sizesnap "<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 saidsnap "<name>" does not have expected ID or revision according to assertions (metadata is broken or tampered): ...
the snap-declaration still has the expected namecannot 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 devicesnap "<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'ssnap "<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

ProvenanceSigner 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 valuean account listed in the snap-declaration's revision-authority for that provenance

revision-authority entries:

KeyMeaning
account-idthe account allowed to sign
provenancea non-empty list of provenances it may sign for
min-revisionthe lowest revision; default 1
max-revisionthe highest revision; optional
on-store, on-brand, on-modellimits 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

CommandEffect
snap validatelists 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

ActionResult
install a snap the set marks invalidcannot install snap "<name>" due to enforcing rules of validation set <series>/<account>/<name>/<seq>
install or refresh to another revision than the one requiredcannot <install or update> snap "<name>" <...> revision <r> without --ignore-validation, revision <q> is required by validation sets: <sets>
remove a required snapsnap "<name>" is required by validation sets: <sets> or snap "<name>" at revision <r> is required by validation sets: <sets>
refreshthe store is asked for the required revision; channel and cohort are left out
--ignore-validationthe snap is installed or refreshed anyway, and later refreshes of all snaps keep ignoring the sets for it
parallel instance of a snapnot constrained
snap validate --forget for a set the model lists with mode: enforcevalidation-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

KeyContent
validation-setsone entry per <account>/<name>: mode, pinned sequence, current sequence, local-only
validation-sets-historythe 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

Roads from here

GETTING SNAPS

INTERFACES AND CONFINEMENT

RUNNING SNAPS

  • Refresh — refreshes steered or refused by validation sets

ASSERTIONS · signed statements snapd trusts