@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
@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".
@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.
@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:
@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:
@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
@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
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
@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
@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.
@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.
@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
@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.
@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.
@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
@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.
@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.
@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.
@node CM
+@cindex CM
+@cindex cryptographic messages
+@nodedescription Cryptographic messages
@unnumbered Cryptographic messages
Here are some suggested formats for use with cryptographic messages.
@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.
@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.
@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.
@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.
@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}:
@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
@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}}.
@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.
@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.
@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
@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
@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.
@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
@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}
-@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
@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 [...]
@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 [...]
-@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,
@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
@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