James-E-A / pypqc

Attempt to expose Wiggers and Stebila's PQClean via Python CFFI
Other
0 stars 1 forks source link

Usage

Simply install from PyPI with pip install pypqc, or see "Development" below if you want to tinker on the codebase!

KEMs

McEliece, Kyber, and HQC are currently provided, all with the same interface.::

# Available: hqc_128, hqc_192, hqc_256,
# kyber512, kyber768, kyber1024,
# mceliece348864, mceliece460896,
# mceliece6688128, mceliece6960119, mceliece8192128
from pqc.kem import mceliece6960119 as kemalg

# 1. Keypair generation
pk, sk = kemalg.keypair()

# 2. Key encapsulation
ss, kem_ct = kemalg.encap(pk)

# 3. Key de-encapsulation
ss_result = kemalg.decap(kem_ct, sk)
assert ss_result == ss

Capabilities not included in PQClean, such as McEliece signatures, Hybrid Encryption or KEM-TRANS, and message encapsulation, are not going to be implemented in this library. (Exception: Plaintext Confirmation <https://www.github.com/thomwiggers/mceliece-clean/issues/3>_ is on the agenda for inclusion even if upstream ultimately decides to exclude it.)

Signature Algorithms

SPHINCS+, Dilithium, and Falcon are provided, all with the same interface.::

# Available: dilithium2, dilithium3, dilithium5,
# falcon_512, falcon_padded_512, falcon_1024, falcon_padded_1024,
# sphincs_sha2_128f_simple, sphincs_sha2_128s_simple,
# sphincs_shake_128f_simple, sphincs_shake_128s_simple,
# sphincs_sha2_192f_simple, sphincs_sha2_192s_simple,
# sphincs_shake_192f_simple, sphincs_shake_192s_simple,
# sphincs_sha2_256f_simple, sphincs_sha2_256s_simple,
# sphincs_shake_256f_simple, sphincs_shake_256s_simple
from pqc.sign import sphincs_shake_256s_simple as sigalg

# 1. Keypair generation
pk, sk = sigalg.keypair()

# 2. Signing
# (detached signature)
sig = sigalg.sign(MY_MESSAGE, sk)

# 3. Signature verification
# (Returns None on success; raises ValueError on failure.)
sigalg.verify(sig, MY_MESSAGE, pk)

Regarding SPHINCS+: the Simple version is included; the Robust version is is not; SHA256 and SHAKE256 are included; Haraka is not. See https://github.com/PQClean/PQClean/discussions/548#discussioncomment-8565116 for more information.

Regarding Falcon: the Compressed and Padded versions are included, and are able to verify() each others' signatures. The CT version is not currently planned.

Development

Dependencies:

Getting started:

  1. Maybe use a venv <https://www.bitecode.dev/p/relieving-your-python-packaging-pain>_ or whatever if you want to

    • for Windows: py -m venv .venv & .venv\Scripts\activate.bat

    • for Linux and Mac: python3 -m venv .venv; . .venv/bin/activate (first install it <https://packages.ubuntu.com/jammy/python/python3-venv>_, if needed)

  2. Run python -m pip install .

    • Alternatively: you may get cleaner building with python -m build . (only after python -m pip install build)

    • Editable / "develop" mode not supported currently (CFFI will have to support this <https://setuptools.pypa.io/en/latest/userguide/extension.html#setuptools.command.build.SubCommand.editable_mode>_ before it's even on the table.)

  3. Run python -m pqc.demo to test it. If it prints "OK" and exits, the functions are almost certainly not broken. (Ideally, run this from a DIFFERENT directory, such as your home folder, so you can be sure it's being imported properly and not being masked by the local copy.)

    • N.B. / FIXME: this function is currently NOT a full test suite; it only does a single encap-decap cycle with the default implementation of mceliece6960119. It does NOT test any other version of McEliece, or any signature algorithm.

.. _cffi: https://cffi.readthedocs.io/en/release-1.16/ .. _wheel: https://wheel.readthedocs.io/ .. setuptools: https://setuptools.pypa.io/en/stable/ .. Python Headers: https://packages.ubuntu.com/jammy/python3-dev .. build-essential: https://packages.ubuntu.com/jammy/build-essential .. 'Development Tools': https://git.rockylinux.org/rocky/comps/-/blob/e6c8f29a7686326a731ea72b6caa06dabc7801b5/comps-rocky-9-lh.xml#L2169

.. McEliece Signatures: https://inria.hal.science/inria-00072511 .. Hybrid Encryption: https://en.wikipedia.org/wiki/Hybrid_encryption .. KEM-TRANS: https://www.ietf.org/staging/draft-prat-perret-lamps-cms-pq-kem-00.html .. message encapsulation: https://en.wikipedia.org/wiki/Cryptographic_Message_Syntax