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, the Snap Store and Brand stores 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.
These are the currently used assertion types:
snap-id
, its name, and the publisher, plus policy related to accessing privileged interfacesThe 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
type
, sign-key-sha3-384
and a signatureauthority-id
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.
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_945.assert
snap install gnome-calculator_945.snap
Assertions include a snap-sha3-384
hash value to ensure their integrity:
snap-sha3-384: j73cFx0pIMoX4U[...]
However, these hash values will appear different, depending on whether they were either downloaded from the Snap Store, such as with the snap download
command, or retrieved with via the snapd REST API.
This difference is because the Store uses hex-encoded byte arrays while the snapd REST API encodes hashes with with base64.
Developers can typically use hash-encoded values directly in their code, whereas base64 values will need to be decoded first, such as with the base64 command.
Last updated 1 year, 5 months ago.