Apply review suggestions

docs/cryptodoc/src/05_09_kyber.rst

@@ -315,7 +315,7 @@ In combination, Botan does the following:
 
    - Step 1 corresponds to Algorithm 19 of [FIPS-203]_ and is performed in :srcref:`[src/lib/pubkey/kyber]/kyber/kyber_common/kyber.cpp:232|Kyber_PrivateKey::Kyber_PrivateKey`.
    - Steps 2-7 correspond to Algorithms 16 and 13 of [FIPS-203]_ and are performed in :srcref:`[src/lib/pubkey/kyber]/kyber/kyber_common/kyber_algos.cpp:321|expand_keypair`.
-   - Botan only stores the seeds as the secret key. The required values for decapsulation are recomputed on demand.
+   - Botan only stores the seeds as the secret key. The required values for decapsulation are recomputed on demand. Loading or storing the partially expanded key format specified in [FIPS-203]_ is explicitly not supported.
 
 
 .. _pubkey/kyber/encaps:
@@ -349,23 +349,23 @@ In combination, Botan does the following:
    2. ``(K, r) = G(m || H(pk))``
    3. K-PKE encrypt ``m`` using ``r`` to obtain ciphertext ``c``
 
-      4. Sample transposed matrix ``At`` from ``rho`` using ``sample_matrix``
-      5. Initialize a ``PolynomialSampler`` ``ps`` with ``sigma``
-      6. ``y = ntt(ps.sample_polynomial_vector_cbd_eta1())``
-      7. ``e1 = ps.sample_polynomial_vector_cbd_eta2()``
-      8. ``e2 = ps.sample_polynomial_cbd_eta2()``
-      9. ``u = inverse_ntt(At * y) + e1``
-      10. ``mu = polynomial_from_message(m)`` for byte decoding and decompression
-      11. ``v = inverse_ntt(t * y) + e2 + mu``
-      12. Encode and compress ``u`` and ``v`` to obtain ``c = c1 || c2`` using ``compress_ciphertext``
-      13. ``c = c1 || c2``
+      1. Sample transposed matrix ``At`` from ``rho`` using ``sample_matrix``
+      2. Initialize a ``PolynomialSampler`` ``ps`` with ``sigma``
+      3. ``y = ntt(ps.sample_polynomial_vector_cbd_eta1())``
+      4. ``e1 = ps.sample_polynomial_vector_cbd_eta2()``
+      5. ``e2 = ps.sample_polynomial_cbd_eta2()``
+      6. ``u = inverse_ntt(At * y) + e1``
+      7. ``mu = polynomial_from_message(m)`` for byte decoding and decompression
+      8. ``v = inverse_ntt(t * y) + e2 + mu``
+      9. Encode, compress and concatenate ``u`` and ``v`` to obtain the
+         ciphertext ``c`` using ``compress_ciphertext``
 
 
    **Notes:**
 
    - Steps 1-3 correspond to Algorithms 20 and 17 of [FIPS-203]_ and are performed in :srcref:`[src/lib/pubkey/kyber]/ml_kem/ml_kem_impl.cpp:25|ML_KEM_Encryptor::encapsulate`.
-   - Steps 4-14 correspond to Algorithms 14 of [FIPS-203]_ and are performed in :srcref:`[src/lib/pubkey/kyber]/kyber/kyber_common/kyber_keys.cpp:55|indcpa_encrypt`.
-   - The transposed matrix ``At`` is precomputed and stored in the public key object.
+   - Steps 1.1-1.9 correspond to Algorithms 14 of [FIPS-203]_ and are performed in :srcref:`[src/lib/pubkey/kyber]/kyber/kyber_common/kyber_keys.cpp:55|indcpa_encrypt`.
+   - The transposed matrix ``At`` is precomputed and stored in the public key object. This way, consecutive encapsulations for the same public key do not have to re-generate ``At`` from ``rho``.
 
 
 .. _pubkey/kyber/decaps:
@@ -398,19 +398,19 @@ In combination, Botan does the following:
    **Steps:**
 
    1. Recompute the secret key value ``s`` from ``seed.d``
-   2. K-PKE decrypt ``c`` to obtain message ``m``
+   2. K-PKE decrypt ``c`` to obtain message ``m_prime``
 
-      3. Retrieve ``u, v`` using ``decompress_ciphertext`` on ``c``
-      4. Compute ``w = v - inverse_ntt(s * ntt(u))``
-      5. ``m = polynomial_to_message(w)`` for compression and byte encoding
+      1. Retrieve ``u, v`` using ``decompress_ciphertext`` on ``c``
+      2. Compute ``w = v - inverse_ntt(s * ntt(u))``
+      3. ``m = polynomial_to_message(w)`` for compression and byte encoding
 
-   6. ``(K_prime, r_prime) = G(m || H(pk))``
-   7. ``K_bar = J(seed.z || c)``
-   8. K-PKE encrypt ``m`` using ``r_prime`` to obtain ciphertext ``c_prime``
-   9. if ``c != c_prime`` set ``K_prime = K_bar``
+   3. ``(K_prime, r_prime) = G(m_prime || H(pk))``
+   4. ``K_bar = J(seed.z || c)``
+   5. K-PKE encrypt ``m`` using ``r_prime`` to obtain ciphertext ``c_prime``
+   6. if ``c != c_prime`` set ``K_prime = K_bar``
 
    **Notes:**
 
    - Steps 1,2 and 6-9 correspond to Algorithm 18 of [FIPS-203]_ and are performed in :srcref:`[src/lib/pubkey/kyber]/ml_kem/ml_kem_impl.cpp:48|ML_KEM_Decryptor::decapsulate`.
-   - Steps 3-5 correspond to Algorithms 15 of [FIPS-203]_ and are performed in :srcref:`[src/lib/pubkey/kyber]/kyber/kyber_common/kyber_keys.cpp:84|Kyber_PrivateKeyInternal::indcpa_decrypt`.
-   - Step 9 uses a constant time check and memory assignment function.
+   - Steps 2.1-2.3 correspond to Algorithm 15 of [FIPS-203]_ and are performed in :srcref:`[src/lib/pubkey/kyber]/kyber/kyber_common/kyber_keys.cpp:84|Kyber_PrivateKeyInternal::indcpa_decrypt`.
+   - Step 6 uses a constant time check and memory assignment function.