Repository files navigation

crypto-condor is a tool for compliance testing of cryptographic primitives, inthe form of a Python library and CLI. It is complemented by an extensivedocumentation, featuring guides on the primitives supported.

Q: What is a cryptographic primitive?

A: A low-level cryptographic algorithm, generally used to build a protocol.For example, AES is an encryption primitive that is used in the TLS protocol,which is the protocol your browser used to securely get this page.

Q: What is compliance testing?

A: Algorithms are described in specifications, such as FIPS publications orRFCs. When implementing these algorithms, we want to ensure that they complywith the specification, i.e. the implementation behaves as the algorithmdescribed.

Q: How to test for compliance then?

A: We can usetest vectors, which are sets of inputs and theircorresponding outputs. For example, encrypting with AES is a deterministicoperation: for a given key and message, AES will always return the sameciphertext. So we can choose some input values, run the algorithm, and recordthe value returned. All implementations of AES are then expected to return thesame ciphertext for this given key and message. If it does not, then it is notcompliant.

Q: And so, what does crypto-condor do?

A: crypto-condor provides both a nice Python API and a wrapper system totest implementations with sets of test vectors that come from sources such astheNISTCAVP.

The Python API exposes test functions that take an implementation as input, inthe form of a Python function or class, passes the inputs defined by the testvectors to that implementation, and checks if the outputs are those defined bythe vectors.

The wrappers are small programs that already define the function prototype. Theuser calls the implementation to test inside this function, and crypto-condorruns it with the test vectors as with the Python API.

And it comes with a documentation, wrapper examples, and guides on supportedprimitives.

crypto-condor requiresPython 3.10+. For information, it is developed usingPython 3.13 on Fedora 41.

The implementations ofAES, ML-KEM, ML-DSA, and TestU01 are written in C andare compiled directly on the user's machine. As such, they require a C compiler(by default GCC on Linux and Clang on MacOS) and GNU Make. These primitives areonly compiled when required, and not when installing the package:

• AES: when testing the output of an implementation using classic modes ofoperation (not CCM or GCM).
• ML-KEM: when testing the output of an implementationor when using testvectors on theencapsulate function.
• ML-DSA: when testing the output of an implementation.
• TestU01: when used to test a file.

The compiler can be chosen by setting theCC environment variable on Linux. OnMacOS, only Clang has been confirmed to work.

It is available on PyPI:

python -m pip install crypto-condor

An up-to-date list of the requirements can be found in the[tool.poetry.dependencies] section of thepyproject.tomlfile.

The documentation is available athttps://quarkslab.github.io/crypto-condor/latest/index.html.

Once installed, the CLI is available ascrypto-condor-cli. It is structured incommands, similar to Git. Run it without arguments or with--help to displaythe help message detailing the available subcommands. You can checkthedocumentation fora quick rundown of all the commands.

As for the Python library, it is available ascrypto_condor (note theunderscore). Each primitive has its own module underprimitives, e.g.crypto_condor.primitives.AES. It contains the functions used to testimplementations.

SeeCONTRIBUTING.

Achangelogis available. This projects adheres toCalVer. The formatused is YYYY.MM.DD[.MICRO][-MODIFIER]:

• YYYY: full year (2023).
• 0M: zero-padded month (01, 02, ..., 12).
• 0D: zero-padded day (01, 02, ..., 31).
• MICRO: an increasing counter, used for patches published in the same day.
• MODIFIER: usuallyrc<n> to indicate a release candidate.

• Julio Loayza Meneses, Quarkslab.
• Angèle Bossuat, Quarkslab.
• Dahmun Goudarzi, Quarkslab.

Logo idea by Robin David, drawing by Irene Loayza.

Apache License Version 2.0, seeLICENSE.