99 lines
4.8 KiB
Markdown
99 lines
4.8 KiB
Markdown
# ChronoSeal Protocol Specification (PROTOCOL)
|
|
|
|
This document defines the formal wire protocol, state transitions, cryptographic primitives, and execution invariants of the ChronoSeal browser attestation system.
|
|
|
|
---
|
|
|
|
## 1. Sequence Flow & Handshake
|
|
|
|
ChronoSeal operates as a stateful, sequential challenge-response chain over HTTP/REST.
|
|
|
|
```
|
|
Client (JS/WASM) Server (chronoseald)
|
|
| |
|
|
| 1. POST /init { public_key: String } ----------------> |
|
|
| | (Generates VM Opcodes)
|
|
| | (Computes initial hash chain head H_0)
|
|
| | (Saves initial session record)
|
|
| <--- 200 OK { InitResponse } --------------------------|
|
|
| |
|
|
| [Client executes VM program & prepares gene preview] |
|
|
| |
|
|
| 2. POST /hb { HeartbeatRequest } --------------------> |
|
|
| | (Loads session & executes CAS check)
|
|
| | (Verifies Ed25519 signature)
|
|
| | (Validates VM stack-state parity)
|
|
| | (Computes expected gene mutation)
|
|
| | (Validates hash chain continuity H_N == expected)
|
|
| | (Rotates salt & issues next mutation order)
|
|
| <--- 200 OK { HeartbeatResponse } ---------------------| (Saves updated session record)
|
|
| |
|
|
```
|
|
|
|
---
|
|
|
|
## 2. Cryptographic Transition Mechanics
|
|
|
|
### A. Handshake Phase (`/init`)
|
|
The client registers a 32-byte Ed25519 verifying key represented as a hex string.
|
|
The server:
|
|
1. Generates a 32-byte session ID ($ID$) and a 16-byte initial salt ($S_0$).
|
|
2. Computes the initial hash chain head:
|
|
$$H_0 = \text{Blake3}(ID \parallel PK_{\text{client}} \parallel S_0)$$
|
|
3. Generates a random VM program of size $8..=16$ bytes.
|
|
4. Creates the initial mutation order program $M_1$.
|
|
5. Persists the session record in the database.
|
|
|
|
---
|
|
|
|
### B. Heartbeat progression (`/hb`)
|
|
For each heartbeat step $n \ge 1$:
|
|
The client submits:
|
|
* `prev_hash`: $H_{n-1}$ (hex encoded).
|
|
* `timestamp`: $T_n$ (milliseconds).
|
|
* `entropy_data`: Mouse movement arrays.
|
|
* `stack_state`: The VM final stack and instruction pointer `ip` after execution.
|
|
* `gene_commitment`: Hex-encoded commitment of the mutated gene state.
|
|
* `signature`: Ed25519 signature of the canonical alphabetical JSON payload.
|
|
|
|
The server:
|
|
1. Loads the session record from storage, enforcing optimistic locking (CAS check) to confirm the database `last_hash` matches $H_{n-1}$.
|
|
2. Validates the Ed25519 signature against the canonical alphabetical serialization.
|
|
3. Re-executes the session's VM opcodes and asserts the client's `stack_state` matches the output.
|
|
4. Applies the mutation order $M_n$ to the stored gene state and calculates the expected commitment:
|
|
$$C_n = \text{Blake3}(\text{CandidateGene} \parallel ID \parallel n)$$
|
|
Asserts the client's `gene_commitment` matches.
|
|
5. Validates that $|T_{\text{server}} - T_n| \le \text{max\_drift}$.
|
|
6. Advances the hash chain:
|
|
$$H_n = \text{Blake3}(H_{n-1} \parallel T_n \parallel \text{Blake3}(E_n) \parallel \text{Blake3}(S_n) \parallel S_{n-1})$$
|
|
7. Rotates the salt to $S_n$ and issues the next mutation order $M_{n+1}$.
|
|
|
|
---
|
|
|
|
## 3. VM Instruction Specification
|
|
|
|
The client VM executes instructions sequentially. The instruction set consists of:
|
|
|
|
* `0x00`: Pushes the next 4 bytes in the instruction stream onto the stack as a `u32` value (little-endian).
|
|
* `0x01`..=`0x07`: Binary operators. Requires at least 2 elements on the stack:
|
|
* `0x01`: Wrapping Add (`a.wrapping_add(b)`)
|
|
* `0x02`: Wrapping Sub (`a.wrapping_sub(b)`)
|
|
* `0x03`: Wrapping Mul (`a.wrapping_mul(b)`)
|
|
* `0x04`: XOR (`a ^ b`)
|
|
* `0x05`: AND (`a & b`)
|
|
* `0x06`: OR (`a | b`)
|
|
* `0x07`: Rotate Left (`a.rotate_left(b % 32)`)
|
|
* `0x08`: Unary Bitwise Not (`!a`). Requires at least 1 element on the stack.
|
|
* `0x09`: Hash Stack. Hashes all stack elements using BLAKE3 and reduces it to a single `u32` value, clearing the stack and pushing the hash.
|
|
* *Any other opcode:* Terminates VM execution immediately.
|
|
|
|
|
|
## v1.0.2 Protocol Hardening
|
|
|
|
- Fingerprint aspect ratio validation
|
|
- Device pixel ratio validation
|
|
- Hardware concurrency validation (1..=256)
|
|
- Entropy event cap (500 events)
|
|
- IP-based rate limiting
|
|
- Silent rejection preserved for protocol failures
|