Assertions: identity and store

assertion group for users for app developers for Ubuntu Core developers for snapd developers for administrators

account names a publisher and carries the validation behind the store badge; account-key binds a public key to an account for a validity window and is always issued by Canonical; account-key-request is how a developer asks for one; store describes a brand or proxy store; snap-developer lists collaborators; the base-declaration is built into snapd and is neither signed nor fetched.

On the map: assertions district

▶ Watch this deck — 8 scenes, ~6 min

01 Accounts come first for app developers for Ubuntu Core developers for snapd developers for administrators

IDENTITY AND STORE accountexample · Example Studio signed by Canonical onlyaccount-keya key belongs to an account storenames the account that runs it snap-developerwho may work on a snap account-key-requestsigned by the key it asks forbase-declarationbuilt into snapd, not signed account missing: the statement is refused, not fetched by the database
The account example at the centre; account-key, store and snap-developer point to it; account, account-key and store are signed by Canonical only; account-key-request is self-signed and base-declaration is built into snapd

An account names a publisher, brand or operator. account, account-key and store are signed by Canonical, and keys and stores need their account first. snap-developer is signed by the publisher, account-key-request by its own key; the base-declaration is built in.

Before snapd believes anything about photo editor, it needs to know who example is. That's an account: an ID, a display name, and how far the store vouches for that name. Accounts, account-keys and stores must be signed by a directly trusted authority, which in production is Canonical. A key or a store also needs its account stored first. A snap developer, signed by the publisher, lists who may work on its snap. Two types differ: an account-key-request is signed by the key it asks for, and the base declaration is built into snapd. A statement whose account is missing is refused, not fetched.

02 Where the publisher badge comes from for users for administrators for app developers

THE BADGE $ snap listName Rev Publishercore24 1055 canonical✓photo-editor 42 exampleexample output (abbreviated) account assertionsigned by the store,kept by snapd the account saysshown asunicode off verified✓ green tick** anything elseno badge starred✪ yellow star* installed with --dangerous:publisher - snap find: the badge comesfrom the store's search answer
snap list shows core24 from canonical with a green tick and photo-editor from example with no badge; the badge comes from the store's signed account assertion for the publisher; verified prints a green tick, starred a yellow star, anything else nothing; --dangerous snaps show a dash and snap find takes the badge from the store's answer

verified prints ✓ (or **), starred prints ✪ (or *), anything else no badge. Installed snaps take it from the publisher's account assertion; --dangerous snaps show -; snap find uses the store's answer.

In snap list, some publishers have a tick next to them. Who puts it there? It comes from the account assertion for that publisher, which the store signs and snapd keeps. Canonical's account says certified, which snapd treats as verified, so core24 shows a green tick. The example account says neither verified nor starred, so photo editor's publisher shows no badge. Starred would print a yellow star. Turn unicode off and they print as two stars and one star. A snap installed with --dangerous has no publisher, so you see a dash. Snap find is the exception: there the badge comes from the store's search answer.

03 What an account-key states for app developers for Ubuntu Core developers for snapd developers for administrators

ACCOUNT-KEY type: account-key authority-id: canonical public-key-sha3-384: kq2F… account-id: example name: default since: 2026-03-02T10:00:00Z body-length: 717 sign-key-sha3-384: BWDE… AcbBTQRWhcGAARAA… … the rest of the key, then the signature illustrative: IDs and signature cut ← the public key← primary key: must equal the ID of the key in the body ← whose key← which one: a second key with this name is refused ← valid from; no until here, so it does not expire constraints:format 1: which types and header values this key may signoptional; each entry is a map of headers with a literal type ← the signer: canonical, as for every account-keyonly a directly trusted authority may sign an account-key
An illustrative account-key assertion for the example account, signed by canonical, with its public-key-sha3-384, account-id, name and since headers labelled, the public key in the body, and an optional constraints header that limits what it may sign

public-key-sha3-384 identifies the key in the body; account-id and name say whose; since and until bound it. Optional constraints limit what it may sign. Illustrative: IDs, body and signature are cut.

Here's an account-key for the example account, the key its own statements are signed with. The public key sits in the body. The primary key is that key's SHA3-384, and the two must match. account-id and name say whose key it is and which one, and a second key with the same name is refused. Since and until bound when it's valid. Leave until out, and it doesn't expire. An optional constraints list, which needs format one, limits the types and header values the key may sign. And look at the signer: Canonical. In production every account-key is signed by Canonical.

04 Expired keys block only new assertions for Ubuntu Core developers for app developers for snapd developers for administrators

KEY VALIDITY key valid: since ≤ t < untilsinceuntil revision 42 added: stored ✓checked now: key valid, signer matches timestamp before sincetimestamp outside of signing key validity 42 still in uselookups do no time check new or refreshed, after untilassertion is signed with expired public key seeding: the newest timestamp in the seed is taken as the earliest time, not the clockelsewhere a device with a wrong clock can still report an expired key
A timeline of a signing key's validity window: photo-editor revision 42's statements, added inside it, stay in use after the key expires; a statement timestamped before since and a new statement added after until are refused; seeding takes the newest timestamp in the seed as the earliest time

Validity is checked when an assertion is added, not when it is read. Stored assertions survive expiry; new ones signed by an expired key are refused. The assertion's own timestamp must also fall inside the key's window.

Say the key that signed photo editor's statements reaches its until. Does revision 42 stop working? No. Three checks run when an assertion is added: the signing key must be valid now, the assertion's own timestamp must fall inside the key's window, and the signer must match the key's account and constraints. Nothing checks stored assertions again, so 42 keeps working. A new or refreshed statement signed by that key is refused, though, so rotate a key before its until. Seeding doesn't trust the clock: it takes the newest timestamp in the seed as the earliest possible time. Elsewhere, a wrong clock can still report an expired key.

05 Getting a key the store will accept for app developers for Ubuntu Core developers

YOUR OWN KEY $ snap create-key my-keyPassphrase:$ snap keysName SHA3-384my-key <sha3-384 of the key>by default in ~/.snap/gnupg,not in snapd's database $ snap export-key --account=example my-keyaccount-key-requestsigned by my-key itselfno authority-id · since = now storeregistered via snapcraftaccount-keysigned by canonical $ snap sign -k my-key set.json > set.assertfetches your account-key from the store to check its constraints--chainappends the account-key and account, for checking offline "revision": 1 → "revision" header is not an integer: 1"revision": "1" → every scalar is a string
snap create-key makes a local key, snap export-key --account prints a self-signed account-key-request, the store issues an account-key signed by canonical, and snap sign signs a JSON statement whose scalar values must be strings

snap create-key, then snap export-key --account=example prints an account-key-request; the store issues the account-key after snapcraft register-key. snap sign [-k key] [--chain] signs JSON whose scalar values are all strings.

Example Studio wants to sign its own statements. Where does the key come from? Your signing keys live in your home directory, not in snapd's database. snap create-key makes one. snap export-key, given the account example, prints an account-key-request, signed by that same key to prove you hold it. The store certifies it once you register the key with snapcraft, and issues an account-key signed by Canonical. Then snap sign reads a JSON statement, checks it against your key's constraints, and prints the assertion. The --chain option appends the key and the account. One trap: every single value in the JSON is a string.

06 The store assertion for Ubuntu Core developers for administrators for snapd developers

STORE a laptop on the default store needs no store assertion store: <store-id>operator-id: <account-id>url: https://…friendly-stores: <store-id> …location: …signed by canonical; the operator's account is required modelstore: <store-id>must match $ snap set system proxy.store=<store-id>cannot set proxy.store to "<store-id>" without a matching store assertion… with a matching store assertion with url unset on-store rules in snap-declarationsalso accept the friendly stores fetched with store installs when the model names a store; it can also be acked
The store assertion's headers, the proxy.store setting that needs it, and on-store rules, for which it must match the model's store and its friendly-stores also match

store names a store, its operator-id, its url and its friendly-stores. proxy.store requires a matching store assertion with a url. For on-store rules it must match the model's store, and friendly stores also match.

Photo editor came from the default store, and your laptop needs nothing more. A device that uses a different store does. The store assertion names that store, the account that operates it, its address, and its friendly stores. It must be signed by Canonical, because it changes where snapd connects and how policy is judged. Setting proxy.store needs a matching store assertion with an address, or snapd refuses. When a declaration has an on-store rule, the store assertion must match the model's store, and its friendly stores count as matches too. Snapd fetches it with store installs when the model names a store, or an admin acks it.

07 The base-declaration is built in for app developers for Ubuntu Core developers for snapd developers for administrators

BASE-DECLARATION networkhomesnapd-control… base-declarationbuilt at startup: revision 0 $ snap debug base-declarationtype: base-declarationauthority-id: canonicalseries: 16revision: 0plugs:…$builtin← the signature: a marker a copy from the storeprimary key clashing with a predefined assertionit changes only with a new snapd photo-editor's snap-declaration: for that snapbase-declaration: built in, for every snaphow the rules combine:How interfaces are implemented
Interface code is assembled into the base-declaration at startup with revision 0 and the literal signature $builtin; a store copy is refused; a snap-declaration from the store can replace a rule for one snap

Built from interface code at startup, revision 0, signature $builtin. A store copy is refused. Print it with snap debug base-declaration; a snap's snap-declaration can replace the rule for an interface for that snap.

Photo editor plugs into the home interface. Which rule says that's allowed? First, the base declaration. Every interface in snapd brings its default plug and slot rules, and snapd assembles them into the base declaration when it starts. It has no signature, only the literal $builtin marker where one would be. A copy from the store would clash with the built-in primary key and is refused, so the base declaration changes only when snapd does. snap debug base-declaration prints it. Photo editor's own snap-declaration, from the store, can replace the rule for an interface for that one snap. How interfaces are implemented shows how the two combine.

08 Where to go from here

ROADS Assertions: howthey workchecking and storing Snapsthe snap-declaration Devicesbrand keys How interfaces areimplementeddeclaration rules Why snapsthe publisher owns it snapctl: device and systemsnapctl model snap debugbase-declaration and more
Roads from identity and store: the assertion mechanism, the snaps and devices decks, how interfaces are implemented, why snaps, snapctl device and system, and snap debug

Roads: how assertions work, snaps, devices, how interfaces are implemented, why snaps, snapctl model and the debug commands.

So behind the word example in snap list stand an account, a key that Canonical certified, and the rules that came with snapd. Here's where to go next. Assertions: how they work shows how any statement is checked and stored, and where the chain ends. The snaps deck covers the snap-declaration that names photo editor's publisher. The devices deck shows brand keys signing models and serials. How interfaces are implemented explains how the base declaration and snap-declarations decide connections. Why snaps explains why the publisher owns the package. And the snapctl and snap debug decks cover snapctl model and snap debug base-declaration.

Read more

Publisher badges

validation in the account assertionUnicodeWithout UnicodeColour
verified✓**green
starred✪*bright yellow
anything elsenonenone—
no publisher (--dangerous)--—
  • snap list and snap find show the account's username. snap info shows the display name, followed by the username in brackets when the two differ beyond case and dashes.
  • Installed snaps take the badge from the stored account assertion; snap find takes it from the store's search answer.
  • snapctl model appends ** or * to a verified or starred publisher.
  • snapd accepts any non-empty validation. The built-in canonical account says certified, which snapd reads as verified.
  • The only policy that reads validation is snap set system interface.x11.allow-auto-connection=verified; the option accepts true, false and verified, and exists for x11 only.

for app developers for Ubuntu Core developers for snapd developers for administrators

What each type needs first

TypeNeeds first
account—
account-keythe account
storethe operator's account
snap-developerthe snap-declaration, the publisher's and each developer's account
account-key-requestthe account
base-declaration—

for app developers for Ubuntu Core developers for snapd developers for administrators

Key validity

CheckWhenMessage
the key is valid now: since ≤ now < untiladding an assertionassertion is signed with expired public key "<id>" from "<account>": ...
the assertion's timestamp is inside the key's validityadding an assertion<type> assertion timestamp "<t>" outside of signing key validity ...
authority-id equals the key's account-idadding an assertion—
the headers match the key's constraintsadding an assertionassertion does not match signing constraints for public key ...
a second key with the same account-id and nameadding an account-keyrefused

No check runs when a stored assertion is read. During seeding, snapd takes the newest timestamp of the model and snaps in the seed as the earliest possible time instead of the clock.

for app developers for Ubuntu Core developers

Signing your own statements

StepCommandResult
1snap create-key [<name>]an RSA 4096 key in ~/.snap/gnupg (or $SNAP_GNUPG_HOME), or in an external key manager named by SNAPD_EXT_KEYMGR
2snap export-key --account=<account-id> [<name>]an account-key-request signed by that key, since set to now
3snapcraft register-key <name>the store issues an account-key signed by Canonical
4snap sign [-k <name>] [--chain] [--update-timestamp] <file.json>the signed assertion on standard output
  • snap sign fetches the account-key from the store to compare it with the constraints. When it cannot, it prints WARNING: could not fetch account-key to cross-check signed assertion with key constraints. and still signs, but --chain fails with cannot create assertion chain: ....
  • Write every scalar as a JSON string: "revision": 1 fails with "revision" header is not an integer: 1.
  • The pseudo-header body gives the assertion's body.

for Ubuntu Core developers for administrators for snapd developers

The store assertion

HeaderMeaning
storethe store ID, the primary key
operator-idthe account that operates it; required
urlthe address snapd connects to; http or https, with a host, no query or fragment
friendly-storesother store IDs that on-store rules also accept
locationoptional
SituationResult
snap set system proxy.store=<id> without a store assertion for <id>cannot set proxy.store to "<id>" without a matching store assertion
the store assertion has no urlcannot set proxy.store to "<id>" with a matching store assertion with url unset
the model names a storevalidate-snap fetches its store assertion with each store install
an on-store rule is checked with a store assertion whose store differs from the model'sstore assertion and model store must match

Further reading

  • account: every header of the account assertion, with an example.
  • account-key: the key assertion's fields and an example.
  • store: the store assertion's fields.

for app developers for Ubuntu Core developers

Further reading on signing

  • Sign the model: creating a key, registering it with snapcraft register-key and signing.
  • Brand accounts: the account behind a brand's keys and store.

Roads from here

START HERE

  • Why snaps — why the publisher owns the package

INTERFACES AND CONFINEMENT

SNAPCTL · the snap's API into snapd

ASSERTIONS · signed statements snapd trusts

TOOLS