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
01 Accounts come first for app developers for Ubuntu Core developers for snapd developers for administrators
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
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
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
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
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 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
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: 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 assertion | Unicode | Without Unicode | Colour |
|---|---|---|---|
verified | ✓ | ** | green |
starred | ✪ | * | bright yellow |
| anything else | none | none | — |
no publisher (--dangerous) | - | - | — |
snap listandsnap findshow the account's username.snap infoshows 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 findtakes it from the store's search answer. snapctl modelappends**or*to a verified or starred publisher.- snapd accepts any non-empty
validation. The built-incanonicalaccount sayscertified, which snapd reads asverified. - The only policy that reads
validationissnap set system interface.x11.allow-auto-connection=verified; the option acceptstrue,falseandverified, and exists forx11only.
for app developers for Ubuntu Core developers for snapd developers for administrators
What each type needs first
| Type | Needs first |
|---|---|
account | — |
account-key | the account |
store | the operator's account |
snap-developer | the snap-declaration, the publisher's and each developer's account |
account-key-request | the account |
base-declaration | — |
for app developers for Ubuntu Core developers for snapd developers for administrators
Key validity
| Check | When | Message |
|---|---|---|
the key is valid now: since ≤ now < until | adding an assertion | assertion is signed with expired public key "<id>" from "<account>": ... |
the assertion's timestamp is inside the key's validity | adding an assertion | <type> assertion timestamp "<t>" outside of signing key validity ... |
authority-id equals the key's account-id | adding an assertion | — |
the headers match the key's constraints | adding an assertion | assertion does not match signing constraints for public key ... |
a second key with the same account-id and name | adding an account-key | refused |
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
| Step | Command | Result |
|---|---|---|
| 1 | snap 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 |
| 2 | snap export-key --account=<account-id> [<name>] | an account-key-request signed by that key, since set to now |
| 3 | snapcraft register-key <name> | the store issues an account-key signed by Canonical |
| 4 | snap sign [-k <name>] [--chain] [--update-timestamp] <file.json> | the signed assertion on standard output |
snap signfetches theaccount-keyfrom the store to compare it with the constraints. When it cannot, it printsWARNING: could not fetch account-key to cross-check signed assertion with key constraints.and still signs, but--chainfails withcannot create assertion chain: ....- Write every scalar as a JSON string:
"revision": 1fails with"revision" header is not an integer: 1. - The pseudo-header
bodygives the assertion's body.
for Ubuntu Core developers for administrators for snapd developers
The store assertion
| Header | Meaning |
|---|---|
store | the store ID, the primary key |
operator-id | the account that operates it; required |
url | the address snapd connects to; http or https, with a host, no query or fragment |
friendly-stores | other store IDs that on-store rules also accept |
location | optional |
| Situation | Result |
|---|---|
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 url | cannot set proxy.store to "<id>" with a matching store assertion with url unset |
| the model names a store | validate-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's | store 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-keyand 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
- How interfaces are implemented — how the base-declaration and snap-declarations decide connections
SNAPCTL · the snap's API into snapd
- snapctl: device and system — snapctl model and its publisher badge suffix
ASSERTIONS · signed statements snapd trusts
- Assertions: how they work — how any assertion is checked and stored
- Assertions: snaps and validation — the snap-declaration that names a snap's publisher
- Assertions: devices — brand keys signing models and serials
TOOLS
- snap debug: tools for looking inside — snap debug base-declaration and other debug commands