Encryption Types

Overview

The encryption type controls four things at once: the size of the request header (32, 48, or 64 bytes), which key encrypts the body, which cipher is used, and how the response proves it came from a genuine RAIDA. The header itself is never encrypted; only the request and response bodies are.

Shared first 16 bytes

Bytes 0–15 are identical for every encryption type: the Routing section (version, split, RAIDA ID, shard, command group, command, coin ID) followed by the Presentation section. Only bytes 16 and up change per type, so the per-type diagrams below start at byte 16.

See the Request Header page for the field-by-field meaning of these 16 bytes.

Type 0 — None (plaintext)

The body is sent unencrypted. Used for public commands such as echo, version, and unencrypted sum-mode operations (pown_sum). The header layout is the 32-byte layout shown under Type 1, but the key-selector bytes (17–21) are ignored.

• Header: 32 bytes. Body length at bytes 22–23. Echo bytes at 30–31 are reflected in response bytes 6–7.
• Body: a 16-byte challenge (12 random bytes + 4-byte CRC32, big-endian) followed by command data, ending with the clear 0x3E 0x3E terminator. The server validates the challenge CRC even though nothing is encrypted — a mismatch returns status 37.
• Response proof: the server copies the challenge unchanged into response bytes 16–31. This proves nothing cryptographically; type 0 offers no authenticity.

Type 1 — AES (coin AN, AES-128-CTR)

The workhorse of the protocol. The client picks one coin it owns as the encryption key coin and encrypts the body with that coin's 16-byte Authenticity Number (AN) for the target RAIDA. Because each RAIDA holds a different AN for the same coin, each of the 25 requests is encrypted with a different key.

• Header: 32 bytes. Byte 17 = key coin denomination (DN), bytes 18–21 = key coin serial number (SN, big-endian), bytes 22–23 = body length (BL), bytes 24–31 = 8-byte random nonce (NO). Echo bytes (EC) 30–31 double as the last two nonce bytes and are reflected in the response.
• Cipher: AES-128-CTR. The 16-byte counter block is the 8-byte header nonce followed by 8 zero bytes that act as the block counter.
• Key lookup: the server looks the coin up by denomination and serial number and uses its stored AN. If the coin page cannot be found the request is rejected with status 34.
• Body: challenge (16 bytes) + command data, encrypted; clear 0x3E 0x3E terminator. After decryption the server verifies the challenge CRC32 — garbage from a wrong key fails here with status 37.
• Response proof: the server writes challenge XOR AN into response bytes 16–31. Only a server that knows the coin's AN can produce this, so the client verifies it to authenticate the response. The response body is encrypted with the same key and nonce (CTR is symmetric).

Type 2 — Locker key (AES-128-CTR)

Identical mechanics and header layout to type 1, but the key is not a coin the client owns — it is derived from a locker code. Used by locker peek and download so a recipient who only knows the locker code can talk to the RAIDA before owning any coins.

• Header: 32 bytes. Bytes 17–21 carry the first 5 bytes of the locker key instead of a real denomination/serial number.
• Key lookup: the server finds the locker index entry whose AN starts with that 5-byte prefix and uses the full 16-byte locker AN as the AES key. An unknown prefix is rejected with status 34.
• Everything else (nonce, challenge CRC, XOR response proof, CTR symmetry) works exactly as in type 1.

Type 4 — AES-256 single key (SHA-256 hardened)

A 256-bit mode that derives its key by hashing a single coin AN. Uses the larger 48-byte header. Note the field order differs from the legacy layout: body length comes before the key coin ID.

• Header: 48 bytes. As implemented by the server: body length (BL) at bytes 17–18, key coin denomination (DN) at byte 19, serial number (SN) at bytes 20–23, and a 24-byte nonce (NO) at bytes 24–47. There are no echo bytes in the request; the response carries the last two request-nonce bytes at response bytes 46–47.
• Key: SHA-256(AN) → 32 bytes. An unknown coin is rejected with status 25.
• Cipher: AES-256-CTR using the first 16 nonce bytes as the IV.
• Body integrity: no challenge. Instead, a 32-byte HMAC-SHA256 over the ciphertext (keyed with the same 32-byte key) is appended to the body before the terminator. The server verifies the HMAC before decrypting; a mismatch returns status 207.
• Response: 48-byte header with a freshly generated random 24-byte response nonce; the response payload is encrypted with the same key and the new nonce, and its own HMAC is appended.

Type 5 — AES-256 double key (two coins, hashed)

Like type 4 but the key comes from two coins, halving the value any single coin leak exposes. The second coin's ID bytes do double duty as the first five nonce bytes.

• Header: 48 bytes. Body length (BL) at bytes 17–18; first coin (DN1/SN1) at bytes 19–23; second coin (DN2/SN2) at bytes 24–28. The second coin's ID bytes double as the first 5 bytes of the 24-byte nonce (bytes 24–47).
• Key: SHA-256(AN1 || AN2) → 32 bytes. Either coin missing → status 25.
• Cipher, HMAC, and response behave exactly as in type 4. The response echoes the second coin's ID at bytes 24–28.

Type 7 — Inter-RAIDA pre-shared key

Used only between RAIDA servers (for example during healing's validate_ticket fan-out). Clients never send type 7.

• Header: 48 bytes. Byte 17 = the sending RAIDA's ID (RI), bytes 18–21 = a 4-byte random key selector (KS), bytes 22–23 = body length (BL), bytes 24–47 = 24-byte nonce (NO).
• Key: a 32-byte pre-shared key looked up from the key manager by (sender, receiver, selector). An unknown selector returns status 216.
• Cipher: AES-256-CTR. No challenge and no HMAC — the inter-RAIDA link relies on the pre-shared key itself. The response generates a fresh key selector and nonce.

Type 8 — Dual-key AES-256-GCM (authenticated encryption)

The newest and strongest mode: 256-bit authenticated encryption designed for post-quantum symmetric strength. Two coin ANs are concatenated raw (no hash) into a 32-byte key, and AES-256-GCM both encrypts the body and produces a 16-byte authentication tag that also covers the header. Unlike CTR modes, any tampering with the header or ciphertext — even a single bit — is detected. Note that bytes 16–23 keep the exact type 1 layout, so key coin A and the body length are where legacy tooling expects them.

• Header: 64 bytes. Bytes 0–23 are byte-for-byte identical to type 1 (key coin A at 17–21, body length at 22–23). Then: key coin B at bytes 24–28, a 12-byte GCM nonce at bytes 29–40, reserved zero bytes at 41–47, and the 16-byte GCM tag (AT) at bytes 48–63.
• Key: ANA || ANB — the two 16-byte ANs concatenated in header order, with no SHA-256 step (this is the key difference from type 5). Order matters: swapping A and B produces a different key and every packet fails.
• Nonce rule: the client generates the 12-byte nonce randomly and clears the most significant bit of its first byte. The response nonce is the same value with that bit set. This splits the nonce space into disjoint request/response halves so a nonce can never be reused across directions — critical because nonce reuse breaks GCM catastrophically. A request whose nonce has the direction bit set is rejected.
• Authenticated data (AAD): the tag covers header bytes 0–47 plus the body plaintext. A tampered command code, body length, or key ID fails verification even though the header is not encrypted.
• Body: same logical layout as type 1 — 16-byte challenge + command data, then the clear 0x3E 0x3E terminator. After the tag verifies, the server still checks the challenge CRC32 (status 37 on mismatch), keeping every command handler unchanged.
• One-coin fallback: a wallet with only one usable coin may put the same coin in both key slots. The server accepts this, but the effective key entropy is then 128 bits, not 256 — two distinct coins are required for the full security claim.
• Deployment: type 8 is enabled per server by configuration. A server with it disabled (or an older server) answers status 34, exactly as it would for any unknown encryption type.

Type 8 response frame

The response keeps the legacy 32-byte frame, with one change: bytes 16–31 carry the response's GCM tag instead of the challenge ⊕ AN proof. The tag covers response header bytes 0–15 (status, body length, execution time) as authenticated data, so a forged status byte is detectable. Empty-body responses still carry a real tag.

Failure frames: if the server cannot verify the request tag (unknown key coin → status 25, or tag mismatch → status 34), it cannot produce a tag the client could verify either. It sends this same 32-byte frame with zero body length and an all-zero tag field. Clients treat that frame only as an unauthenticated hint and act on it only after multiple RAIDAs agree — never from a single frame.

Challenges & CRCs

Types 0, 1, 2, and 8 begin every request body with a 16-byte challenge: 12 cryptographically random bytes followed by the big-endian CRC32 of those 12 bytes. It serves two purposes:

• Decryption check: after decrypting, the server recomputes the CRC32 over the first 12 bytes and compares it with bytes 12–15. Decrypting with the wrong key produces garbage that fails this check, so the server can distinguish “wrong key” (status 37) from “malformed command” without executing anything.
• Response authentication (types 1 and 2): the server proves it decrypted the challenge — and therefore knows the coin's AN — by returning challenge XOR AN in response bytes 16–31. The client recomputes the same value locally and compares.

Types 4, 5, and 7 carry no challenge; their bodies start directly with command data. Types 4 and 5 rely on the HMAC-SHA256 for integrity, and type 7 relies on the pre-shared key. Type 8 keeps the challenge for command-layer compatibility, but its GCM tag — not the CRC and not an XOR proof — is the authoritative integrity and authenticity mechanism in both directions.

Encryption error statuses