The job certificate format, version 1

Certificate format. A Hangar certificate is a signed file that shows what happened in a job, and anyone can check the file offline.

Use this page to build your own checker for Hangar certificates. The page gives every byte of the job certificate, the data certificate, the record, the tree head, the key attestation and the key set. The page also gives every byte of the application release documents that a job certificate includes (Section 12). A checker built from this page alone gives the same result as hangar verify on every test vector in vectors/cert/.

The hangar_cert crate is the reference implementation. If the crate and this page disagree, that is a defect. Report the defect to the address in SECURITY.md.

1. Conventions

• All integers are unsigned. Multi-byte numbers in hashes and signatures are big-endian, unless the text says otherwise.
• || means concatenation of bytes.
• SHA-384 means FIPS 180-4 SHA-384. The output is 48 bytes.
• "Map {1: a, 2: b}" means a CBOR map with unsigned integer keys 1 and 2.
• An optional field is absent when the field has no value. The field is never present with an empty or null value.
• Times are seconds since 1970-01-01 00:00:00 UTC. A time value is the array [seconds, nanoseconds], with nanoseconds below 1,000,000,000.

2. The encoding profile

Every document is CBOR (RFC 8949) in the core deterministic encoding of RFC 8949 Section 4.2.1, with the narrower rules below. A decoder must refuse any input that breaks a rule. A decoder must never repair the input.

Unknown fields. Every map on this page lists all of its keys. A decoder refuses any key that the page does not list. This rule stops an attacker adding a field to a signed document that one verifier ignores while another verifier acts on the field.

Re-encoding. After decoding, a verifier encodes the document again with these rules and compares the new bytes with the input. Any difference is a failure. A decoder that follows the rules above never sees a difference. The check catches a decoder that accepts more than this page allows.

3. Digests and domain separation

The digest of a signed document is

D = SHA-384( ASCII(context) || 0x00 || encode(body) )

Here encode(body) is the canonical encoding of the body map of the document, not the signature bundle. The context is one of these strings:

No context contains a zero byte, so the hashed bytes can be read in only one way. The record digest is also the chain hash and the log leaf data. The certificate digest is the fingerprint of the certificate, printed on the certificate page. The release id is the digest of the exact bytes of a release manifest under hangar-app-release-v1. A document type number marks a domain even where the domain hashes JSON. No CBOR document can take such a number.

The log uses the hashes of RFC 9162 Section 2.1, with SHA-384:

leaf hash = SHA-384( 0x00 || leaf data )        leaf data = the 48-byte record digest
node hash = SHA-384( 0x01 || left || right )
empty tree root = SHA-384( "" )

Key id. A key pair has an ML-DSA-87 public key pk_ml (2,592 bytes) and a P-256 public key pk_ec (65 bytes). The key id is:

key id = first 16 bytes of SHA-384( pk_ml || pk_ec )

The file vectors/cert/digests.txt gives test values for each formula. The values were computed without the crate.

4. Signatures

Every signed document has the form

{1: body, 2: signature bundle}

Both signatures cover the 48-byte digest D of the body (Section 3).

A WebCrypto or OpenSSL verifier checks the P-256 signature with message D, hash SHA-384, and the IEEE P1363 (r || s) format.

The signature bundle is the map

The issuer always writes both signatures. A damaged document may lack key 2 or key 3, so the verifier can report which signature is missing. A bundle verifies only when both signatures are present and both are valid. A P-256 signature with a high s value fails.

5. The key hierarchy

A root signs a key attestation that vouches for each day key. A certificate includes the attestation for every day key that signed anything in the certificate. A verifier therefore needs only the key set.

A signed object is valid only if its time falls inside the window of the day key that signed the object. The times are the time of a record, the time of a tree head and the issued_at of a certificate. A day key that has expired does not invalidate objects that the key signed while the window was open.

5.1 Root key custody

The record-signing root of Hangar is separate from the release-signing root. Neither root is held in AWS (engine paper Section 1).

• P-256 root private key. The YubiHSM 2 pair in Sydney generates the key as a non-exportable asymmetric key with the ECDSA signing capability only. The key never exists outside the HSM.
• ML-DSA-87 root private key. The D-02 step must confirm whether the YubiHSM 2 firmware supports ML-DSA [verify]. If the firmware supports ML-DSA, the HSM generates and holds the key, as for the P-256 key. If the firmware does not support ML-DSA, the root is held as follows:
  • Two people generate the 32-byte ML-DSA-87 seed on an offline machine in a ceremony. The seed is never written in plain form.
  • The seed is sealed with AES-256-GCM under a 256-bit wrap key. The YubiHSM generates the wrap key, and the key cannot be exported. If the team uses the data-wrap command of the HSM instead, the mode is the AES-CCM of the HSM [verify which, at D-02].
  • The sealed file is stored in the vault account and in the offline safe. The file is unsealed only into the memory of the signing process, in SecretBox, for a signing ceremony. The memory is wiped when the ceremony ends.
  • Recommended, for the Director's decision: each ceremony signs the day key attestations for a batch of days ahead (for example 35 days). The seed is then unsealed about once a month, not every day.

Together, the key set and this section state which of the two arrangements applies.

6. The record (document type 1)

A record is one state change. Signed form: {1: record body, 2: bundle}.

6.1 Record kinds

Kind 15 records the events of one job of an application release: compiled, an attempt started or ended, an artefact checked, returned or cancelled. Kind 16 records a change to an application release: submitted, accepted, refused, revoked, a channel moved, a widening approved or declined. Kind 11 still means a release of Hangar itself.

6.2 The kind-specific body

The kind-specific body is a map with unsigned integer keys. Each type of value has a size limit, so a record cannot hold customer data:

• byte strings at most 64 bytes;
• text at most 1,024 bytes, with no control characters (Unicode general category Cc);
• arrays and maps at most 256 items;
• nesting at most 4 levels, the body map being level 1;
• integers and booleans as in Section 2.

The verifier reads the body without knowing the keys. The only exception is the movement record, below.

Movement records (kind 3).

The control plane (D-02) defines the bodies of the other kinds and lists the bodies there. The test vectors use these bodies: job state {1: job id, 2: state (1 started, 2 finished), 3: image name, 4: image digest text, 5: resolution time, 6: command, 7: environment names, 8: exit code}; reset {1: instance id, 2: GPU UUIDs, 3: serials, 4: method}; wipe {1: instance id, 2: method, 3: result}; attestation {1: subject, 2: digest}; release {1: version, 2: manifest digest}.

A record from the slot egress proxy (D-03) has key 97. Key 97 is an array of text with one line for each decision of the proxy. Each line has the form <outcome> <destination> <bytes_up> <bytes_down> <at> <reason>. The outcome is refused or connected. The destination is the name that the job asked for, or - when the job gave no name. The byte counts are decimal. The time is RFC 3339. The reason is empty for a connection. Refusals go on a flag record, and connections go on a job state record. A record holds at most 256 lines, and each record links to the slot. The lines hold destinations and byte counts only, never content.

Application release and release job records (kinds 14, 15 and 16, and the movement and operator records of a job). This page fixes the keys from 100 up (hangar_cert::release::body). Keys 1 (action text), 2 (status text), 19 (reason text) and 39 (a 48-byte digest) are general keys of the control plane. The release check also reads these four keys.

A certificate of kind 4 (the return of one job) includes these records, listed by action text (key 1):

The certificate includes the D-08 session records of each attempt (start, steps, reset steps with provider responses, connections and approvals) in the same form as on a sandbox session certificate.

7. The log

7.1 Inclusion proof

An inclusion proof is the map {1: leaf index (uint), 2: path (array of bytes, 48 each, at most 64)}. The path is the RFC 9162 PATH(m, D[n]), with the sibling nearest the leaf first. Verify the proof with RFC 9162 Section 2.1.3.2. Take the tree size and the root from the signed tree head, never from the proof.

7.2 Tree head (document type 2)

Signed form: {1: tree head body, 2: bundle}.

7.3 Published tree head list (document type 6)

The list is an unsigned map. Each head in the list is signed.

8. Keys

8.1 Key set (document type 5)

The key set is the published trust anchor. Signed form: {1: key set body, 2: bundle}.

Root entry: {1: key id (bytes, 16), 2: ML-DSA-87 public key (bytes, 2,592), 3: P-256 public key (bytes, 65), 4: not before (uint), 5: not after (uint, optional)}. The key id must equal the key id computed from keys 2 and 3.

A root listed in the key set signs the bundle. On rotation, key 8 names the previous root, and the previous root signs the bundle. The key set then lists both the old root (with not_after) and the new root. A verifier that holds the old key set accepts the new key set when all of these are true: the new key set checks on its own; the previous root of the new key set is a root of the old key set; the issuer, platform chain id and log id are unchanged; and the not_before of the new key set is not earlier than the old one.

8.2 Key attestation (document type 3)

Signed form: {1: attestation body, 2: bundle}. A root signs the bundle.

A verifier refuses an attestation if any of these is true: the key id of the bundle differs from key 7; the day key id equals the id of any root in the key set; key 7 is not a root in the key set; the window is longer than 26 hours; the validity of the root does not cover not before; or the bundle does not verify under the root.

9. The certificate (document type 4)

Signed form: {1: certificate body, 2: bundle}. A day key signs the bundle.

9.1 Facts

A verifier that does not know key 20 fails decode with the unknown-key sentence (Section 2, unknown fields), so an older verifier never reads a certificate that states a platform version as if the certificate stated none. The certificate version stays 1: key 20 is an additive field, and the rule that a decoder refuses a key the page does not list is what makes the addition safe.

The issuer (certificate field 4) is the issuer that the record key set names (key set fields 2 and 3). Certificates from Hangar name TALOS Defence Pty Ltd as issuer. A job in a customer-controlled pool is signed under the customer's own root. The return from that job names the customer as issuer, and a verifier checks the return against the key set of the customer.

Job map: {1: job id (text), 2: image name (text, optional), 3: image digest (text), 4: resolved at (time), 5: command (array of text, at most 256), 6: environment names (array of text, at most 256), 7: started (time), 8: ended (time), 9: outcome (uint), 10: outcome reason (text, optional)}. Outcome: 1 completed (the command ran and exited), 2 ended abnormally (the job stopped before its command exited: a crash, an instance fault or the end of the slot), 3 cancelled (by the customer or an operator), 4 not started (booked and never run). The reason is a plain sentence from the worker, for example the exit status.

Hardware: {1: instance type, 2: instance id, 3: accelerator count (uint), 4: accelerators (array of {1: UUID or device identity, 2: serial}, at most 64), 5: region, 6: zone, 7: capacity block id (optional), 8: accelerator family (optional)}, text unless stated. Key 8 is nvidia-h100 or aws-trainium2. When key 8 is absent, the family is nvidia-h100, so certificates issued before the Trainium pool keep their meaning. A certificate from the pool hosted-trn-mel has aws-trainium2 at key 8, and each key 4 entry is {1: "neuron<N>@<bdf>", 2: the driver serial}. Any other text at key 8 fails decode. An entry that does not match the family also fails decode: a neuron<N>@<bdf> entry under any family but aws-trainium2, or any other entry under aws-trainium2. A verifier that does not know key 8 fails decode with the unknown-key sentence, so the verifier cannot misread the certificate. The facts page prints "with 1 Trainium2 accelerator" and one "Accelerator N" line for each device.

When: {1: zone name (text, "Australia/Melbourne"), 2: start (local time), 3: end (local time)}. Local time: {1: UTC time, 2: offset in minutes east of UTC (uint), 3: local time text}.

Data item: {1: digest (fact digest), 2: size in bytes (uint), 3: file name (text, optional)}.

9.2 Value rules on the certificate

No certificate field holds free bytes. A certificate cannot show file contents, secret values or environment values.

9.3 Melbourne time

Victoria observes AEST (UTC+10, offset 600) and AEDT (UTC+11, offset 660). Daylight time starts at 02:00 AEST on the first Sunday in October and ends at 03:00 AEDT on the first Sunday in April; both moments are 16:00 UTC on the Saturday before that Sunday. For a UTC time t in UTC year Y, the offset is 660 if t is at or after the October change of Y or before the April change of Y, and 600 otherwise.

The local time text is YYYY-MM-DD HH:MM:SS AEDT or YYYY-MM-DD HH:MM:SS AEST. The text shows the UTC time plus the offset, zero-padded. Example: UTC 1793829600 (2026-11-04 22:00:00 UTC) is 2026-11-05 09:00:00 AEDT.

9.4 Sandbox facts (kind 2 only)

The published sandbox reset has five steps. These are the names that the worker uses: instance_terminated, egress_group_checked, credentials_revoked, gateway_ca_destroyed, secrets_detached. A sandbox session certificate lists each step exactly once and lists no other step. The step egress_group_checked replaces the earlier step security_group_deleted (D-20 N1). A verifier refuses a certificate that lists security_group_deleted.

The field names follow the D-08 control plane (hangar_api sandboxes): shape, vcpus, secret_name and destination, decisions approved and declined, and the reset step names. In D-08, the start record holds the allowlist as an array of text at body key 71, and each reset step record holds the response text of the provider at body key 76.

9.5 Release job facts (kind 4 only)

A job certificate of an application release is the return of one job (D15.19). Facts key 2 (jobs) may be empty, and key 3 (hardware) may be absent, because each attempt below lists its own instance. Keys 4 (when), 16 (attestation kind) and 17 (reset path) are present, as on every job certificate.

Keys 19 and 20 are both present on a return from a customer-controlled pool (pool kind 2) and both absent on a return from a hosted pool.

The return holds no input bytes, no output bytes, no configuration value and no secret value. The return holds only the digests, names and sizes of these items.

9.6 Places and the Region policy (facts keys 22 and 23)

Key 22 states each place where customer bytes were stored, processed or staged, and where the records about them are, by AWS Region. Key 23 states the Region policy the job ran under (D-20 WP19). Both are additive under certificate version 1, as key 20 is: a verifier that does not know them fails decode with the unknown-key sentence, so it never reads a certificate that states them as if they were absent. A data certificate states neither. A return from a customer-controlled pool states neither: a customer runtime keeps no Region policy.

Place: {1: role (uint), 2: region (text), 3: zone (text, optional), 4: what (text), 5: movement records (array of record digests, bytes 48, at most 4,096)}.

A movement record of type 2 (staged for a slot) or 3 (mounted on the instance) belongs to a staged place. A movement record of any other type belongs to a stored place.

Region policy: {1: setting (text), 2: source (uint), 3: policy record (bytes, 48), 4: cell (text), 5: home cell (text), 6: reason (text)}.

The location statement is derived. Key 14 equals the statement built from key 22 and key 23 by hangar_cert::places::location_statement, byte for byte. The issuer and the verifier call the same function. The Regions of processed and staged places are "processed"; the Regions of stored places are "stored"; each Region prints with its city, such as ap-southeast-4 (Melbourne):

• Processed and stored in the same Regions: "Staged, processed and stored in R only."
• No stored place: "Processed in R only.", or "Staged and processed in R only." when a staged place exists.
• Otherwise: "Staged and processed in R. Stored in S."
• Then, when a record place exists: " Records in T."
• Then, when key 23 is present: " Region policy: W, set by the organisation." or "..., set by the job.", where W is the setting in the Director's words (melbourne only, melbourne preferred, sydney as the alternative, no preference, sydney only, sydney preferred, melbourne as the alternative).
• Last: " Keys held in Australia."

For example: "Staged, processed and stored in ap-southeast-4 (Melbourne) only. Records in ap-southeast-4 (Melbourne). Region policy: melbourne only, set by the organisation. Keys held in Australia."

The facts page prints one row "Place" for each place, and the rows "Region policy", "Placement" (the sentence of the reason), "Cells" (signer named: sydney; home cell: melbourne) and "Policy record".

10. Verification procedure

Inputs: the certificate bytes, the key set bytes, the current time now in seconds, and optionally the published tree head list. The checks run in this order. The first failure stops the procedure. The report shows every later check as not run, never as passed.

1. decode. The certificate decodes under Section 2 with only the fields of Section 9, every nested document included, and re-encodes to identical bytes.
2. key_set. The key set decodes and re-encodes identically, lists distinct roots, names an issuer, and its bundle verifies under a root it lists (the previous root, on rotation).
3. day_keys. The certificate carries at least one attestation, no day key is attested twice, and each attestation passes Section 8.2.
4. certificate_signature. The bundle's key id is an attested day key, issued_at is inside its window, and the bundle verifies over the certificate digest.
5. record_signatures. Every included record passes the same test, using the time of the record.
6. chain. Every record's chain id is the organisation's chain id (field 5.3) or the key set's platform chain id. Within each chain, indices strictly increase in the order given. Where two included records are adjacent (index n and n + 1), the later one's previous record hash equals the earlier one's digest, and its time is not earlier by more than the larger of the two clock error bounds. Gaps are allowed: the log, not the chain, proves membership.
7. inclusion. There is at least one record and exactly one proof per record. No two proofs name one leaf index and no record appears twice. Each record digest verifies at its leaf index against the tree head's size and root.
8. tree_head. The tree head's log id equals the key set's log id, its bundle key id is an attested day key, its time is inside that key's window, and the bundle verifies.
9. time. The key set's not_before is not after now. No record time, tree head time, issued_at or attestation not_before is later than now plus the clock error bound. No record is later than the tree head, and the tree head is not later than issued_at, each allowing the clock error bound.
10. facts. The facts agree with the signed records. Check each of these:
    • The issuer equals the issuer of the key set.
    • Every data digest, the instance attestation digest, the release manifest digest, the daily audit log digest and the image digest of every job (as text) appears as a leaf value in the body of some included record.
    • Each listed movement record digest is the digest of an included movement record. Each reset and wipe record digest is the digest of an included reset or wipe record.
    • The accelerator count equals the number of accelerators listed. Each entry has the form of the accelerator family (Section 9.1).
    • Each local time equals the time that Section 9.3 gives for the UTC time. The zone is Australia/Melbourne.
    • A job ends no earlier than it starts. A job starts no earlier than its image name resolved.
    • A job certificate states hardware, when, the attestation kind and the reset path.
    • A sandbox session certificate has sandbox facts. Every other kind has none.
    • For sandbox facts, all of these hold. The vCPUs are 2, 4, 8 or 16. Refused connections do not exceed connections. The instance type and id equal those in hardware. The allowlist digest is the SHA-384 of the canonical encoding of an array that an included record holds. An included record holds the proposal digest of each approval, as bytes. Each published reset step appears exactly once, and no other step appears. The response digest of each step is the SHA-384 of a text value that an included record holds. A tenant, when present, is a text value that an included record holds.
    • A data certificate names its subject upload. Every included record is a movement record whose key 2 or key 9 contains the digest of that upload. The records are in time order. The first record shows the upload being received.
    • Places and the Region policy (Section 9.6). A job certificate of the hosted service whose platform version is 4.17.0 or later states key 22 and key 23. Key 23 is not stated without key 22. When key 22 is stated, all of these hold. Each listed movement record is named by exactly one place, of the role its type gives. A place names no movement record that the facts do not list. The instance of the hardware, and of each attempt of a release job, is a processed place, in the Region the hardware states. The location statement is the derived one.
    • When key 23 is stated, all of these hold, in this order. The cell and the home cell are cells of the hosted service. For melbourne_only and sydney_only, every place of every role is in that Region, the cell is the cell of that Region, and the home cell is the cell of that Region. Every place of every role is in the Region of a hosted cell that the setting allows: melbourne for melbourne_only, sydney for sydney_only, and sydney and melbourne for the three other settings. For melbourne_preferred and sydney_preferred, a processed place outside the preferred Region has the reason chip_not_in_preferred_region, no_capacity_in_start_window or chosen_block. Every processed place is in the Region of the cell that key 23 names.
11. release (kind 4 only, listed straight after facts; Section 10.1). The vendor signed the release, TALOS Defence accepted the release, the compiled envelope lies within the request of the release, and every connection and output stays within the envelope.
12. published_heads (only when the list is supplied). The list's heads have one log id and strictly increasing sizes; each consistency proof verifies; each head is signed by a day key the list's attestations vouch for, within its window; and the certificate's tree head (log id, size and root) is one of the heads. If the list does not contain the tree head of the certificate, the certificate comes from a log that was never published. The test therefore detects a fork of the log.

For kind 4, check 10 also requires: release job facts present (and absent on every other kind); when, the attestation kind and the reset path stated.

The certificate is valid when every check but published_heads passes and published_heads did not fail. For kinds 1 to 3, the checks are 1 to 10, and the reports list eleven checks exactly as before. For kind 4, the checks also include release. The report says whether published_heads ran.

10.1 The release check

Inputs: the certificate, the record key set, and TALOS Defence's published release key set (hangar verify --release-keys). The parts run in order. The first part that fails stops the check and gives the failure sentence.

1. The release id (Section 12.2) equals release job facts key 22. The record whose digest is at key 21 is included and is a release job record (kind 15) with action compiled. The body of that record has the release id at key 100 and the pool id at key 102. The body has the tenant at key 103 (absent when the job has no tenant). The body has self_test at key 2 for a self-test, or run otherwise.
2. The vendor signature bundle names the vendor keys in the release (key id as in Section 3). Both signatures verify over the release id. A return from a hosted pool carries facts key 4. A customer-controlled runtime cannot include a record of the Hangar chain, so there the acceptance binds the key. When facts key 4 is present, the record that key 4 names is included. That record is a key event (kind 14) on the vendor chain (the vendor chain of the manifest) with action vendor release key registered. The record has the vendor key id at key 107 and the vendor keys digest at key 108. A self-test runs on a hosted pool with no tenant. A return with facts key 18 true fails if the pool is customer-controlled, if the return names a tenant, if the return carries an acceptance, or if the return carries facts key 5.
3. Unless the job is a self-test, all of these are true:
   • The release carries an acceptance.
   • The verifier has the release key set. Otherwise the check fails with "This return needs TALOS Defence's published release key set to check the release. Give it with hangar verify --release-keys."
   • The acceptance names this release, this vendor key and this vendor keys digest.
   • Every published acceptance check appears exactly once and passed. The exception is advisory_match, which may be not run.
   • The key id of the acceptance bundle is a root of the release key set that is valid at the acceptance time. A day key is never a root.
   • That root is not a root of the record key set, because release roots and record roots are separate keys.
   • Then the widening rules apply. The compiled record has a baseline release id at key 125. When the baseline release id equals the release id, facts key 24 is absent and the widening is empty. Otherwise facts key 24 is present, and all of these are true: the release id in key 24 equals key 125; key 24 names the same package and vendor chain as the release; the vendor signature of key 24 verifies; and the acceptance of key 24 verifies against the release key set, by a root that is not a root of the record key set. The widening is the difference diff (Section 12.1) from the envelope request of the baseline to the envelope request of the release. Each item is printed as describe prints it. Key 118 of the compiled record (absent when empty) lists exactly those items, in that order. A widening that is not empty needs facts key 5. The widening list inside the acceptance is information only and decides nothing. A self-test carries no facts key 24. When facts key 5 is present, the record that key 5 names is included. That record is an application release record (kind 16) with action widening approved. The record has the release id at key 100 and the tenant of the job at key 103. For a job with no tenant, key 103 is absent or the empty text.
4. The envelope digest (hangar-envelope-v1 over the canonical bytes of the envelope) equals facts key 23 and key 101 of the compiled record. The envelope lies within the request of the release (Section 12.1, the rule within). The first source of the envelope is the envelope request digest of the release. The envelope states the release id, the id, name and kind of the pool, the tenant, the configuration digest, the inputs and the values digest, and each agrees with the facts. The configuration digest also equals facts key 6 and key 104 of the compiled record. Every input is in data in, with its size. A return from a customer-controlled pool states facts keys 19 and 20. A return from a hosted pool states neither.
5. Every destination with a connection made is in the destinations of the envelope. A destination with only refusals may have any name. Every model route used is a route of the envelope, to the destination of that route, or to the declared fallback when the entry is marked as a fallback. An included record holds the proposal digest of every approval, as bytes.
6. There are at most retries plus one attempts, numbered from 1 in order. Each attempt starts no earlier than the not-before time of the envelope and no later than the not-after time, allowing for the clock error bound. Each attempt ends no earlier than the attempt starts. The reset and wipe records of each attempt are included reset or wipe records. Every output names a listed attempt and is in data out with its size. Every output also has an included release job record with action artefact checked, the output name at key 111, the descriptor result at key 112 and the output digest at key 39. A job that states success has a last attempt that succeeded, and every output of that attempt passed.

The compiled record may hold the advisory stamp of the release vulnerability watch (Section 6.2, keys 126 to 129). Part 1 reads the stamp for every job. The record has all four keys or none. The digest is 48 bytes, the time is a uint, the counts are text in the stated form, and the decision is one of the three words. A record with no stamp is valid, so a return from before the watch verifies as before. The stamp shows what the control plane knew when the job started. The stamp does not show that the release has no vulnerabilities.

The browser verifier has no release key set. For a return that is not a self-test, the browser verifier therefore fails part 3 with the sentence above. The browser verifier never passes a release that it could not check.

Notices. Every report, valid or not, prints these facts as notices beside the verdict. The JSON field notices holds the notices, and the terminal shows them as NOTICE: lines. Notices are not checks, so a report never shows a notice as passed:

• attestation kind 2: "Test attestation: this certificate comes from the Hangar test pool and carries a test attestation of the instance."
• attestation kind 4: "Not attested: no attestation of the instance arrived for this job, so the certificate states none."
• reset path 2: "Reset by reboot in place: the instance was reset and rebooted between jobs on the same hardware."
• on a sandbox session certificate, one line for the tenant when there is one ("This session served the tenant NAME."), one line per companion ("Companion container NAME ran inside this session, image DIGEST."), one line for the gateway ("The gateway handled N connections and refused R."), and one line per reset step ("Reset step NAME confirmed at TIME, provider response digest HEX.").
• on a job certificate of an application release whose compiled record carries the advisory stamp: "When this job started the release was matched against the advisory snapshot sha384:HEX taken TIME. Matches: COUNTS. The advisory policy decided: DECISION. The match is only as complete as the advisory sources and the bill of materials."
• on a job certificate of an application release: for a self-test, "This return is a self-test of a release before TALOS Defence accepted it."; for a lapsed licence, "The runtime's licence had lapsed when this job returned."; and when the revocation list's age is stated, "The release revocation list was N days old when this job started."

The facts page of a kind 4 return adds these rows after the sandbox rows: Release (<package> <version>, sha384:<12 hex>), Tenant, Pool (<name>, <site>), Envelope (sha384:<12 hex>, <n> destinations, <v> vCPU, <m> min), Attempts, Outcome, and Self-test (yes, for a self-test only).

11. A worked start

The test vector for a slot certificate begins like this:

a2                         map, 2 entries (signed form)
  01                       key 1: body
  ac                       map, 12 entries
    00 04                  document type 4
    01 01                  version 1
    02 50 <16 bytes>       certificate id
    03 01                  kind 1, GPU slot
    04 a2                  issuer, map of 2
       01 75 "TALOS Defence Pty Ltd"     21-byte text
       02 6e "24 696 691 906"           14-byte text
    05 a3 ...              organisation
    06 ...                 facts
    ...
  02 a3                    key 2: bundle, map of 3
    01 50 <key id>
    02 59 12 13 <4,627 bytes>
    03 58 40 <64 bytes>

Every record inside the certificate begins a2 01 ab 00 01 01 01 02 50 <chain id> 03 <index>. The bytes show a signed form, then a record body of 11 entries, with type 1 and version 1.

12. The application release documents

These documents describe an application release and let a customer-controlled pool check the release offline. The release check (Section 10.1) reads them. Every document follows the encoding rules of Section 2 and lists all of its keys. A verifier refuses a document when a list that the page calls "sorted" is out of order or repeats an item. The version is 1 in every document.

12.1 The envelope request and the compiled envelope (types 10 and 9)

The envelope request sits inside the release manifest. The request has no field 0. The digest of the request is hangar-envelope-request-v1 over the canonical bytes of the request.

Names: a destination is a lower-case DNS name of two or more labels. A destination is not an address, does not end in .hangar.internal and has no trailing dot. A secret is a capital letter then up to 63 capitals, digits or underscores. A header is lower-case letters, digits and hyphens, and is not a header that the gateway refuses. A companion is a lower-case letter then up to 30 lower-case letters, digits or hyphens, and is never agent. A secret is bound to a requested destination. The destination and the fallback of a model route are requested destinations, and the two differ. A destination first use step names a requested destination. A credential use step names a requested secret.

The compiled envelope (type 9). The envelope digest is hangar-envelope-v1 over the canonical bytes of the compiled envelope.

A compiled envelope has these properties without reference to a request. Every secret, model route and fallback is bound to a granted destination. The envelope grants the data scope of the inputs of the job whenever the envelope binds an input. The window is positive and at most (minutes + 10) * (retries + 1) * 60 seconds.

Within. A compiled envelope lies within the request of a release when all of these are true:

• The request is the request inside the manifest, and the envelope names the digest of the request as the request source.
• The image and the command are those of the manifest.
• Every companion, data scope and secret binding is requested exactly.
• Every destination is requested. Every required destination and secret is present.
• Every dropped item names a requested item that the envelope does not grant.
• Every model route is a requested route to the same destination, with the requested fallback or none.
• Every requested person-present step is present.
• Compute, retries and resume are no wider than requested.

Widening. Between two requests, the widenings are the following, in this order and by name within each: a new destination; a new or rebound secret; a new data scope; a new companion or one on another image; a new model route or one to another destination; a fallback gained or changed; more vCPUs, memory or minutes; more retries or resume newly allowed; a person-present step removed. A request with no widening needs no approval.

12.2 The release manifest and the signed release (type 7)

The compute of the request lies inside the resources. The release id is hangar-app-release-v1 over the exact canonical bytes of the manifest. No field names an image by tag, and no field holds a configuration value.

The signed release: {1: manifest bytes, 2: vendor signature bundle, 3: {1: ML-DSA-87 public key, 2: P-256 public key}, 4: acceptance (optional), 5: acceptance signature bundle (optional)}. Key 1 holds the exact bytes of the manifest, decoded strictly. Keys 4 and 5 are both present or both absent. The vendor bundle signs the release id (Section 4). The vendor keys digest is hangar-vendor-key-v1 over the ML-DSA-87 key followed by the P-256 key.

12.3 The acceptance (type 8)

The published checks, each listed once, are: vendor_signature, image_present, sbom_present, advisory_match, envelope_request, configuration_schema, runtime_range, envelope_difference, self_test. A root of the release key set signs the acceptance digest, which is hangar-app-acceptance-v1 over the canonical bytes of the acceptance.

12.4 The release revocation list (type 13)

The list is the map {0: 13, 1: 1, 2: sequence (uint, from 1), 3: issued at, 4: revoked}, where revoked is an array sorted by release id of {1: release id (bytes, 48), 2: at, 3: reason (text)}. Each list holds every revocation made so far. Signed form {1: list, 2: bundle}. A root of the release key set that is valid at the issue time signs the bundle, over hangar-release-revocations-v1 of the list.

12.5 The release bundle and the site snapshot (types 16 and 15, unsigned)

A root signs each item inside, so neither document is signed as a whole. A key set inside is stored as the exact published bytes of the key set.

• Release bundle: {0: 16, 1: 1, 2: signed release, 3: signed revocation list, 4: release key set bytes}. The bundle checks when all of these are true: the release key set checks; the vendor signature and the acceptance hold against the release key set; the release key set signed the list; and the release is not on the list. A reader compares the key set with the key set that the reader trusts, or checks the key set as a rotation of the trusted key set.
• Site snapshot: {0: 15, 1: 1, 2: pool id (text), 3: created at, 4: licence file (optional), 5: signed revocation list, 6: release key set bytes, 7: entitlement key set bytes}. The snapshot checks when all of these are true: both key sets check and share no root; the release key set signed the list; and the entitlement key set signed the licence, which names the pool in key 2.

Neither document holds image layers. The vendor ships a separate OCI layout, and the importer checks the layout by digest against the manifest.

12.6 The licence (type 12)

The licence file is {1: licence, 2: bundle}. A root of the entitlement key set that is valid at the issue time signs the bundle, over hangar-entitlement-v1 of the licence. The offline check reads the file, the signature, the deployment and the term, in that order. The check refuses a file that does not decode, a bad signature, another deployment, or a term that has not started. Inside the term, the licence is valid. After the term, the licence is lapsed. A lapsed licence still runs installed releases and refuses new release imports. A lapsed licence admits new tenants for 90 days. The check reports nothing to TALOS Defence.

Read this page as Markdown