Assertions

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 type, sign-key-sha3-384 and a signature
  • most assertions have authority-id
  • 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.

Assertion types

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

Viewing assertions

The 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
[...]

Last updated 2 years ago.

Help improve this document in the forum.