From 8728ce989cf338672db15df337b8ae33d61c025c9866347fff74e59a0034ae23 Mon Sep 17 00:00:00 2001 From: Sergey Matveev Date: Fri, 14 Feb 2025 12:37:04 +0300 Subject: [PATCH] Proper node descriptions --- spec/cm/encrypted.texi | 27 +++++++++++++++--------- spec/cm/hashed.texi | 44 ++++++++++++++++++++++++++-------------- spec/cm/index.texi | 3 +++ spec/cm/prv.texi | 21 +++++++++++-------- spec/cm/pub.texi | 20 +++++++++++------- spec/cm/signed.texi | 23 +++++++++++++-------- spec/encoding/blob.texi | 6 +++--- spec/encoding/index.texi | 4 ++-- spec/encoding/magic.texi | 4 ++-- spec/encoding/table.texi | 4 ++-- 10 files changed, 98 insertions(+), 58 deletions(-) diff --git a/spec/cm/encrypted.texi b/spec/cm/encrypted.texi index 6b7c226..cd2d056 100644 --- a/spec/cm/encrypted.texi +++ b/spec/cm/encrypted.texi @@ -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 diff --git a/spec/cm/hashed.texi b/spec/cm/hashed.texi index 785da1f..e0112d7 100644 --- a/spec/cm/hashed.texi +++ b/spec/cm/hashed.texi @@ -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. diff --git a/spec/cm/index.texi b/spec/cm/index.texi index e00c77f..c86999a 100644 --- a/spec/cm/index.texi +++ b/spec/cm/index.texi @@ -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. diff --git a/spec/cm/prv.texi b/spec/cm/prv.texi index 3060a54..ad2b472 100644 --- a/spec/cm/prv.texi +++ b/spec/cm/prv.texi @@ -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. diff --git a/spec/cm/pub.texi b/spec/cm/pub.texi index 85e5f17..60489df 100644 --- a/spec/cm/pub.texi +++ b/spec/cm/pub.texi @@ -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. diff --git a/spec/cm/signed.texi b/spec/cm/signed.texi index 5979a13..b0634e3 100644 --- a/spec/cm/signed.texi +++ b/spec/cm/signed.texi @@ -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} diff --git a/spec/encoding/blob.texi b/spec/encoding/blob.texi index 302a5ea..bedc724 100644 --- a/spec/encoding/blob.texi +++ b/spec/encoding/blob.texi @@ -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 diff --git a/spec/encoding/index.texi b/spec/encoding/index.texi index 2522627..e8ab4b5 100644 --- a/spec/encoding/index.texi +++ b/spec/encoding/index.texi @@ -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 [...] diff --git a/spec/encoding/magic.texi b/spec/encoding/magic.texi index 365bd4f..1a885cd 100644 --- a/spec/encoding/magic.texi +++ b/spec/encoding/magic.texi @@ -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, diff --git a/spec/encoding/table.texi b/spec/encoding/table.texi index 96aa26f..e96f6f1 100644 --- a/spec/encoding/table.texi +++ b/spec/encoding/table.texi @@ -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 -- 2.50.0