Skip to content

Commit 171e265

Browse files
pohlm01pohlm01
committed
Add CESR encoding to mdBook
Signed-off-by: Maximilian Pohl <[email protected]>
1 parent aa118d2 commit 171e265

File tree

3 files changed

+115
-1
lines changed

3 files changed

+115
-1
lines changed

‎.github/workflows/gh-pages.yml

+1-1
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ name: Deploy mdBook site to Pages
66
on:
77
# Runs on pushes targeting the default branch
88
push:
9-
branches: [ $default-branch ]
9+
branches: [ "main" ]
1010

1111
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
1212
permissions:

‎docs/src/SUMMARY.md

+1
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22

33
- [Getting started](./start.md)
44
- [TSP technical specification](./TSP-technical-specification.md)
5+
- [CESR encoding](./cesr.md)
56
- [Web interface](./web-interface.md)
67
- [Command line interface](./cli/index.md)
78
- [Installation](./cli/installation.md)

‎docs/src/cesr.md

+113
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
TSP CESR Encoding
2+
=================
3+
4+
CESR Code Tables
5+
----------------
6+
Codes used by TSP that are already in the CESR draft:
7+
8+
| Code | Description | Code Length | Count Length | Total Length |
9+
|------|--------------------|-------------|--------------|--------------|
10+
| I | SHA-256 Digest | | 1 | 44 |
11+
| F | Blake2b256 Digest | | 1 | 44 |
12+
| 0A | 128 bit Nonce | | 2 | 24 |
13+
| 0B | Ed25519 signature | | 2 | 88 |
14+
15+
Fixed-length codes introduced by TSP:
16+
17+
| Code | Description | Code Length | Count Length | Total Length |
18+
|------|-------------|-------------|--------------|--------------|
19+
| X | Type code | | 1 | 4 |
20+
21+
Variable-length codes introduces by TSP (note: this just introduces the code "B", "C" and "VID", the length of the table
22+
below is caused by the regular CESR encoding scheme for variable length codes).
23+
24+
The type for "VID" is temporary, pending a decision on how to choose/encode VID types; but the code for "VID" dictates
25+
that only a "large" encoding is available. For non-post-quantum, non-`did:peer` VID's, a shorter encoding will usually
26+
suffice.
27+
28+
| Code | Description | Code Length | Count Length | Total Length |
29+
|------|----------------------------------|-------------|--------------|--------------|
30+
| 4B | TSP Plaintext Lead Size 0 | 4 | 2 | |
31+
| 5B | TSP Plaintext Lead Size 1 | 4 | 2 | |
32+
| 6B | TSP Plaintext Lead Size 2 | 4 | 2 | |
33+
| 7AAB | TSP Large Plaintext Lead Size 0 | 8 | 4 | |
34+
| 8AAB | TSP Large Plaintext Lead Size 1 | 8 | 4 | |
35+
| 9AAB | TSP Large Plaintext Lead Size 2 | 8 | 4 | |
36+
| 4C | TSP Ciphertext Lead Size 0 | 4 | 2 | |
37+
| 5C | TSP Ciphertext Lead Size 1 | 4 | 2 | |
38+
| 6C | TSP Ciphertext Lead Size 2 | 4 | 2 | |
39+
| 7AAC | TSP Large Ciphertext Lead Size 0 | 8 | 4 | |
40+
| 8AAC | TSP Large Ciphertext Lead Size 1 | 8 | 4 | |
41+
| 9AAC | TSP Large Ciphertext Lead Size 2 | 8 | 4 | |
42+
| 7VID | TSP Verifiable ID Lead Size 0 | 8 | 4 | |
43+
| 8VID | TSP Verifiable ID Lead Size 1 | 8 | 4 | |
44+
| 9VID | TSP Verifiable ID Lead Size 2 | 8 | 4 | |
45+
46+
Framing codes introduces by TSP:
47+
48+
| Code | Description | Code Length | Count Length | Total Length |
49+
|------|-----------------------------|-------------|--------------|--------------|
50+
| -E## | TSP Encrypt&Signed Envelope | 4 | 2 | 4 |
51+
| -S## | TSP Signed-Only Envelope | 4 | 2 | 4 |
52+
| -I## | TSP Hop List | 4 | 2 | 4 |
53+
| -Z## | TSP Payload | 4 | 2 | 4 |
54+
55+
TSP Message format
56+
------------------
57+
A encrypted TSP message is encoded as:
58+
59+
<ETS-ENVELOPE> <TSP-CIPHERTEXT> <SIGNATURE>
60+
61+
a non-encrypted TSP message is encoded as:
62+
63+
<S-ENVELOPE> <TSP-PLAINTEXT> <SIGNATURE>
64+
65+
where,
66+
67+
ETS-ENVELOPE ::= -E01 Xvvv Xttt <SENDER-VID> <RECEIVER-VID> <OPTIONAL:TSP-PLAINTEXT>
68+
S-ENVELOPE ::= -S01 Xvvv Xttt <SENDER-VID> <OPTIONAL:RECEIVER-VID>
69+
70+
vvv contains the two-byte "major.minor" version of TSP (currently "0.0").
71+
ttt contains a two-byte "encryption `scheme.signature` scheme" type indicator:
72+
73+
encryption scheme\
74+
0 — Unencrypted (for "S" envelopes" only)\
75+
1 — HPKE in Auth mode\
76+
2 — HPKE in Base mode with ESSR\
77+
3 — Libsodium in Auth mode\
78+
4 — Libsodium in ESSR mode
79+
80+
Specifying an encryption scheme in an "S" envelope is technically an error (since there will be no ciphertext anyway)
81+
82+
signature scheme\
83+
0 - Unsigned (Reserved for future use)\
84+
1 - Ed25519
85+
86+
A `TSP-CIPHERTEXT` must, after successful decryption, have one of the two encodings:
87+
88+
AUTH-PAYLOAD ::= -Z01 Xppp <PAYLOAD>
89+
ESSR-PAYLOAD ::= -Z02 <SENDER-VID> Xppp <PAYLOAD>
90+
91+
where ppp contains a two-byte "type.subtype" indicator of the control fields present in the
92+
payload, which currently are:
93+
94+
| type.subtype | description | `PAYLOAD` (after decrypting) |
95+
|--------------|--------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
96+
| 0.0 | generic message | `<TSP-PLAINTEXT>` for direct, <br> `-I## <VID> <VID>... <TSP-PLAINTEXT>` for routed, with the plaintext holding the tsp message |
97+
| 0.1 | nested message | `<TSP-PLAINTEXT>` <br> the plaintext holds a (signed, or signed-and-encrypted) TSP message |
98+
| 0.1 | routed message | |
99+
| 1.0 | NEW_REL | `<NONCE>` |
100+
| 1.1 | NEW_REL_REPLY | `<DIGEST>` |
101+
| 1.2 | NEW_NEST_REL | `<TSP-PLAINTEXT> <NONCE>` <br> the plaintext holds a signed-only TSP message where the sender field has the new nested VID, and an empty receiver |
102+
| 1.3 | NEW_NEST_REL_REPLY | `<TSP-PLAINTEXT> <DIGEST>` <br> the plaintext holds a signed-only TSP message where the sender field has the new nested VID, and the receiver is the nested VID of the other party |
103+
| 1.4 | NEW_REFER_REL | `<DIGEST>` `<VID>` |
104+
| 1.5 | 3P_REFER_REL | `<VID>` |
105+
| 1.255 | REL_CANCEL | `<DIGEST>` |
106+
107+
QUESTIONS FOR THE SPEC
108+
----------------------
109+
110+
* Do we really need a CESR frame indicator to differentiate `S` envelopes from `ETS` envelopes?
111+
112+
* How do parties decide which `DIGEST` to use for creating the "thread-id"? (An initiating party has no way of
113+
communicating what digest it wants to use, and it's inefficient to use all possible hash functions at this stage)

0 commit comments

Comments
 (0)