@node dem-chapoly-krkc
@cindex dem-chapoly-krkc
-@nodedescription ChaCha20-Poly1305 with key ratcheting and key commitment DEM
-@subsubsection ChaCha20-Poly1305 with key ratcheting and key commitment DEM
+@nodedescription XChaCha20-Poly1305 with key ratcheting and key commitment DEM
+@subsubsection XChaCha20-Poly1305 with key ratcheting and key commitment DEM
@code{cm/encrypted}'s @code{/dem/a} equals to "chapoly-krkc".
Nonce's lowest bit is set only if this is the last chunk we encrypting.
@code{/payload}'s chunk length equals to 128KiB+16+32 bytes.
+
+HKDF is KDF algorithm,
+@url{https://datatracker.ietf.org/doc/html/rfc5869.html, RFC 5869}.
+@url{https://www.blake2.net/, BLAKE2b} is hashing algorithm,
+@url{https://datatracker.ietf.org/doc/html/rfc7693.html, RFC 7693}.
+@url{https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-xchacha, XChaCha20-Poly1305}
+is an authenticated encryption algorithm, extended nonce version of ChaCha20-Poly1305,
+@url{https://datatracker.ietf.org/doc/html/rfc8439.html, RFC 8439}.
CKi = HKDF-Extract(Streebog-512, salt="", ikm=CK{i-1})
Kenc = HKDF-Expand(Streebog-512, prk=CKi,
info="cm/encrypted/kuznechik-ctr-hmac-kr/enc")
+IV = HKDF-Expand(Streebog-512, prk=CKi,
+ info="cm/encrypted/kuznechik-ctr-hmac-kr/iv", len=8)
Kauth || KauthTail = HKDF-Expand(Streebog-512, prk=CKi,
info="cm/encrypted/kuznechik-ctr-hmac-kr/auth")
KauthTail = HKDF-Expand(Streebog-512, prk=CKi,
info="cm/encrypted/kuznechik-ctr-hmac-kr/authTail")
-CT = Kuznechik-CTR(key=Kenc, ctr=0x00, data=chunk)
+CT = Kuznechik-CTR(key=Kenc, ctr=IV, data=chunk)
CT || HMAC(Streebog-256, key={Kauth|KauthTail}, data=CT)
@end verbatim
that it is the last one.
@code{/payload}'s chunk length equals to 128KiB+32 bytes.
+
+HKDF is KDF algorithm,
+@url{https://datatracker.ietf.org/doc/html/rfc5869.html, RFC 5869}.
+HMAC is MAC algorithm,
+@url{https://datatracker.ietf.org/doc/html/rfc2104.html, RFC 2104}.
+Kuznechik is GOST R 34.12-2015 encryption algorithm,
+@url{https://datatracker.ietf.org/doc/html/rfc7801.html, RFC 7801}.
+Streebog is GOST R 34.11-2012 hashing algorithm,
+@url{https://datatracker.ietf.org/doc/html/rfc6986.html, RFC 6986}.
@cindex cm/encrypted
@section cm/encrypted format
+Encrypted container, some kind of analogue to ASN.1-based
+@url{https://datatracker.ietf.org/doc/html/rfc5652, CMS} EnvelopedData,
+@url{https://librepgp.org/, LibrePGP} or
+@url{https://age-encryption.org/, age}.
+
+@itemize
+@item Ability to use multiple recipients
+@item Either passphrase- or public-key based KEMs
+@item Hybrid PQ/T KEMs
+@item Optionally anonymous recipients
+@item Streaming friendly
+@item Ability to parallelise encryption/decryption procedures
+@item Current DEM schemes do explicit key commitment
+@item Current DEM schemes use key ratcheting and rotation
+@end itemize
+
+Currently there is @strong{no} sender authentication! But remember to
+include recipient's public key fingerprint in encrypted signed document
+if you use it.
+
Stored in a file, it should begin with "cm/encrypted" @ref{MAGIC, magic}.
@verbatiminclude cm/encrypted.cddl
@nodedescription cm/hashed with BLAKE2b
@subsection cm/hashed with BLAKE2b
- @url{https://www.blake2.net/, BLAKE2b} with
+ BLAKE2b with
512-bit output has @code{blake2b} algorithm identifier.
256-bit output has @code{blake2b256} algorithm identifier.
+ @url{https://www.blake2.net/, BLAKE2b} is hashing algorithm,
+ @url{https://datatracker.ietf.org/doc/html/rfc7693.html, RFC 7693}.
+
@node cm-hashed-blake2b-merkle
@cindex cm-hashed-blake2b-merkle
@nodedescription cm/hashed with BLAKE2b in Merkle-tree mode
@code{streebog256}, @code{streebog512} algorithm identifiers are used.
+ Streebog is GOST R 34.11-2012 hashing algorithm,
+ @url{https://datatracker.ietf.org/doc/html/rfc6986.html, RFC 6986}.
+
@node cm-hashed-gost3411-merkle
@cindex cm-hashed-gost3411-merkle
@nodedescription cm/hashed with GOST R 34.11-2012 in Merkle tree mode
@end verbatim
@code{/kem/*/cek} is wrapped with @ref{keywrap-xchapoly} mechanism.
+
+HKDF is KDF algorithm,
+@url{https://datatracker.ietf.org/doc/html/rfc5869.html, RFC 5869}.
+@url{https://www.blake2.net/, BLAKE2b} is hashing algorithm,
+@url{https://datatracker.ietf.org/doc/html/rfc7693.html, RFC 7693}.
Sender's ephemeral 512-bit public key.
@end table
-ГОСТ Р 34.10-2012 VKO parameter set A/C ("gost3410-256A", "gost3410-512C")
+GOST R 34.10-2012 VKO parameter set A/C ("gost3410-256A", "gost3410-512C")
must be used for DH operation, with UKM taken from the structure. VKO's
output is 512- or 1024-bit @code{BE(X)||BE(Y)} point. It is used in HKDF
and KExp15 (Р 1323565.1.017) key wrapping algorithm:
@end verbatim
@code{/kem/*/cek} is wrapped with @ref{keywrap-kexp15} mechanism.
+
+HKDF is KDF algorithm,
+@url{https://datatracker.ietf.org/doc/html/rfc5869.html, RFC 5869}.
+Streebog is GOST R 34.11-2012 hashing algorithm,
+@url{https://datatracker.ietf.org/doc/html/rfc6986.html, RFC 6986}.
+GOST R 34.10-2012 is signing/key-aggreement algorithm,
+@url{https://datatracker.ietf.org/doc/html/rfc7091.html, RFC 7091}.
@end verbatim
@code{/kem/*/cek} is wrapped with @ref{keywrap-xchapoly} mechanism.
+
+HKDF is KDF algorithm,
+@url{https://datatracker.ietf.org/doc/html/rfc5869.html, RFC 5869}.
+@url{https://keccak.team/, SHAKE} is a XOF function.
@nodedescription KExp15 key wrapping mechanism
@subsubsection KExp15 key wrapping mechanism
-KExp15 (Р 1323565.1.017) key wrapping mechanism uses GOST (ГОСТ)
+KExp15 (Р 1323565.1.017) key wrapping mechanism uses GOST
cryptography algorithms. KEK is 32+8+32=72 bytes long.
@verbatim
KExp15(Kenc, Kauth, IV, CEK) = Kuznechik-CTR(
Kenc, CEK || Kuznechik-CMAC(Kauth, IV || CEK), IV=IV)
@end verbatim
+
+Kuznechik is GOST R 34.12-2015 encryption algorithm,
+@url{https://datatracker.ietf.org/doc/html/rfc7801.html, RFC 7801}.
+CMAC, OMAC1 is described in GOST R 34.13-2015.
@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
-in @code{BE(X)||BE(Y)} format.
+ 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 in @code{BE(X)||BE(Y)} format.
-Algorithm identifiers for the public key: @code{gost3410-256A},
-@code{gost3410-512C}.
+ Algorithm identifiers for the public key: @code{gost3410-256A},
+ @code{gost3410-512C}.
-Public key's fingerprint should be calculated using big-endian
-Streebog-256 hash.
+ Public key's fingerprint should be calculated using big-endian
+ Streebog-256 hash.
+
+ Streebog is GOST R 34.11-2012 hashing algorithm,
+ @url{https://datatracker.ietf.org/doc/html/rfc6986.html, RFC 6986}.
+ GOST R 34.10-2012 is signing/key-aggreement algorithm,
+ @url{https://datatracker.ietf.org/doc/html/rfc7091.html, RFC 7091}.
@node cm-pub-ed25519-blake2b
@cindex cm-pub-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}}.
+ Same calculation and serialisation rules must be used as with
+ @code{@ref{cm-signed-ed25519-blake2b}}.
+
+ Public key's fingerprint should be calculated using BLAKE2b hash
+ with 256 bit output length specified.
-Public key's fingerprint should be calculated using BLAKE2b hash with
-256 bit output length specified.
+ Algorithm identifier for the public key: @code{ed25519-blake2b}.
-Algorithm identifier for the public key: @code{ed25519-blake2b}.
+ @url{https://cr.yp.to/ecdh.html, X2559} is key-agreement algorithm,
+ @url{https://datatracker.ietf.org/doc/html/rfc7748.html, RFC 7748}.
+ @url{https://www.blake2.net/, BLAKE2b} is hashing algorithm,
+ @url{https://datatracker.ietf.org/doc/html/rfc7693.html, RFC 7693}.
@node cm-pub-sntrup4591761-x25519
@cindex cm-pub-sntrup4591761-x25519
@nodedescription cm/pub with SNTRUP4591761+X25519
@subsection cm/pub with SNTRUP4591761+X25519
-Combined Streamlined NTRU Prime 4591^761 and X25519 public keys are
-used for KEM purposes, so should have "kem" key usage set.
+ Combined Streamlined NTRU Prime 4591^761 and X25519 public keys are
+ used for KEM purposes, so should have "kem" key usage set.
-Its algorithm identifier is @code{sntrup4591761-x25519}. Its public key
-value is a concatenation of 1218-byte SNTRUP4591761 public key and
-32-byte X25519 one.
+ Its algorithm identifier is @code{sntrup4591761-x25519}. Its public
+ key value is a concatenation of 1218-byte SNTRUP4591761 public key
+ and 32-byte X25519 one.
-Public key's fingerprint should be calculated using BLAKE2b hash with
-256 bit output length specified.
+ Public key's fingerprint should be calculated using BLAKE2b hash
+ with 256 bit output length specified.
+
+ @url{https://cr.yp.to/ecdh.html, X2559} is key-agreement algorithm,
+ @url{https://datatracker.ietf.org/doc/html/rfc7748.html, RFC 7748}.
+ @url{https://ntruprime.cr.yp.to/, Streamlined NTRU Prime} is KEM algorithm.
@node cm-pub-mceliece6960119-x25519
@cindex cm-pub-mceliece6960119-x25519
@nodedescription cm/pub with Classic McEliece 6960-119+X25519
@subsection cm/pub with Classic McEliece 6960-119+X25519
-Combined Classic McEliece 6960-119 and X25519 public keys are used
-for KEM purposes, so should have "kem" key usage set.
+ Combined Classic McEliece 6960-119 and X25519 public keys are used
+ for KEM purposes, so should have "kem" key usage set.
+
+ Its algorithm identifier is @code{mceliece6960119-x25519}. Its
+ public key value is a concatenation of 1047319-byte
+ @code{mceliece6960119} public key and 32-byte X25519 one.
-Its algorithm identifier is @code{mceliece6960119-x25519}. Its public key
-value is a concatenation of 1047319-byte @code{mceliece6960119} public key
-and 32-byte X25519 one.
+ Public key's fingerprint should be calculated using SHAKE128.
-Public key's fingerprint should be calculated using SHAKE128.
+ @url{https://cr.yp.to/ecdh.html, X2559} is key-agreement algorithm,
+ @url{https://datatracker.ietf.org/doc/html/rfc7748.html, RFC 7748}.
+ @url{https://classic.mceliece.org/, Classic McEliece} is KEM algorithm.
+ @url{https://keccak.team/, SHAKE} is a XOF function.
@cindex cm/signed
@section cm/signed format
-Signed container, analogue to ASN.1-based
+Signed container, some kind of analogue to ASN.1-based
@url{https://datatracker.ietf.org/doc/html/rfc5652, CMS} SignedData.
+@itemize
+@item Ability to embed the data in the signed container
+@item Ability to create detached signature
+@item Ability to use non-prehashed signature of the embedded data,
+ potentially gaining more security
+@item Prehashed format is streaming friendly
+@item You can use @ref{Merkle hashing} mode to parallelise calculations
+@item Ability to attach arbitrary additional data
+@item Ability to store multiple signatures
+@end itemize
+
Stored in a file, it should begin with "cm/signed" @ref{MAGIC, magic},
unless it is a @ref{cm-pub, public key}.
Algorithm identifiers for the signature: @code{gost3410-256A},
@code{gost3410-512C}.
+ Streebog is GOST R 34.11-2012 hashing algorithm,
+ @url{https://datatracker.ietf.org/doc/html/rfc6986.html, RFC 6986}.
+ GOST R 34.10-2012 is signing/key-aggreement algorithm,
+ @url{https://datatracker.ietf.org/doc/html/rfc7091.html, RFC 7091}.
+
@node cm-signed-gost3410-merkle
@cindex cm-signed-gost3410-merkle
@nodedescription cm/signed with GOST R 34.10-2012 with Merkle-tree hashing