120 lines
2.7 KiB
Markdown
120 lines
2.7 KiB
Markdown
# ASL/USB-EXCHANGE/1 -- USB Request/Response Exchange Layout
|
|
|
|
Status: Draft
|
|
Owner: Architecture
|
|
Version: 0.1.0
|
|
SoT: No
|
|
Last Updated: 2026-01-17
|
|
Tags: [ops, usb, exchange, offline]
|
|
|
|
**Document ID:** `ASL/USB-EXCHANGE/1`
|
|
**Layer:** O2 -- Offline exchange profile
|
|
|
|
**Depends on (normative):**
|
|
|
|
* `ASL/DAP/1`
|
|
* `ASL/DAM/1`
|
|
* `ASL/POLICY-HASH/1`
|
|
* `PER/SIGNATURE/1`
|
|
|
|
**Informative references:**
|
|
|
|
* `ASL/AUTH-HOST/1`
|
|
|
|
---
|
|
|
|
## 0. Conventions
|
|
|
|
The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHOULD**, and **MAY** are to be interpreted as in RFC 2119.
|
|
|
|
ASL/USB-EXCHANGE/1 defines a filesystem layout for offline request/response exchanges via removable media. It does not define PEL or PER encodings.
|
|
|
|
---
|
|
|
|
## 1. Purpose
|
|
|
|
This document defines the on-media layout for USB-based request/response exchanges used in offline rescue, admission, and authority operations.
|
|
|
|
---
|
|
|
|
## 2. Request Layout (Normative)
|
|
|
|
```
|
|
/usb/REQUEST/
|
|
├── manifest.yaml # REQUIRED
|
|
├── pel-program.yaml # REQUIRED
|
|
├── input-artifacts/ # OPTIONAL
|
|
├── policy.hash # REQUIRED
|
|
├── request.sig # REQUIRED
|
|
└── meta/ # OPTIONAL
|
|
├── requester-domain.txt
|
|
└── notes.txt
|
|
```
|
|
|
|
### 2.1 `manifest.yaml` (Normative)
|
|
|
|
```yaml
|
|
version: 1
|
|
request_id: <uuid>
|
|
request_type: rescue | admission | authority-op
|
|
created_at: <iso8601>
|
|
requested_outputs:
|
|
- artifacts
|
|
- receipt
|
|
- dam # optional
|
|
policy_hash: <sha256>
|
|
pel_program_hash: <sha256>
|
|
input_artifact_hashes:
|
|
- <sha256>
|
|
signing:
|
|
algorithm: ed25519
|
|
signer_hint: <string>
|
|
```
|
|
|
|
Invariants:
|
|
|
|
* `manifest.yaml` is canonical; all hashes are computed over canonical encodings.
|
|
* `policy.hash` MUST match `manifest.yaml.policy_hash`.
|
|
* `request.sig` MUST cover the canonical manifest.
|
|
|
|
---
|
|
|
|
## 3. Response Layout (Normative)
|
|
|
|
```
|
|
/usb/RESPONSE/
|
|
├── receipt.per # REQUIRED
|
|
├── published/
|
|
│ ├── blocks/
|
|
│ ├── index/
|
|
│ └── snapshots/
|
|
├── dam/ # OPTIONAL
|
|
│ └── domain.dam
|
|
├── response.sig # REQUIRED
|
|
└── meta.yaml # OPTIONAL
|
|
```
|
|
|
|
Invariants:
|
|
|
|
* RESPONSE is append-only; existing entries MUST NOT be modified.
|
|
* `response.sig` MUST cover the canonical receipt and published artifacts manifest.
|
|
|
|
---
|
|
|
|
## 4. Exchange Rules (Normative)
|
|
|
|
1. A RESPONSE MUST correspond to exactly one REQUEST.
|
|
2. `receipt.per` MUST be verifiable under `PER/SIGNATURE/1`.
|
|
3. Published artifacts MUST be a subset of the requested outputs.
|
|
4. If a DAM is included, it MUST match the request type and policy hash.
|
|
|
|
---
|
|
|
|
## 5. Non-Goals
|
|
|
|
ASL/USB-EXCHANGE/1 does not define:
|
|
|
|
* PEL operator constraints or execution semantics
|
|
* PER payload encodings
|
|
* Transport beyond filesystem layout
|