An assertion is a digitally signed document that either verifies the validity of a process, as attested by the signer, or carries policy information, as formulated by the signer.
Snapcraft, snapd and the Snap Store all use assertions to handle a variety of functions and processes, including authentication, policy setting, identification and validation.
Assertions are text-based and take a context-dependent format that always includes one or more headers, an optional body, and the encoded signature.
The typical format of an assertion, with common headers, is as follows:
type: <type> # For example, “account” or “model” authority-id: <account id> # On whose authority this assertion is made <key field 1>: <value> # Fields identifying the object of the assertion ... <key field N>: <value> <other field>: <value> ... revision: <int> # Assertions can be updated with a higher revision format: <int> # Assertion types can have backward incompatible format changes signaled by a higher format body-length: <int> # Present if a body is provided with this assertion sign-key-sha3-384: <key id> # Encoded key id of signing key <body> # Optional type-dependent body of length `body-length` bytes <signature> # Encoded signature
- every assertion has
sign-key-sha3-384and a signature
- most assertions have
- values are scalars (strings, integers, booleans), lists, or maps
- some headers are used as a unique index to specify the context of an assertion of the given, together they form the so-called primary key of the assertion
- most assertions also have a revision to enable a particular assertion to be updated by issuing another assertion of the same type and index with a higher revision.
Given a particular type and index, there is only one “latest” valid assertion that properly determines policy for a system - the one with the highest revision. For a given assertion, the index headers must all be defined.
These are the currently used assertion types:
- account: links an account name to its identifier and other properties
- account-key: holds the public part of a key belonging to the account
- model: brand-specified properties for the device, used to drive the building of an Ubuntu Core image
- serial: binds the device identity to the device’s key by carrying the public part
snap-declaration: defines various snap properties, such as
snap-id, its name, and the publisher, plus policy related to accessing privileged interfaces
- snap-revision: store acknowledgement on receipt of a snap build labelled with a revision
- system-user: usually brand authorisation to create local system users on specified devices
- validation: validates a specific snap revision for a given series
snap known <type> [<header>=<value>...] command can be used to view assertions or a specific type:
$ snap known account account-id=generic type: account authority-id: canonical account-id: generic display-name: Generic timestamp: 2017-07-27T00:00:00.0Z username: generic validation: certified sign-key-sha3-384: [...]
Similarly, a snap’s assertions are downloaded alongside the snap using the
snap download command:
$ snap download gnome-calculator Fetching snap "gnome-calculator" Fetching assertions for "gnome-calculator" Install the snap with: snap ack gnome-calculator_544.assert snap install gnome-calculator_544.snap $ cat gnome-calculator_544.assert type: account-key authority-id: canonical revision: 2 [...]