Skip to content

Commit

Permalink
Apply Renéview suggestions
Browse files Browse the repository at this point in the history
  • Loading branch information
@FAlbertDev
FAlbertDev committed Oct 21, 2024
1 parent 8a59260 commit 22bcfbf
Showing 1 changed file with 68 additions and 63 deletions.
131 changes: 68 additions & 63 deletions docs/cryptodoc/src/05_09_kyber.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,14 +28,16 @@ in Table
Algorithm Internals
-------------------

[FIPS-203]_ splits the three main algorithms for key generation, encapsulation,
and decapsulation into three layers: ML-KEM (Section 7), ML-KEM internal
(Section 6), and K-PKE (Section 5). The high-level ML-KEM algorithms
are mainly concerned with randomness generation and calling the internal
algorithms (Section 6 of [FIPS-203]_) that performs the actual logic.
The internal algorithms apply a modified Fujisaki-Okamoto transform
with the K-PKE encryption scheme, which consists of three algorithms
for key generation, encryption, and decryption.
Being a key encapsulation mechanism, [FIPS-203]_ defines three primary
operations: key generation, encapsulation, and decapsulation.

Internally, those operations are further split into three functional layers:
ML-KEM (Section 7), ML-KEM-internal (Section 6), and K-PKE (Section 5). ML-KEM
and ML-KEM-internal decouple the actual high-level logic from the generation of
randomness. ML-KEM-internal receives pre-determined random bytes and is,
therefore, fully deterministic. ML-KEM-internal applies a modified
Fujisaki-Okamoto transform to define an IND-CCA2 secure KEM based on the
internal IND-CPA secure key exchange algorithm K-PKE.

Table :ref:`ML-KEM components and file locations <pubkey/kyber/component_table>`
shows an overview of all ML-KEM components and their file locations.
Expand All @@ -50,7 +52,7 @@ shows an overview of all ML-KEM components and their file locations.
+===========================================================+============================================================================+====================================================================+========================+
| :ref:`Types <pubkey/kyber/types>` | :srcref:`[src/lib/pubkey/kyber/kyber_common]/kyber_types.h` | Strong types | \- |
+-----------------------------------------------------------+----------------------------------------------------------------------------+--------------------------------------------------------------------+------------------------+
| :ref:`Constants <pubkey/kyber/constants>` | :srcref:`[src/lib/pubkey/kyber/kyber_common]/constants.h` | Parameter set instantiations | 8 |
| :ref:`Constants <pubkey/kyber/constants>` | :srcref:`[src/lib/pubkey/kyber/kyber_common]/kyber_constants.h` | Parameter set instantiations | 8 |
+-----------------------------------------------------------+----------------------------------------------------------------------------+--------------------------------------------------------------------+------------------------+
| :ref:`Compression Helpers <pubkey/kyber/compr_helpers>` | :srcref:`[src/lib/pubkey/kyber/kyber_common]/kyber_helpers.h` | Specific bit operations, compression and decompression | 4.2.1 |
+-----------------------------------------------------------+----------------------------------------------------------------------------+--------------------------------------------------------------------+------------------------+
Expand Down Expand Up @@ -124,10 +126,11 @@ Polynomials

ML-KEM relies extensively on polynomials within the polynomial ring :math:`R_q`,
utilizing vectors and matrices of polynomials, both inside and outside the NTT
domain. Botan represents these polynomials and polynomial vectors as
``KyberPoly`` and ``KyberPolyVec``, with their NTT counterparts being
``KyberPolyNTT`` and ``KyberPolyVecNTT``. Matrices only appear in the NTT
domain and are represented by the class ``KyberPolyMatrix``.
domain. Botan uses :ref:`strong types <pubkey/kyber/types>` to distinguish
polynomials and polynomial vectors as ``KyberPoly`` and ``KyberPolyVec``, as
well as their NTT counterparts ``KyberPolyNTT`` and ``KyberPolyVecNTT``.
Matrices only appear in the NTT domain and are represented by the class
``KyberPolyMatrix``.

ML-DSA, as defined in [FIPS-204]_, also employs polynomials, leading to shared
polynomial logic between the two algorithms. This shared logic is located in
Expand All @@ -139,18 +142,14 @@ this construction by including the NTT (Algorithm 9 of [FIPS-203]_) and inverse
NTT (Algorithm 10 of [FIPS-203]_) operations, along with NTT polynomial
multiplication (Algorithms 11 and 12 of [FIPS-203]_).

Botan's polynomial type system ensures that correct polynomial representations
are used and that operations are valid only on compatible types. For instance,
polynomial multiplication is permissible only if both polynomials are in the
NTT domain.
Due to this type-based construction, the C++ compiler can detect specific
implementation issues statically. For instance, the polynomial
multiplication operation is only defined for the ``PolyVecNTT`` type. Misuse
would result in a compile-time error.

Botan utilizes either Montgomery or Barrett reduction for modular reduction,
depending on the size of the values involved. Montgomery reduction requires
multiplying by a Montgomery factor after each reduction. An optimization from
the reference implementation integrates this factor into the NTT constants,
eliminating the need for an additional multiplication in the NTT
function. For the inverse NTT, another Montgomery factor is embedded to
compensate for the latest reduction in the main ML-KEM algorithm.
depending on the expected result range of certain operations. Reductions are
explicitly applied in the implementation as needed.


.. _pubkey/kyber/sup_algos:
Expand All @@ -166,29 +165,29 @@ summary of these functions and their specific purposes.
.. _pubkey/kyber/algos:

.. table:: ML-KEM Algorithms Overview
:widths: 30, 52, 18

+------------------------------+----------------------------------------------------------------------+---------------------------+
| Botan Function | Purpose | Algorithms of [FIPS-203]_ |
+==============================+======================================================================+===========================+
| ``encode_polynomial_vector`` | Byte encoding of polynomial vectors | 5 |
+------------------------------+----------------------------------------------------------------------+---------------------------+
| ``decode_polynomial_vector`` | Byte decoding of polynomial vectors | 6 |
+------------------------------+----------------------------------------------------------------------+---------------------------+
| ``polynomial_from_message`` | Byte decoding of the K-PKE message :math:`m` | 6 |
+------------------------------+----------------------------------------------------------------------+---------------------------+
| ``polynomial_to_message`` | Byte encoding of the K-PKE message :math:`m` | 5 |
+------------------------------+----------------------------------------------------------------------+---------------------------+
| ``expand_keypair`` | Create public and secret keys from the seeds :math:`d` and :math:`z` | 13, 16 |
+------------------------------+----------------------------------------------------------------------+---------------------------+
| ``compress_ciphertext`` | Compress, byte encode, and concatenate polynomial vector | 5, Formula 4.7 |
| | :math:`\mathbf{u}` and polynomial :math:`\mathbf{v}` | |
+------------------------------+----------------------------------------------------------------------+---------------------------+
| ``decompress_ciphertext`` | Split, byte decode, and decompress bytes to polynomial vector | 6, Formula 4.8 |
| | :math:`\mathbf{u'}` and polynomial :math:`\mathbf{v'}` | |
+------------------------------+----------------------------------------------------------------------+---------------------------+
| ``sample_matrix`` | Samples a matrix from a secret seed | 7, 13 |
+------------------------------+----------------------------------------------------------------------+---------------------------+
:widths: 28, 28, 21, 13

+------------------------------+---------------------------------------------------------------------------------------------+----------------------------------------------------------------------+---------------------------+
| Botan Function | Code Reference | Purpose | Algorithms of [FIPS-203]_ |
+==============================+=============================================================================================+======================================================================+===========================+
| ``encode_polynomial_vector`` | :srcref:`[src/lib/pubkey/kyber/kyber_common]/kyber_algos.cpp:184|encode_polynomial_vector` | Byte encoding of polynomial vectors | 5 |
+------------------------------+---------------------------------------------------------------------------------------------+----------------------------------------------------------------------+---------------------------+
| ``decode_polynomial_vector`` | :srcref:`[src/lib/pubkey/kyber/kyber_common]/kyber_algos.cpp:192|decode_polynomial_vector` | Byte decoding of polynomial vectors | 6 |
+------------------------------+---------------------------------------------------------------------------------------------+----------------------------------------------------------------------+---------------------------+
| ``polynomial_from_message`` | :srcref:`[src/lib/pubkey/kyber/kyber_common]/kyber_algos.cpp:204|polynomial_from_message` | Byte decoding of the K-PKE message :math:`m` | 6 |
+------------------------------+---------------------------------------------------------------------------------------------+----------------------------------------------------------------------+---------------------------+
| ``polynomial_to_message`` | :srcref:`[src/lib/pubkey/kyber/kyber_common]/kyber_algos.cpp:212|polynomial_to_message` | Byte encoding of the K-PKE message :math:`m` | 5 |
+------------------------------+---------------------------------------------------------------------------------------------+----------------------------------------------------------------------+---------------------------+
| ``expand_keypair`` | :srcref:`[src/lib/pubkey/kyber/kyber_common]/kyber_algos.cpp:321|expand_keypair` | Create public and secret keys from the seeds :math:`d` and :math:`z` | 13, 16 |
+------------------------------+---------------------------------------------------------------------------------------------+----------------------------------------------------------------------+---------------------------+
| ``compress_ciphertext`` | :srcref:`[src/lib/pubkey/kyber/kyber_common]/kyber_algos.cpp:352|compress_ciphertext` | Compress, byte encode, and concatenate polynomial vector | 5, Formula 4.7 |
| | | :math:`\mathbf{u}` and polynomial :math:`\mathbf{v}` | |
+------------------------------+---------------------------------------------------------------------------------------------+----------------------------------------------------------------------+---------------------------+
| ``decompress_ciphertext`` | :srcref:`[src/lib/pubkey/kyber/kyber_common]/kyber_algos.cpp:362|decompress_ciphertext` | Split, byte decode, and decompress bytes to polynomial vector | 6, Formula4.8 |
| | | :math:`\mathbf{u'}` and polynomial :math:`\mathbf{v'}` | |
+------------------------------+---------------------------------------------------------------------------------------------+----------------------------------------------------------------------+---------------------------+
| ``sample_matrix`` | :srcref:`[src/lib/pubkey/kyber/kyber_common]/kyber_algos.cpp:380|sample_matrix` | Samples a matrix from a secret seed | 7, 13 |
+------------------------------+---------------------------------------------------------------------------------------------+----------------------------------------------------------------------+---------------------------+


Additionally, the ``PolynomialSampler`` class offers robust functionality for
Expand All @@ -203,16 +202,17 @@ object and increments with each method call accordingly.
.. _pubkey/kyber/poly_sample:

.. table:: Polynomial Sampling Methods
:widths: 40, 26, 34

+------------------------------------------+---------------------------------------------------------------------+
| Polynomial sampler method | Purpose |
+==========================================+=====================================================================+
| ``sample_polynomial_vector_cbd_eta1`` | Polynomial vector sampling in :math:`\mathcal{D}_{\eta_1}(R_q)` |
+------------------------------------------+---------------------------------------------------------------------+
| ``sample_polynomial_cbd_eta2`` | Polynomial sampling in :math:`\mathcal{D}_{\eta_2}(R_q)` |
+------------------------------------------+---------------------------------------------------------------------+
| ``sample_polynomial_vector_cbd_eta2`` | Polynomial vector sampling in :math:`\mathcal{D}_{\eta_2}(R_q)` |
+------------------------------------------+---------------------------------------------------------------------+
+------------------------------------------+---------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+
| Polynomial sampler method | Code Reference | Purpose |
+==========================================+===================================================================================================+=====================================================================+
| ``sample_polynomial_vector_cbd_eta1`` | :srcref:`[src/lib/pubkey/kyber/kyber_common]/kyber_algos.h:70|sample_polynomial_vector_cbd_eta1` | Polynomial vector sampling in :math:`\mathcal{D}_{\eta_1}(R_q)` |
+------------------------------------------+---------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+
| ``sample_polynomial_cbd_eta2`` | :srcref:`[src/lib/pubkey/kyber/kyber_common]/kyber_algos.h:78|sample_polynomial_cbd_eta2` | Polynomial sampling in :math:`\mathcal{D}_{\eta_2}(R_q)` |
+------------------------------------------+---------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+
| ``sample_polynomial_vector_cbd_eta2`` | :srcref:`[src/lib/pubkey/kyber/kyber_common]/kyber_algos.h:86|sample_polynomial_vector_cbd_eta2` | Polynomial vector sampling in :math:`\mathcal{D}_{\eta_2}(R_q)` |
+------------------------------------------+---------------------------------------------------------------------------------------------------+---------------------------------------------------------------------+


.. _pubkey/kyber/sym_primitives:
Expand All @@ -221,9 +221,11 @@ Symmetric Primitives
^^^^^^^^^^^^^^^^^^^^

In Botan, the symmetric primitives of ML-KEM are represented by the
``KyberSymmetricPrimitives`` class. This class provides an interface for
the primitives, which are defined as :math:`PRF`, :math:`H`, :math:`J`,
:math:`G`, and :math:`XOF` in Section 4.1 of [FIPS-203]_.
``KyberSymmetricPrimitives`` class
(:srcref:`[src/lib/pubkey/kyber/kyber_common]/kyber_symmetric_primitives.h:30|Kyber_Symmetric_Primitives`).
This class provides an interface for the primitives, which are defined as
:math:`PRF`, :math:`H`, :math:`J`, :math:`G`, and :math:`XOF` in Section 4.1 of
[FIPS-203]_.


.. _pubkey/kyber/kpke_keys:
Expand Down Expand Up @@ -263,11 +265,14 @@ Kyber
^^^^^

For compatibility reasons, Botan continues to support the Kyber Round 3.1 NIST
submission [Kyber-R3]_. The Kyber and Kyber 90s instances can be activated by
enabling the ``kyber`` or ``kyber_90s`` module, respectively. This allows for
the selection of the desired variants within the ``KyberMode``. It is strongly
recommended to use the ML-KEM instances instead.

submission [Kyber-R3]_, which was implemented and released before the release of
the final standard. The Kyber and Kyber 90s instances can be activated by
enabling the ``kyber`` or ``kyber_90s`` module, respectively.

Note that the Kyber 90s is already marked as deprecated, and both Kyber and
Kyber 90s may be removed as early as the next major release of the library. It
is not advisable to use any other variant than the ones specified in
[FIPS-203]_.


.. _pubkey/kyber/key_gen:
Expand Down

0 comments on commit 22bcfbf

Please sign in to comment.