Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Classic McEliece Testspecification #187

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Classic McEliece Testspecification #187

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0f86b99
Classic McEliece Testspecification
FAlbertDev Feb 15, 2024
4531dbe
Apply review suggestions
FAlbertDev Mar 11, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
142 changes: 132 additions & 10 deletions docs/testspec/src/12_pubkey_kem.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,127 @@
Public Key Encapsulation Mechanisms
-----------------------------------

Classic McEliece
~~~~~~~~~~~~~~~~

To ensure the correctness of the implementation, the Known Answer Test (KAT)
vectors provided by the reference implementation are used. However, no
KAT vectors are available for plaintext confirmation (pc) instances. To address
this, the reference implementation was extended with pc logic independently of
Botan for generating KAT vectors.

In addition to the KAT tests, Botan includes
implementation-independent test cases. These test cases guarantee the
interoperability of the algorithm when using Botan's generic API for public key
algorithms. These test cases are applicable to all public key schemes and are
therefore not discussed in detail here.

Also, the Classic McEliece implementation includes utility and unit tests that
are useful for debugging purposes. However, these tests are not extensive and
are already covered by the Known Answer Test (KAT) suite.

Of particular importance are the tests that verify the correct revocation of
invalid ciphertexts. For pc instances, it is crucial to confirm that the
decryption of invalid ciphertexts produces the expected invalid result, even
when only the second part of the ciphertext (referred to as :math:`C_1` in the
Classic McEliece specification) is malformed. In this case, the rejection seed
(:math:`s`) is utilized. These cases are tested using self-generated KAT tests.

All the tests specific to Classic McEliece are found in
:srcref:`src/tests/test_cmce.cpp`. The relevant test data vectors for the
KAT tests are located in :srcref:`src/tests/data/pubkey/cmce_kat_hashed.vec`,
while the negative test vectors are in
:srcref:`src/tests/data/pubkey/cmce_negative.vec`. Note that, due to the large
size of the other values, all values except the KAT seeds and the ciphertexts
are hashed.

.. table::
:class: longtable
:widths: 20 80

+------------------------+-------------------------------------------------------------------------+
| **Test Case No.:** | PKENC-CMCE-1 |
+========================+=========================================================================+
| **Type:** | Known Answer Tests |
+------------------------+-------------------------------------------------------------------------+
| **Description:** | Uses the KAT vectors of Classic McElieces's reference implementation as |
| | specified in the NIST submission |
+------------------------+-------------------------------------------------------------------------+
| **Preconditions:** | None |
+------------------------+-------------------------------------------------------------------------+
| **Input Values:** | Test Vectors with RNG seed inputs in: |
| | |
| | * :srcref:`src/tests/data/pubkey/cmce_kat_hashed.vec` |
+------------------------+-------------------------------------------------------------------------+
| **Expected Output:** | Above described test vector files contain expected values for: |
| | |
| | * Classic McEliece Public Key |
| | * Classic McEliece Private Key |
| | * Ciphertext |
| | * Shared Secret |
+------------------------+-------------------------------------------------------------------------+
| **Steps:** | For each KAT vector: |
| | |
| | #. Seed an AES-256-CTR-DRBG with the specified RNG seed |
| | |
| | #. Use the seeded RNG to generate a Classic McEliece key pair and |
| | compare its private key to the expected one in the test |
| | vector. This vector contains the key encoding as implemented in the |
| | reference implementation hashed using SHAKE-256(512) to save |
| | disk space in the KAT vectors. |
| | |
| | #. Check that the expected algorithm properties of the generated keys |
| | match the generic expectations for KEMs (supports key encapsulation, |
atreiber94 marked this conversation as resolved.
Show resolved Hide resolved
| | reports a key strength in a reasonable interval, etc.). |
| | |
| | #. Extract the public key from the just generated key pair and compare |
atreiber94 marked this conversation as resolved.
Show resolved Hide resolved
| | it to the expected (hashed) value in the test vector. |
| | |
| | #. Encode both public and private key, and decode them again. |
atreiber94 marked this conversation as resolved.
Show resolved Hide resolved
| | |
| | #. Encapsulate a secret with the just-generated public key after the |
| | encode/decode roundtrip (using the same RNG) and compare the |
| | resulting shared secret and ciphertext to expected values in the |
| | test vector. |
| | |
| | #. Decapsulate the just-calculated ciphertext with the private key from |
| | the encode/decode roundtrip and ensure that the resulting shared |
| | secret is equal to the expected value from the test vector. |
+------------------------+-------------------------------------------------------------------------+

.. table::
:class: longtable
:widths: 20 80

+------------------------+-------------------------------------------------------------------------+
| **Test Case No.:** | PKENC-CMCE-2 |
+========================+=========================================================================+
| **Type:** | Negative Test/Known Answer Tests |
+------------------------+-------------------------------------------------------------------------+
| **Description:** | For a plaintext confirmation (pc) and a non-pc instance: |
| | Generate a Classic McEliece keypair using any KAT seed, use the private |
| | key to decapsulate an invalid ciphertext, and compare the resulting |
| | value with the value generated using the reference implementation. |
+------------------------+-------------------------------------------------------------------------+
| **Preconditions:** | None |
+------------------------+-------------------------------------------------------------------------+
| **Input Values:** | KAT seed, invalid ciphertext, corresponding invalid shared secret |
+------------------------+-------------------------------------------------------------------------+
| **Expected Output:** | The correct invalid shared secret |
+------------------------+-------------------------------------------------------------------------+
| **Steps:** | For each available algorithm parameterization: |
| | |
| | #. Generate a key pair using the KAT seed with AES-256-CTR-DRBG |
| | |
| | #. Decapsulate the invalid ciphertext (input value). The invalid |
| | ciphertext is a valid one where a single bit is flipped. |
| | The bit flip position varies in different test vectors to also |
| | cover tests where only plaintext confirmation fails. |
| | |
| | #. Compare the resulting shared secret with the reference shared |
| | secret (input value). |
+------------------------+-------------------------------------------------------------------------+

FrodoKEM
~~~~~~~~

Expand Down Expand Up @@ -43,15 +164,16 @@ tests are in *src/tests/data/pubkey/frodokem_kat.vec*.
+------------------------+-------------------------------------------------------------------------+
| **Steps:** | For each KAT vector: |
| | |
| | #. Seed a AES-256-CTR-DRBG with the specified RNG seed |
| | #. Seed an AES-256-CTR-DRBG with the specified RNG seed |
| | |
| | #. Use the seeded RNG to generate a FrodoKEM key pair and compare it to |
| | the expected public and private key in the test vector. This uses |
| | #. Use the seeded RNG to generate a FrodoKEM key pair and |
| | compare its private key to the expected one in the test vector. |
| | This vector contains |
| | the key encoding as implemented in the reference implementation and |
| | hashes the result using SHAKE-256(128) to save disk space in the KAT |
| | hashed using SHAKE-256(128) to save disk space in the KAT |
| | vectors. |
| | |
| | #. Check that the expected algorithm properties of the generated key |
| | #. Check that the expected algorithm properties of the generated keys |
| | match the generic expectations for KEMs (supports key encapsulation, |
| | reports a key strength in a reasonable interval, etc.). |
| | |
Expand Down Expand Up @@ -153,13 +275,13 @@ algorithm parameters, namely *512*, *512_90s*, *768*, *768_90s*, *1024* and
+------------------------+-------------------------------------------------------------------------+
| **Steps:** | For each KAT vector: |
| | |
| | #. Seed a AES-256-CTR-DRBG with the specified RNG seed |
| | #. Seed an AES-256-CTR-DRBG with the specified RNG seed |
| | |
| | #. Use the seeded RNG to generate a Kyber key pair and compare it to |
| | the expected public and private key in the test vector. This uses |
| | the key encoding as implemented in the reference implementation. |
| | #. Use the seeded RNG to generate a Kyber key pair and |
| | compare its private key to the expected one in the test vector. This |
| | uses the key encoding as implemented in the reference implementation.|
| | |
| | #. Check that the expected algorithm properties of the generated key |
| | #. Check that the expected algorithm properties of the generated keys |
| | match the generic expectations for KEMs (supports key encapsulation, |
| | reports a key strength in a reasonable interval, etc.). |
| | |
Expand Down
Loading