]> Cypherpunks repositories - keks.git/commitdiff
Proper node descriptions
authorSergey Matveev <stargrave@stargrave.org>
Fri, 14 Feb 2025 09:37:04 +0000 (12:37 +0300)
committerSergey Matveev <stargrave@stargrave.org>
Fri, 14 Feb 2025 09:40:13 +0000 (12:40 +0300)
spec/cm/encrypted.texi
spec/cm/hashed.texi
spec/cm/index.texi
spec/cm/prv.texi
spec/cm/pub.texi
spec/cm/signed.texi
spec/encoding/blob.texi
spec/encoding/index.texi
spec/encoding/magic.texi
spec/encoding/table.texi

index 6b7c22673c798880a7e9e1e432d7501ad99927fb9a255f102f3ad345241b4fb2..cd2d0560c8532b0beda4541ff85504c1da28f74b249d6f7fc11812f41536b81f 100644 (file)
@@ -1,8 +1,9 @@
 @node cm-encrypted
-@cindex cm-encrypted
-@section cm-encrypted format
+@nodedescription Encrypted messages
+@cindex cm/encrypted
+@section cm/encrypted format
 
-Stored in a file, it should begin with "cm/encrypted" @ref{Magic, magic}.
+Stored in a file, it should begin with "cm/encrypted" @ref{MAGIC, magic}.
 
 @verbatiminclude cm/encrypted.cddl
 
@@ -30,7 +31,8 @@ side.
 
 @node cm-encrypted-chacha20poly1305
 @cindex cm-encrypted-chacha20poly1305
-@subsection Encrypted data with ChaCha20-Poly1305 DEM
+@nodedescription cm/encrypted with ChaCha20-Poly1305 DEM
+@subsection cm/encrypted with ChaCha20-Poly1305 DEM
 
     @code{/dem/a} equals to "chacha20poly1305".
 
@@ -56,7 +58,8 @@ ChaCha20-Poly1305(key=KEY, ad="",
 
 @node cm-encrypted-kuznechik-ctracpkm-hmac
 @cindex cm-encrypted-kuznechik-ctracpkm-hmac
-@subsection Encrypted data with Kuznechik-CTR-ACPKM+HMAC DEM
+@nodedescription cm/encrypted with Kuznechik-CTR-ACPKM+HMAC DEM
+@subsection cm/encrypted with Kuznechik-CTR-ACPKM+HMAC DEM
 
     @code{/dem/a} equals to "kuznechik-ctracpkm-hmac".
     CEK is 32+8+32=72 bytes long.
@@ -74,7 +77,8 @@ Kenc || IV || Kauth = CEK
 
 @node cm-encrypted-balloon-blake2b-hkdf
 @cindex cm-encrypted-balloon-blake2b-hkdf
-@subsection Encrypted data with Balloon-BLAKE2b+HKDF KEM
+@nodedescription cm/encrypted with Balloon-BLAKE2b+HKDF KEM
+@subsection cm/encrypted with Balloon-BLAKE2b+HKDF KEM
 
     @code{/kem/*/a} equals to "balloon-blake2b-hkdf".
     Recipient map must also contain additional fields:
@@ -104,7 +108,8 @@ ChaCha20-Poly1305(data=CEK, key=KEK, nonce=12*0x00, ad="")
 
 @node cm-encrypted-gost3410-hkdf-kexp15
 @cindex cm-encrypted-gost3410-hkdf-kexp15
-@subsection Encrypted data with GOST R 34.10+HKDF+KExp15 KEM
+@nodedescription cm/encrypted with GOST R 34.10+HKDF+KExp15 KEM
+@subsection cm/encrypted with GOST R 34.10+HKDF+KExp15 KEM
 
     @code{/kem/*/a} equals to "gost3410-hkdf-kexp15".
     Recipient map must also contain additional fields:
@@ -130,7 +135,8 @@ KExp15(KEKenc, KEKauth, IV, CEK) = CTR(Kenc, CEK || CMAC(Kauth, IV || CEK), IV=I
 
 @node cm-encrypted-sntrup4591761-x25519-hkdf-blake2b
 @cindex cm-encrypted-sntrup4591761-x25519-hkdf-blake2b
-@subsection Encrypted data with SNTRUP4591761+x25519+HKDF-BLAKE2b KEM
+@nodedescription cm/encrypted with SNTRUP4591761+Curve25519+HKDF-BLAKE2b KEM
+@subsection cm/encrypted with SNTRUP4591761+Curve25519+HKDF-BLAKE2b KEM
 
     @code{/kem/*/a} equals to "sntrup4591761-x25519-hkdf-blake2b".
     Recipient public key with
@@ -163,7 +169,8 @@ ChaCha20-Poly1305(data=CEK, key=KEK, nonce=12*0x00, ad="")
 
 @node cm-encrypted-mceliece6960119-x25519-hkdf-shake256
 @cindex cm-encrypted-mceliece6960119-x25519-hkdf-shake256
-@subsection Encrypted data with Classic McEliece 6960119+x25519+HKDF-SHAKE256 KEM
+@nodedescription cm/encrypted with Classic McEliece 6960-119+Curve25519+HKDF-SHAKE256 KEM
+@subsection cm/encrypted with Classic McEliece 6960-119+Curve25519+HKDF-SHAKE256 KEM
 
     @code{/kem/*/a} equals to "mceliece6960119-x25519-hkdf-shake256".
     Recipient public key with
@@ -172,7 +179,7 @@ ChaCha20-Poly1305(data=CEK, key=KEK, nonce=12*0x00, ad="")
 
     Recipient map must also contain additional field:
     @code{/kem/*/encap: bytes} -- concatenation of 194 bytes of
-    Classic McEliece 6960119 ciphertext with 32 bytes of ephemeral
+    Classic McEliece 6960-119 ciphertext with 32 bytes of ephemeral
     Curve25519 public key.
 
     Recipient performs Curve25519 and Classic McEliece computation to
index 785da1f02dbc7c818c42c25ab519ad4e57e4b4a437bd505faa1a62417fa8739f..e0112d723281be4c32a3aeca174e7ec4bced04b80127576f907105e932f78571 100644 (file)
@@ -1,9 +1,12 @@
 @node cm-hashed
-@cindex cm-hashed
-@section cm-hashed format
+@nodedescription Hashed messages
+@cindex cm/hashed
+@section cm/hashed format
 
-Integrity protected container, CMS'es DigestedData analogue.
-Stored in a file, it should begin with "cm/hashed" @ref{Magic, magic}.
+Integrity protected container, analogue to ASN.1-based
+@url{https://datatracker.ietf.org/doc/html/rfc5652, CMS} DigestedData.
+
+Stored in a file, it should begin with "cm/hashed" @ref{MAGIC, magic}.
 
 @verbatiminclude cm/hashed.cddl
 
@@ -21,7 +24,8 @@ algorithms.
 
 @node Merkle hashing
 @cindex Merkle tree
-@cindex Merkle hashing
+@cindex Merkle-tree hashing
+@nodedescription Merkle-tree based hashing
 @subsection Merkle-tree based hashing
 
     Merkle trees are very convenient way to parallelise data hashing.
@@ -32,7 +36,8 @@ algorithms.
 
 @node cm-hashed-blake2b
 @cindex cm-hashed-blake2b
-@subsection Hashed data with BLAKE2b
+@nodedescription cm/hashed with BLAKE2b
+@subsection cm/hashed with BLAKE2b
 
     @url{https://www.blake2.net/, BLAKE2b} with
     512-bit output has @code{blake2b} algorithm identifier.
@@ -41,7 +46,8 @@ algorithms.
 
 @node cm-hashed-blake2b-merkle
 @cindex cm-hashed-blake2b-merkle
-@subsection Hashed data with BLAKE2b in Merkle-tree mode
+@nodedescription cm/hashed with BLAKE2b in Merkle-tree mode
+@subsection cm/hashed with BLAKE2b in Merkle-tree mode
 
     BLAKE2b-512 is initialised with either "LEAF" or "NODE" keys,
     instead of using @code{0x00}/@code{0x01} constants prepending to the
@@ -52,14 +58,16 @@ algorithms.
 
 @node cm-hashed-blake3
 @cindex cm-hashed-blake3
-@subsection Hashed data with BLAKE3
+@nodedescription cm/hashed with BLAKE3
+@subsection cm/hashed with BLAKE3
 
     @url{https://github.com/BLAKE3-team/BLAKE3/, BLAKE3} with fixed
     256-bit output has @code{blake3} algorithm identifier.
 
 @node cm-hashed-sha2
 @cindex cm-hashed-sha2
-@subsection Hashed data with SHA2
+@nodedescription cm/hashed with SHA2
+@subsection cm/hashed with SHA2
 
     SHA2-256 has @code{sha2-256} algorithm identifier.
 
@@ -67,7 +75,8 @@ algorithms.
 
 @node cm-hashed-shake
 @cindex cm-hashed-shake
-@subsection Hashed data with SHAKE
+@nodedescription cm/hashed with SHAKE
+@subsection cm/hashed with SHAKE
 
     @url{https://keccak.team/, SHAKE} XOF function with fixed
     256 (SHAKE128) or 512 (SHAKE256) bit output.
@@ -76,7 +85,8 @@ algorithms.
 
 @node cm-hashed-shake-merkle
 @cindex cm-hashed-shake-merkle
-@subsection Hashed data with SHAKE in Merkle-tree mode
+@nodedescription cm/hashed with SHAKE in Merkle-tree mode
+@subsection cm/hashed with SHAKE in Merkle-tree mode
 
     cSHAKE with either "LEAF" or "NODE" personalisation strings are used
     instead of @code{0x00}/@code{0x01} constants prepending to the
@@ -87,7 +97,8 @@ algorithms.
 
 @node cm-hashed-skein512
 @cindex cm-hashed-skein512
-@subsection Hashed data with Skein-512
+@nodedescription cm/hashed with Skein-512
+@subsection cm/hashed with Skein-512
 
     512-bit @url{https://www.schneier.com/academic/skein/, Skein-512} hash.
 
@@ -95,7 +106,8 @@ algorithms.
 
 @node cm-hashed-gost3411
 @cindex cm-hashed-gost3411
-@subsection Hashed data with GOST R 34.11-2012
+@nodedescription cm/hashed with GOST R 34.11-2012
+@subsection cm/hashed with GOST R 34.11-2012
 
     Streebog must be big-endian serialised.
 
@@ -103,14 +115,16 @@ algorithms.
 
 @node cm-hashed-gost3411-merkle
 @cindex cm-hashed-gost3411-merkle
-@subsection Hashed data with GOST R 34.11-2012 in Merkle tree mode
+@nodedescription cm/hashed with GOST R 34.11-2012 in Merkle tree mode
+@subsection cm/hashed with GOST R 34.11-2012 in Merkle tree mode
 
     @code{streebog256-merkle}, @code{streebog512-merkle} algorithm
     identifiers are used.
 
 @node cm-hashed-xxh3-128
 @cindex cm-hashed-xxh3-128
-@subsection Hashed data with XXH3-128
+@nodedescription cm/hashed with XXH3-128
+@subsection cm/hashed with XXH3-128
 
     128-bit @url{https://xxhash.com/, XXH3} hash must be big-endian encoded.
 
index e00c77fdbd6e21e12d3279f5efbd5c02cf977ce9521834c280f448e836254288..c86999a74e75951ab6a1ae5bfbe99d6c4c77815deb6c9427061211adc7a1561d 100644 (file)
@@ -1,4 +1,7 @@
 @node CM
+@cindex CM
+@cindex cryptographic messages
+@nodedescription Cryptographic messages
 @unnumbered Cryptographic messages
 
 Here are some suggested formats for use with cryptographic messages.
index 3060a545c1798b3900518c6a80a24341e5827158d5e85d265856a0b57b09b4ff..ad2b472ab818bc2c678053d265a0dad5080caa183fa3f1ceb7a4daa000570619 100644 (file)
@@ -1,16 +1,18 @@
 @node cm-prv
-@cindex cm-prv
-@section cm-prv format
+@nodedescription Private keys
+@cindex cm/prv
+@section cm/prv format
 
 Private key container.
 
 @verbatiminclude cm/prv.cddl
 
-Stored in a file, it should begin with "cm/prv" @ref{Magic, magic}.
+Stored in a file, it should begin with "cm/prv" @ref{MAGIC, magic}.
 
 @node cm-prv-gost3410
 @cindex cm-prv-gost3410
-@subsection Private key with GOST R 34.10-2012
+@nodedescription cm/prv with GOST R 34.10-2012
+@subsection cm/prv with GOST R 34.10-2012
 
     Big-endian private key representation must be used.
 
@@ -19,7 +21,8 @@ Stored in a file, it should begin with "cm/prv" @ref{Magic, magic}.
 
 @node cm-prv-ed25519-blake2b
 @cindex cm-prv-ed25519-blake2b
-@subsection Private key with Ed25519-BLAKE2b
+@nodedescription cm/prv with Ed25519-BLAKE2b
+@subsection cm/prv with Ed25519-BLAKE2b
 
     32-byte Ed25519 private key is used, as described in
     @url{https://datatracker.ietf.org/doc/html/rfc8032, EdDSA} RFC.
@@ -30,7 +33,8 @@ Stored in a file, it should begin with "cm/prv" @ref{Magic, magic}.
 
 @node cm-prv-sntrup4591761-x25519
 @cindex cm-prv-sntrup4591761-x25519
-@subsection Private key with SNTRUP4591761+X25519
+@nodedescription cm/prv with SNTRUP4591761+Curve25519
+@subsection cm/prv with SNTRUP4591761+Curve25519
 
     Concatenation of Streamlined NTRU Prime 4591^761's 1600-byte private key
     and Curve25519's 32-byte one.
@@ -39,9 +43,10 @@ Stored in a file, it should begin with "cm/prv" @ref{Magic, magic}.
 
 @node cm-prv-mceliece6960119-x25519
 @cindex cm-prv-mceliece6960119-x25519
-@subsection Private key with Classic McEliece 6960119+X25519
+@nodedescription cm/prv with Classic McEliece 6960-119+Curve25519
+@subsection cm/prv with Classic McEliece 6960-119+Curve25519
 
-    Concatenation of Classic McEliece 6960119 13948-byte private key
+    Concatenation of Classic McEliece 6960-119 13948-byte private key
     and Curve25519's 32-byte one.
 
     @code{mceliece6960119-x25519} algorithm identifier is used.
index 85e5f17be98fdce04c4e3e93e87d30648fb3b29c2c37615925af163b0b5d6767..60489dfa9cedf9201fc293d6977b132ed967698f3e70a255946e8b65e42f9c5b 100644 (file)
@@ -1,9 +1,11 @@
 @node cm-pub
-@cindex cm-pub
-@section cm-pub format
+@nodedescription Public keys
+@cindex cm/pub
+@section cm/pub format
 
 Public key is the @code{@ref{cm-signed}} structure.
-Stored in a file, it should begin with "cm/pub" @ref{Magic, magic}.
+
+Stored in a file, it should begin with "cm/pub" @ref{MAGIC, magic}.
 
 Its @code{/load/t} equals to @code{pub}.
 @code{/load/v} contains @code{cm-pub-load}:
@@ -95,7 +97,8 @@ Example minimal public key may look like:
 
 @node cm-pub-gost3410
 @cindex cm-pub-gost3410
-@subsection Public key with GOST R 34.10-2012
+@nodedescription cm/pub with GOST R 34.10-2012
+@subsection cm/pub with GOST R 34.10-2012
 
 GOST R 34.10-2012 must be used with Streebog (GOST R 34.11-2012) hash
 function. Its digest must be big-endian serialised. Public key must be
@@ -109,7 +112,8 @@ Streebog-256 hash.
 
 @node cm-pub-ed25519-blake2b
 @cindex cm-pub-ed25519-blake2b
-@subsection Public key with Ed25519-BLAKE2b
+@nodedescription cm/pub with Ed25519-BLAKE2b
+@subsection cm/pub with Ed25519-BLAKE2b
 
 Same calculation and serialisation rules must be used as with
 @code{@ref{cm-signed-ed25519-blake2b}}.
@@ -121,7 +125,8 @@ Algorithm identifier for the public key: @code{ed25519ph-blake2b}.
 
 @node cm-pub-sntrup4591761-x25519
 @cindex cm-pub-sntrup4591761-x25519
-@subsection Public key with SNTRUP4591761+X25519
+@nodedescription cm/pub with SNTRUP4591761+Curve25519
+@subsection cm/pub with SNTRUP4591761+Curve25519
 
 Combined Streamlined NTRU Prime 4591^761 and Curve25519 public keys are
 used for KEM purposes, so should have "kem" key usage set.
@@ -135,7 +140,8 @@ or 256 bit output length specified.
 
 @node cm-pub-mceliece6960119-x25519
 @cindex cm-pub-mceliece6960119-x25519
-@subsection Public key with Classic McEliece 6960-119+x25519
+@nodedescription cm/pub with Classic McEliece 6960-119+Curve25519
+@subsection cm/pub with Classic McEliece 6960-119+Curve25519
 
 Combined Classic McEliece 6960-119 and Curve25519 public keys are used
 for KEM purposes, so should have "kem" key usage set.
index 5979a1381876e34f20fe5c31efaec842b33ad714d34ebed7282b3000cc3a76e9..b0634e38f09bd293047c6e64537d4ef02e80355daf6ec7b8858ab78f43283e1e 100644 (file)
@@ -1,11 +1,12 @@
 @node cm-signed
-@cindex cm-signed
-@section cm-signed format
+@nodedescription Signed messages
+@cindex cm/signed
+@section cm/signed format
 
-That resembles @url{https://datatracker.ietf.org/doc/html/rfc5652, CMS}
-(PKCS#7) ASN.1-based format.
+Signed container, analogue to ASN.1-based
+@url{https://datatracker.ietf.org/doc/html/rfc5652, CMS} SignedData.
 
-Stored in a file, it should begin with "cm/signed" @ref{Magic, magic},
+Stored in a file, it should begin with "cm/signed" @ref{MAGIC, magic},
 unless it is a @ref{cm-pub, public key}.
 
 @verbatiminclude cm/signed.cddl
@@ -48,7 +49,8 @@ recipient's public key id(s).
 
 @node cm-signed-gost3410
 @cindex cm-signed-gost3410
-@subsection Signed data with GOST R 34.10-2012
+@nodedescription cm/signed with GOST R 34.10-2012
+@subsection cm/signed with GOST R 34.10-2012
 
     GOST R 34.10-2012 must be used with Streebog (GOST R 34.11-2012)
     hash function. Its digest must be big-endian serialised. Signature
@@ -59,7 +61,8 @@ recipient's public key id(s).
 
 @node cm-signed-gost3410-merkle
 @cindex cm-signed-gost3410-merkle
-@subsection Signed data with GOST R 34.10-2012 with Merkle-tree hashing
+@nodedescription cm/signed with GOST R 34.10-2012 with Merkle-tree hashing
+@subsection cm/signed with GOST R 34.10-2012 with Merkle-tree hashing
 
     @ref{cm-hashed-gost3411-merkle} Merkle-tree hashing is used.
 
@@ -70,7 +73,8 @@ recipient's public key id(s).
 @node cm-signed-ed25519-blake2b
 @cindex cm-signed-ed25519-blake2b
 @cindex cm-signed-ed25519ph-blake2b
-@subsection Signed data with Ed25519-BLAKE2b
+@nodedescription cm/signed with Ed25519-BLAKE2b
+@subsection cm/signed with Ed25519-BLAKE2b
 
     @url{https://datatracker.ietf.org/doc/html/rfc8032, EdDSA} with
     Edwards25519 is used similarly as in RFC 8032. But BLAKE2b is used
@@ -88,7 +92,8 @@ recipient's public key id(s).
 
 @node cm-signed-ed25519ph-blake2b-merkle
 @cindex cm-signed-ed25519ph-blake2b-merkle
-@subsection Signed data with Ed25519-BLAKE2b with Merkle-tree hashing
+@nodedescription cm/signed with Ed25519-BLAKE2b with Merkle-tree hashing
+@subsection cm/signed with Ed25519-BLAKE2b with Merkle-tree hashing
 
     @ref{cm-hashed-blake2b-merkle} Merkle-tree hashing is used.
     HashEdDSA mode is used with @code{ed25519ph-blake2b-merkle}
index 302a5ea14b7f944289c47e151a5254f924791c859944540c224b0677d4be7944..bedc7244f1a8d7ca6c31b46c1e2ac3c2ecae6e66afb1b0dea3150363b2eec91d 100644 (file)
@@ -1,9 +1,9 @@
-@node Blobs
+@node BLOB
 @cindex BLOB
 @cindex chunk
-@section Blobs
+@section BLOB
 
-Blob (binary large object) allows you to transfer binary data in chunks,
+BLOB (binary large object) allows you to transfer binary data in chunks,
 in a streaming way, when data may not fit in memory.
 
 64-bit big-endian integer follows the BLOB tag, setting the following
index 2522627ef6d12f35cc13c08bf7b5c34ce8d9fe1161765b52304e30b5ea6ee8e4..e8ab4b56a582176fcb8ff2164141712282dba3498e68bf356b780ca1eb71bdb0 100644 (file)
@@ -20,7 +20,7 @@ Possible values for the tag:
 @item 008 @tab 08 @tab @code{00001000} @tab 0 @tab @ref{LIST}
 @item 009 @tab 09 @tab @code{00001001} @tab 0 @tab @ref{MAP}
 @item 010 @tab 0A @tab @code{00001010} @tab
-@item 011 @tab 0B @tab @code{00001011} @tab 8+~ @tab @ref{Blobs, BLOB}
+@item 011 @tab 0B @tab @code{00001011} @tab 8+~ @tab @ref{BLOB}
 @item 012 @tab 0C @tab @code{00001100} @tab 1+~ @tab @ref{Integers, +INT}
 @item 013 @tab 0D @tab @code{00001101} @tab 1+~ @tab @ref{Integers, -INT}
 @item [...]
@@ -34,7 +34,7 @@ Possible values for the tag:
 @item 025 @tab 19 @tab @code{00011001} @tab 12 @tab @ref{TAI64, TAI64N}
 @item 026 @tab 1A @tab @code{00011010} @tab 16 @tab @ref{TAI64, TAI64NA}
 @item [...]
-@item 075 @tab 4B @tab @code{01001011} @tab 15 @tab @ref{Magic, MAGIC}
+@item 075 @tab 4B @tab @code{01001011} @tab 15 @tab @ref{MAGIC}
 @item [...]
 @item 128 @tab 80 @tab @code{10LLLLLL} @tab 0 @tab @ref{Strings, BIN(len=0)}
 @item [...]
index 365bd4fb6b4c2c0bb874e31e598900d88064a7a1382e4a4a61edf733850ba938..1a885cdfdd3ab3912a8f083653a31d4fc01187a57b151004cd0a399a0eaa5152 100644 (file)
@@ -1,6 +1,6 @@
-@node Magic
+@node MAGIC
 @cindex MAGIC
-@section Magic
+@section MAGIC
 
 MAGIC is an atom holding magic number/string aimed to identify the data
 following it. It is a concatenation of ASCII("KEKS") and 12-byte magic,
index 96aa26ff21f8546c8794c874138e54ed021db24d6e3f98f4a3dbff4bf6a28e0f..e96f6f1e225a1689dd6428543530f4a8e483d3b16ffff96eef922c3ad2ac8117 100644 (file)
@@ -15,7 +15,7 @@
 @item 008 @tab 08 @tab @code{00001000} @tab 0 @tab @ref{LIST}
 @item 009 @tab 09 @tab @code{00001001} @tab 0 @tab @ref{MAP}
 @item 010 @tab 0A @tab @code{00001010} @tab 0 @tab
-@item 011 @tab 0B @tab @code{00001011} @tab 8+~ @tab @ref{Blobs, BLOB}
+@item 011 @tab 0B @tab @code{00001011} @tab 8+~ @tab @ref{BLOB}
 @item 012 @tab 0C @tab @code{00001100} @tab 1+~ @tab @ref{Integers, +INT}
 @item 013 @tab 0D @tab @code{00001101} @tab 1+~ @tab @ref{Integers, -INT}
 @item 014 @tab 0E @tab @code{00001110} @tab 0 @tab
@@ -79,7 +79,7 @@
 @item 072 @tab 48 @tab @code{01001000} @tab 0 @tab
 @item 073 @tab 49 @tab @code{01001001} @tab 0 @tab
 @item 074 @tab 4A @tab @code{01001010} @tab 0 @tab
-@item 075 @tab 4B @tab @code{01001011} @tab 15 @tab @ref{Magic, MAGIC}
+@item 075 @tab 4B @tab @code{01001011} @tab 15 @tab @ref{MAGIC}
 @item 076 @tab 4C @tab @code{01001100} @tab 0 @tab
 @item 077 @tab 4D @tab @code{01001101} @tab 0 @tab
 @item 078 @tab 4E @tab @code{01001110} @tab 0 @tab