Sealed-session keys and frame MACs

Test vectors: Sealed-session keys and frame MACs. Shown here as it is in conformance/vectors/seal.json.

Generated at build time from conformance/vectors/seal.json.

Protocol 0.1. Covers: SPEC.md section 5, "Sealed sessions".

Download seal.json: the file itself, as the conformance suite reads it.

How to use it #

Derive th, kPeer and kHub from key, nonce, cnonce, challengeText, helloText, welcomeText; seal the peerToHub messages in order from sequence 0 and compare with wire / wireHex; do the same with hubToPeer; open the wire messages and expect the payloads. macOnly gives MACs at large sequence numbers. illFormed must never be sealed or opened.

Formula #

Text
th = b64url(SHA-256(L(c) || c || L(h) || h || L(w) || w)), with c, h, w the UTF-8 bytes of challengeText, helloText, welcomeText and L(x) the byte length of x as an unsigned 32-bit big-endian integer
k = HMAC-SHA256(key, context + "\n" + nonce + "\n" + cnonce + "\n" + th), context "reins.v1.seal.peer" (peer sends) or "reins.v1.seal.hub" (hub sends)
mac = HMAC-SHA256(k, u64be(seq) || kind || payload), kind 0x74 text, 0x62 binary; seq counts from 0 per direction and is never sent
sealed text = b64url(mac) + "." + text; sealed binary = bytes || mac

Notes #

Everything here is stated in SPEC 5: the HMAC key and message are UTF-8 bytes, th is base64url text, k is the raw 32-byte HMAC output used as the key of the frame MAC, and the payload of a text message is its UTF-8 bytes. macOnly entries use sequence numbers that the public API cannot reach (the counter starts at 0 and is internal); they are here for other implementations. illFormed is a text with a lone surrogate (written as a JSON escape), which must never be sealed or opened.

Fixed values #

key value
key HebNZMN9EImpyoAZxAMca3WUyq-yG5DAkpSIfXpS294
nonce X4jwsNU4ZbyLfcfpTAjqL6YTHwJFRJnhOkaAiob2bbU
cnonce WI8VBFzQHSRrn0GqeV7pEYkNsGcnJACIX8XysTe0wuc
challengeText {"t":"challenge","v":["0.1"],"nonce":"X4jwsNU4ZbyLfcfpTAjqL6YTHwJFRJnhOkaAiob2bbU","hub":{"name":"conformance-hub","ver":"0.1.0"}}
helloText {"t":"hello","v":"0.1","role":"agent","name":"conformance","cnonce":"WI8VBFzQHSRrn0GqeV7pEYkNsGcnJACIX8XysTe0wuc","auth":{"kid":"default","proof":"nD89mHMkpZjv1bORaBzPNGoMXilSlR-6cu-JIzNjpZs"}}
welcomeText {"t":"welcome","v":"0.1","session":"a1","role":"agent","limits":{"maxText":262144,"maxBinary":16384,"heartbeatMs":15000,"reqTimeoutMs":15000,"consentTimeoutMs":60000},"proof":"BYpxxhfA4x9Xak04Rvey74cSQOaBtXiYKY7E3A7N3R0"}
th 2F9jYemeRLbGr6ALI0IOJOPEIXO3o41FVekTBjdE1TI
kPeerHex f114ccc730ba2b425779b0eccfd1b11d4234aea34fabf0aaa4f2da1e293cdf2d
kHubHex 64b9cbd92979ff0f0464dbe64774df9aefc7adb832a44b46de69179901951231
illFormed {"t":"ping","ts":1,"x":"�"}

peerToHub #

4 cases.

JSON
[
  {
    "seq": 0,
    "kind": "text",
    "text": "{\"t\":\"ping\",\"ts\":1}",
    "mac": "MT5ASRv9RnmesIfIwUME6mjptWyUOl8DiNqJishP9-U",
    "wire": "MT5ASRv9RnmesIfIwUME6mjptWyUOl8DiNqJishP9-U.{\"t\":\"ping\",\"ts\":1}"
  },
  {
    "seq": 1,
    "kind": "text",
    "text": "{\"t\":\"req\",\"id\":1,\"m\":\"hub.info\"}",
    "mac": "F_Hb4dRSIWZ_xIko6qRNYiwcWyhJoo5IUsLVBTenlSw",
    "wire": "F_Hb4dRSIWZ_xIko6qRNYiwcWyhJoo5IUsLVBTenlSw.{\"t\":\"req\",\"id\":1,\"m\":\"hub.info\"}"
  },
  {
    "seq": 2,
    "kind": "binary",
    "hex": "01000100050000000100ff7f00401000",
    "mac": "LQYHA9iIqSP1Lknk2rQQFKR0R3I3DRixmTN3wm8e3Xc",
    "wireHex": "01000100050000000100ff7f004010002d060703d888a923f52e49e4dab41014a4744772370d18b1993377c26f1edd77"
  },
  {
    "seq": 3,
    "kind": "text",
    "text": "{\"t\":\"req\",\"id\":2,\"m\":\"act\",\"p\":{\"s\":\"s1\",\"a\":\"note.add\",\"args\":{\"text\":\"café ☕\"}}}",
    "mac": "F78b1FT6vhUYw-5ePVQKY-jmIeD3nlTfqBI3nUl85VI",
    "wire": "F78b1FT6vhUYw-5ePVQKY-jmIeD3nlTfqBI3nUl85VI.{\"t\":\"req\",\"id\":2,\"m\":\"act\",\"p\":{\"s\":\"s1\",\"a\":\"note.add\",\"args\":{\"text\":\"café ☕\"}}}"
  }
]

hubToPeer #

2 cases.

JSON
[
  {
    "seq": 0,
    "kind": "text",
    "text": "{\"t\":\"pong\",\"ts\":1}",
    "mac": "vU_rszPksyQjcw4gxsavf9TkI4eF3ClUeR13ACBJyOA",
    "wire": "vU_rszPksyQjcw4gxsavf9TkI4eF3ClUeR13ACBJyOA.{\"t\":\"pong\",\"ts\":1}"
  },
  {
    "seq": 1,
    "kind": "text",
    "text": "{\"t\":\"res\",\"re\":1,\"ok\":true,\"r\":{}}",
    "mac": "ZLgxlMD0TRpWDjYfFTlGfDeyVOXuBcvFbyCtBs9eEIk",
    "wire": "ZLgxlMD0TRpWDjYfFTlGfDeyVOXuBcvFbyCtBs9eEIk.{\"t\":\"res\",\"re\":1,\"ok\":true,\"r\":{}}"
  }
]

macOnly #

3 cases.

JSON
[
  {
    "direction": "peerToHub",
    "seq": 255,
    "kind": "text",
    "text": "{\"t\":\"ping\",\"ts\":2}",
    "mac": "N421NL3hMwwef2S_TH_1lBBCz-qcE8au7U4zJnXL17s",
    "wire": "N421NL3hMwwef2S_TH_1lBBCz-qcE8au7U4zJnXL17s.{\"t\":\"ping\",\"ts\":2}"
  },
  {
    "direction": "peerToHub",
    "seq": 4294967303,
    "kind": "text",
    "text": "{\"t\":\"ping\",\"ts\":3}",
    "mac": "HBdriryj-F4yJqfDt35-WrHYtatYBFX6vpqR7oSUfbY",
    "wire": "HBdriryj-F4yJqfDt35-WrHYtatYBFX6vpqR7oSUfbY.{\"t\":\"ping\",\"ts\":3}"
  },
  {
    "direction": "hubToPeer",
    "seq": 1099511627776,
    "kind": "binary",
    "hex": "01000100050000000100ff7f00401000",
    "mac": "9FdNozTl7LLWZdMc0hR7_eAVGaj7iaSjbmLrjfdwnE4",
    "wireHex": "01000100050000000100ff7f00401000f4574da334e5ecb2d665d31cd2147bfde01519a8fb89a4a36e62eb8df7709c4e"
  }
]

Generated by conformance/tools/make-vectors.mjs from the formulas in the specification, with node:crypto only.