Assertions: confdb and messages
assertion group for Ubuntu Core developers for snapd developers
confdb-schema is an account's storage schema and views; confdb-control is signed by the device key and delegates views to operators; request-message carries an operator's request through the store and response-message carries the device-signed answer back. All of it is experimental and behind experimental.confdb and experimental.remote-device-management.
On the map: assertions district
01 Schema, control, message: three signers
confdb-schema by its account, confdb-control and response-message by the device key, request-message by an operator. Experimental: experimental.confdb and experimental.remote-device-management.
Acme keeps the gateway's proxy address in confdb. Now it wants to change that address on a gateway nobody can reach. Four assertion types make this work, with three signers. Acme, as an account, publishes the confdb-schema and its views. The gateway signs a confdb-control assertion, which says which operators may use which views. An operator sends a request-message, and it travels through the store. The gateway checks it, applies it, and answers with a response-message signed by its own key. All of this is experimental. It needs experimental.confdb, and remote management also needs experimental.remote-device-management.
02 A confdb-schema for Ubuntu Core developers for snapd developers
Illustrative. Signed by its account-id; views map request names to storage paths with an access mode; the JSON body holds the storage schema. Acked, or fetched when first needed; addressed as acme/gateway/proxy. Experimental.
Here's acme's gateway schema, cut down. A schema belongs to one account, and that account signs it. System schemas are the exception: Canonical signs those. The views are headers. Each rule maps a request name, such as host, to a storage path, with an access mode. Here one view only reads, and the other may write. The storage schema is the body, and confdb-schema is the only type whose body must be JSON. Snaps and commands address a view as account, schema and view. If a snap uses a view snapd doesn't have yet, snapd fetches the schema from the store, and newer revisions replace it on refresh.
03 Delegating views to operators for Ubuntu Core developers for snapd developers
Illustrative; acme-ops is invented. confdb-control is keyed by brand-id, model and serial and signed by the device key. POST /v2/confdb with delegate or undelegate re-signs it. Without one, messages are unauthorized. Experimental.
So who decides that acme's operations account may change the proxy? The gateway does. A confdb-control assertion has no authority-id. It's keyed by brand, model and serial, and signed by the key in that gateway's serial. It lists groups: operators, the views they may use, and how they must authenticate, with an operator-key or through the store. There's no snap command for it. It changes only on the device, through the confdb endpoint with delegate or undelegate, and each change is signed again at a higher revision. Signing one needs a serial in the strict format. Without a confdb-control, every incoming message is answered unauthorized.
04 The exchange with the store for snapd developers for Ubuntu Core developers
Experimental. Change device-management-exchange: exchange-mgmt-messages, dispatch-mgmt-messages, then per message validate-mgmt-message, apply-mgmt-message, queue-mgmt-response. Messages <id>-<n> run in order; a gap stops the sequence.
How does acme's request reach the gateway? The gateway asks for it. Every six hours the device management manager starts a change, device-management-exchange. Its first task sends any responses that are ready and fetches new requests from the store. The dispatch task then builds a chain for each message: validate, apply, queue the response. The next message in a sequence waits for the one before it, while other sequences run side by side. A gap in the numbering stops the chain until the missing message arrives. A message that's refused or fails still gets its answer, and the next one runs. Answers go back on the next exchange.
05 A request-message for snapd developers for Ubuntu Core developers
Illustrative. devices, valid-since and valid-until decide whether the message is for this device now. The confdb handler requires authority-id = account-id and an operator-key delegation; assumes is not checked yet. Experimental.
Here's a request from acme's operations account. It's keyed by account and message-id. It names its kind, confdb, the devices it's for, by serial, model and brand, and the window when it's valid. Snapd fetches the signer's key and checks the signature as usual. A message for another device, or outside its window, is rejected. Confdb is the only kind with a handler, and it asks for more. The signer must be the operator itself, and confdb-control must delegate the view to it with an operator-key. So a message the store signs for an operator is unauthorized today. The assumes header is read, but not checked yet.
06 Four answers for snapd developers for Ubuntu Core developers
Experimental. rejected and unauthorized come from validation, error and success from applying. The response-message is signed by the device key and sent on the next exchange.
Acme's operator needs to know what happened to the request, so snapd answers every message it processes. Validation can give two answers. Rejected means the message failed a check: wrong device, outside its window, or in a sequence that was dropped. Unauthorized means the handler found no delegation. Applying gives the other two: error if applying or its change failed, and success otherwise. The response-message is keyed by account, message-id and device, carries a JSON body, and is signed by the gateway's key. It's queued and sent on the next exchange. A note for handler writers: error text reaches the operator exactly as written.
07 Where to go from here
Roads: why confdb exists, configuration, confdb hooks, how assertions work, devices and the device key, identity and store, and the overlord.
So a proxy address on a gateway nobody can reach changes through three signed statements: acme's schema, the gateway's delegation, and an operator's request, with the gateway's answer going back. Confdb: configuration that does not belong to one snap explains why confdb exists at all. Configuration shows views next to snap get and snap set, and the confdb hooks deck covers what runs when a view changes. Assertions: how they work shows how any statement is checked. The devices deck covers the serial and the device key. Identity and store covers the accounts and keys of owners and operators. And the overlord explains changes, tasks and lanes.
Read more
Where each type is kept
| Type | Stored in the assertion database |
|---|---|
confdb-schema | yes |
confdb-control | yes, created on the device |
request-message | no |
response-message | no |
The confdb message handler accepts a request-message only when its authority-id equals its account-id.
Flags
| Flag | Needed for |
|---|---|
experimental.confdb | confdb views, snap get and snap set on views, the confdb message handler and POST /v2/confdb |
experimental.remote-device-management | fetching request messages and POST /v2/confdb |
Set them with snap set system experimental.<flag>=true. With remote device management off, the exchange still runs to send responses that are already queued.
Delegating views
POST /v2/confdb with a JSON body; there is no snap command.
| Field | Value |
|---|---|
action | delegate or undelegate |
operator-id | the operator's account ID |
views | a list of <account>/<schema>/<view> |
authentications | a list of operator-key and store |
Each change re-signs confdb-control with the device key at the next revision. The device needs a serial whose serial number matches ^[a-zA-Z0-9](?:[:+-]?[a-zA-Z0-9])*$; otherwise invalid serial: <serial>.
The exchange
| Item | Value |
|---|---|
| Change | device-management-exchange, summary Process device management messages |
| Interval | 6 hours after the last exchange |
| Endpoint | the store's v2/messages |
| Request | the queued responses, the token of the last received message (after), and a limit of 10 new messages |
| Acknowledgement | a message stays queued at the store until a later exchange acknowledges it with after |
| Tasks | exchange-mgmt-messages, dispatch-mgmt-messages, then per message validate-mgmt-message, apply-mgmt-message, queue-mgmt-response |
| Order | a message-id of <id>-<n> is message n of sequence <id>; each waits for the one before; sequences and unsequenced messages run in parallel lanes |
| Gap | the sequence stops until the missing message arrives |
| More than 8 messages waiting behind a gap | the earliest is answered rejected (too many messages waiting on missing predecessors in sequence) and the rest are dropped |
| More than 256 sequences | the least recently used are answered rejected (sequence evicted due to capacity limits) |
| Waiting for the applied change | queue-mgmt-response retries every 30 seconds until the change is ready |
Answers
| Status | From | Example reasons |
|---|---|---|
rejected | validate-mgmt-message | cannot decode message, cannot verify message signature, not intended for device <id>, not valid at <time>, cannot find handler for message kind "<kind>", an invalid confdb action |
unauthorized | validate-mgmt-message | no confdb-control; authority-id differs from account-id; the view is not delegated to the operator with operator-key |
error | apply-mgmt-message | the handler or the change it started failed; the text reaches the operator as written |
success | apply-mgmt-message | the result is in the body |
A message's devices entries have the form <serial>.<model>.<brand-id>. assumes is parsed but not checked yet.
The confdb message body
| Field | Meaning |
|---|---|
action | get or set |
account | the schema's account |
view | <schema>/<view> |
keys | the request names to read |
constraints | optional constraints for a read |
values | the values to write |
Further reading
- Confdb configuration mechanism: views, custodians and hooks as published.
- Configure snaps with confdb: a worked example with a schema and two snaps.
- confdb-schema: the schema assertion's fields.
- confdb-control: groups, operators, authentications and how delegations are managed.
- Experimental features: the flags this deck needs.
Roads from here
RUNNING SNAPS
- Configuration — confdb views as configuration with snap get and snap set
- The overlord — the device-management-exchange change and its tasks
- Confdb: configuration that does not belong to one snap — what confdb is for
ASSERTIONS · signed statements snapd trusts
- Assertions: how they work — how any assertion is checked and stored
- Assertions: devices — the serial and device key that sign confdb-control and responses
- Assertions: identity and store — the accounts and keys of schema owners and operators
HOOKS · code snapd runs inside a snap
- Hooks: confdb hooks — the hooks that run when a view is read or changed