Signed release manifests

An artifact proves which bytes were published. A signed release manifest records who authorized those bytes for a product and the safety rules that belong to the release.

The meshanics.release.v1 payload binds the tenant, product, release identity, components, TUF targets, compatibility profiles, activation order, health policy, rollout constraints, approval references, recovery behavior and related attestation digests. The payload is wrapped in a DSSE envelope and signed with an Ed25519 key controlled by your release process.

Publish a release

1. Create an Ed25519 signing key outside Meshanics. Keep the private key in your CI secret store, HSM or offline release process.
2. Add the public key under Signed releases - Trusted authorizer keys.
3. Select the target device group in Signed releases - Authorized targets. Copy its SHA-256 value into rollout.target_policy_digest. This binds the authorization to that exact static membership snapshot.
4. Create the release JSON and sign it locally with meshanics-release sign.
5. Submit the DSSE envelope and its expected product ID in the control panel or POST /api/v1/releases.

The service verifies the signature, registered key state, tenant, product, validity window and required safety fields. It then stages and publishes the exact envelope as an immutable TUF target. A conflicting product/version cannot replace an existing release.

To start work, select the same group and choose Roll out beside the published release. The service re-verifies the authorizer, envelope digests, current group snapshot, artifact record, device compatibility, health probe, rollout waves and recovery policy. A changed group produces a different target-policy digest and is refused.

Verify outside Meshanics

Download the exact envelope from the release row and run:

meshanics-release verify \
  -envelope release.dsse.json \
  -key release-authorizer.pub \
  -tenant YOUR_TENANT_UUID \
  -product YOUR_PRODUCT_ID

The verifier checks canonical payload bytes, DSSE signature, expected tenant and product, authorizer key, and current validity period. It prints both the signed payload digest and the complete envelope digest.

Device verification

Signed-release assignments carry a TUF target and pinned envelope/payload digests alongside legacy advisory fields. A configured Linux agent downloads the release through TUF, verifies it against locally pinned customer authorizer keys, checks its tenant, product, profile, validity and offline-age limits, then rejects any conflict in the artifact or health fields. It persists the verified desired state before applying the artifact.

Provision all four settings together:

The directory is a local trust anchor. The control plane does not silently add or replace keys after enrollment. A release pointer fails closed when these settings are absent. Legacy rollouts without a release pointer continue during migration and remain distinguishable from signed-release work.

For a multi-component Linux release, use recovery.on_failure: rollback and recovery.rollback_boundary: release. Supported transaction members are containers, models, placed configurations and systemd service binaries. Signed maintenance windows, minimum-agent constraints, Compose, operating-system and package-manager members are refused until those adapters can enforce the same recovery contract.

An os-bundle uses a separate standalone release boundary. It must be the only component in the signed release and must name a .raucb artifact with media type application/vnd.rauc.bundle. The device verifies TUF and the customer release authorization before RAUC independently verifies the bundle signature and compatible string. See Linux A/B system updates.

Multi-component release transactions

The rollout service resolves every signed component before it exposes any work to a device. Each deployment receives a unique transaction ID, so two rollouts of the same release cannot be mixed. Assignment metadata carries the complete member count and the exact group and position from activation.ordered_groups.

On the device, the agent:

1. verifies the same signed release for every member;
2. waits for the complete member set;
3. downloads and stages every descriptor and payload before activation;
4. activates and checks one signed order group at a time;
5. restores every attempted member in reverse order if activation or health fails; and
6. keeps a local crash journal so an interrupted activation is rolled back conservatively before retry.

The control panel shows the transaction as running, committed, rolled back or failed. Download result returns deterministic per-device result manifests that reference every member by rollout ID, artifact ID, digest and ordered position. The API endpoints are GET /api/v1/release-transactions, GET /api/v1/release-transactions/{id} and GET /api/v1/release-transactions/{id}/result.

Device-signed receipts

For a customer-authorized single-component release, the agent writes a terminal meshanics.release-receipt.v1 object before reporting it. The receipt binds the release and rollout, device identity, candidate, previous and resulting digests, activation outcome, health verdict and timestamp. It is signed with the device's existing ECDSA P-256 identity key and uploaded over the same mTLS connection. A failed upload is retried from the locally persisted exact bytes.

A multi-component deployment writes one receipt for the transaction. Its ordered members array records each component's rollout, candidate, previous and resulting digest and terminal verdict. The service validates the complete set against the transaction before accepting the receipt. This avoids treating several independent signatures as proof of one atomic release outcome.

For an OS result, the signed receipt also binds the RAUC compatible string, bundle version, inspected manifest hash, previous and installed slots, observed boot slot, bootloader primary, mark operation and final lifecycle phase. The control panel shows this boot evidence beside the downloadable exact receipt.

The service verifies that the embedded certificate is the certificate on the mTLS connection, checks every field against the signed rollout, and appends the receipt without an update or delete path. The control panel labels this software-key. Legacy rollout status remains device-reported; it is never upgraded merely because it used authenticated transport. A hardware-backed label requires an appraised TPM, TEE or secure-element provider and is not inferred from the software-held device key.

Download one exact envelope from Signed releases - Signed release receipts, or use /api/v1/release-receipts/export for a tar batch with an index. Verify an envelope independently with the tenant device CA:

meshanics-release verify-receipt \
  -envelope DEVICE.receipt.json \
  -ca tenant-device-ca.pem \
  -tenant YOUR_TENANT_UUID \
  -device DEVICE_NAME

Related

• Publishing & signing
• The Update Framework
• Trust Center
• Linux A/B system updates