From e8090e9ba1a702e2704f571ed440873f6a6c3c90b71482938c27a971b78de62d Mon Sep 17 00:00:00 2001 From: Sergey Matveev Date: Sun, 2 Mar 2025 12:19:53 +0300 Subject: [PATCH] More various links --- spec/cm/dem-chapoly-krkc.texi | 12 +++- spec/cm/dem-kuznechik-ctr-hmac-kr.texi | 13 +++- spec/cm/encrypted.texi | 20 ++++++ spec/cm/hashed.texi | 8 ++- spec/cm/kem-balloon-blake2b-hkdf.texi | 5 ++ spec/cm/kem-gost3410-hkdf.texi | 9 ++- ...-mceliece6960119-x25519-hkdf-shake256.texi | 4 ++ spec/cm/keywrap-kexp15.texi | 6 +- spec/cm/pub.texi | 69 ++++++++++++------- spec/cm/signed.texi | 18 ++++- 10 files changed, 132 insertions(+), 32 deletions(-) diff --git a/spec/cm/dem-chapoly-krkc.texi b/spec/cm/dem-chapoly-krkc.texi index 87783b2..171b32a 100644 --- a/spec/cm/dem-chapoly-krkc.texi +++ b/spec/cm/dem-chapoly-krkc.texi @@ -1,7 +1,7 @@ @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". @@ -25,3 +25,11 @@ randomised 192-bit nonce (initialisation vector) are derived from it. 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}. diff --git a/spec/cm/dem-kuznechik-ctr-hmac-kr.texi b/spec/cm/dem-kuznechik-ctr-hmac-kr.texi index 3e81787..08f3052 100644 --- a/spec/cm/dem-kuznechik-ctr-hmac-kr.texi +++ b/spec/cm/dem-kuznechik-ctr-hmac-kr.texi @@ -13,11 +13,13 @@ CK0 = CEK 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 @@ -25,3 +27,12 @@ CT || HMAC(Streebog-256, key={Kauth|KauthTail}, data=CT) 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}. diff --git a/spec/cm/encrypted.texi b/spec/cm/encrypted.texi index be7771b..5c5c957 100644 --- a/spec/cm/encrypted.texi +++ b/spec/cm/encrypted.texi @@ -3,6 +3,26 @@ @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 diff --git a/spec/cm/hashed.texi b/spec/cm/hashed.texi index fd5e93f..499fbd3 100644 --- a/spec/cm/hashed.texi +++ b/spec/cm/hashed.texi @@ -34,11 +34,14 @@ algorithms. @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 @@ -108,6 +111,9 @@ algorithms. @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 diff --git a/spec/cm/kem-balloon-blake2b-hkdf.texi b/spec/cm/kem-balloon-blake2b-hkdf.texi index 61bd83a..faabf29 100644 --- a/spec/cm/kem-balloon-blake2b-hkdf.texi +++ b/spec/cm/kem-balloon-blake2b-hkdf.texi @@ -27,3 +27,8 @@ KEK = HKDF-Expand(BLAKE2b, @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}. diff --git a/spec/cm/kem-gost3410-hkdf.texi b/spec/cm/kem-gost3410-hkdf.texi index d660f45..ef2bbb0 100644 --- a/spec/cm/kem-gost3410-hkdf.texi +++ b/spec/cm/kem-gost3410-hkdf.texi @@ -13,7 +13,7 @@ Recipient map must also contain additional fields: 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: @@ -24,3 +24,10 @@ KEK= HKDF-Expand(Streebog-512, prk=PRK, info="cm/encrypted/gost3410-hkdf" || /id @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}. diff --git a/spec/cm/kem-mceliece6960119-x25519-hkdf-shake256.texi b/spec/cm/kem-mceliece6960119-x25519-hkdf-shake256.texi index 0fda580..0eaae37 100644 --- a/spec/cm/kem-mceliece6960119-x25519-hkdf-shake256.texi +++ b/spec/cm/kem-mceliece6960119-x25519-hkdf-shake256.texi @@ -27,3 +27,7 @@ KEK = HKDF-Expand(SHAKE256, prk=PRK, @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. diff --git a/spec/cm/keywrap-kexp15.texi b/spec/cm/keywrap-kexp15.texi index d68149b..6e27c98 100644 --- a/spec/cm/keywrap-kexp15.texi +++ b/spec/cm/keywrap-kexp15.texi @@ -3,7 +3,7 @@ @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 @@ -11,3 +11,7 @@ Kenc || IV || Kauth = KEK 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. diff --git a/spec/cm/pub.texi b/spec/cm/pub.texi index 20323cf..b92eb62 100644 --- a/spec/cm/pub.texi +++ b/spec/cm/pub.texi @@ -103,54 +103,73 @@ Example minimal certified public key may look like: @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. diff --git a/spec/cm/signed.texi b/spec/cm/signed.texi index 3d7f494..7973157 100644 --- a/spec/cm/signed.texi +++ b/spec/cm/signed.texi @@ -3,9 +3,20 @@ @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}. @@ -59,6 +70,11 @@ recipient's public key fingerprint(s). 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 -- 2.48.1