pypqc 0.0.1.post1

CFFI bindings for PQClean. (Currently, only the Classic McEliece KEM is implemented.)

Installation

(Installation instructions TODO.)

Usage

from pqc.kem import mceliece6960119


# 1. Keypair generation
pk, sk = mceliece6960119.kem_keypair()

# WARNING these^ are some heavy keys
# (1MiB public, 13.6KiB private)
# if you must display them, consider base64.encode(...)


# 2. Key encapsulation
ss, kem_ct = mceliece6960119.kem_enc(pk)

# 2(a). Hybrid KEM-Wrap
cek = urandom(32)
symm_ct = MY_SYMMETRIC_CRYPTOSYSTEM.enc(message_plaintext, key=cek)
kek = MY_KDF(ss, target=MY_KEYWRAP)
wk = MY_KEYWRAP.enc(cek, key=kek)
SEND_MESSAGE([kem_ct, wk, symm_ct])


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

# 3(a) Hybrid KEM Unwrap
kek = MY_KDF(ss_result, target=MY_KEYWRAP)
cek = MY_KEYWRAP.dec(wk, key=kek)
message_result = MY_SYMMETRIC_CRYPTOSYSTEM.dec(symm_ct, key=cek)

Currently, only the McEliece KEM is exposed. Kyber and HQC are planned next; after them will be the signature algorithms.

Capabilities not included in PQClean, such as McEliece signatures, Hybrid Encryption (depicted above), and message encapsulation, are not going to be implemented in this library. (Exception: Plaintext Confirmation is on the agenda for inclusion even if upstream ultimately decides to exclude it.)

Development

Dependencies:

• Python 3 (tested mainly on CPython 3.9, 3.10, 3.11, and 3.12; and on PyPy 7.3.12)

• cffi (from PyPI; build-time dependency only)

  • Transitive dependency: Python Headers (I think these come OOTB on Windows)

• setuptools (from PyPI; build-time dependency only)

• a C compiler (build-time dependency only)

  • If you’re on Windows, https://visualstudio.microsoft.com/visual-cpp-build-tools/

    • If setuptools is having trouble finding your compiler, make sure to first enter the appropriate environment. (For AMD64, this will be “x64 Native Tools Command Prompt for VS 2022”; for 32-bit x86, this will be “Developer Command Prompt for VS 2022”; for other situations, see the documentation.)

  • If you’re on Mac, reportedly Homebrew + pkg-config + libffi is a good choice.

  • If you’re on Linux, install build-essential or ‘Development Tools’ or something like that.

  • (I haven’t tested it, but if you’re allergic to installing things outside the venv you might be able to use this C compiler…)

Getting started:

0. Maybe use a venv 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, if needed)

1. 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 before it’s even on the table.)

2. 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.)

Copyright

Except as noted below, all files original or contributed works, Copyright (c) 2023 James Edington Administrator.

Except as noted below, all files provided under the terms of LICENSE in this folder.

Exceptions:

• Lib/PQClean/common/aes.*: Provided under The MIT License; Copyright (c) 2016 Thomas Pornin.

• Lib/PQClean/common/fips202.*: Public domain; from Ronny Van Keer, Gilles Van Assche, Daniel J. Bernstein, and Peter Schwabe.

• Lib/PQClean/common/keccak4x: Public domain (CC0); from Gilles Van Assche and Ronny Van Keer.

• Lib/PQClean/common/nistseedexpander.*: ⚠️ Ambiguously licensed! Copyright (c) 2017 Lawrence E. Bassham, with contributions from Sebastian Verschoor.

• Lib/PQClean/common/randombytes.*: Provided under The MIT License; Copyright (c) 2017 Daan Sprenkels.

• Lib/PQClean/common/sha2.*: Public domain.

• Lib/PQClean/common/sp800-185.*: Public domain (CC0); from Ko Stoffelen.

• Lib/PQClean/crypto_kem/hqc-rmrs*: Public domain.

• Lib/PQClean/crypto_kem/kyber*: Public domain (CC0).

• Lib/PQClean/crypto_kem/mceliece*: Public domain.

• Lib/PQClean/crypto_sign/dilithium*: Public domain.

• Lib/PQClean/crypto_sign/falcon*: ⚠️ May be patent-encumbered in the United States! Provided under The MIT License; Copyright (c) 2017-2019 Falcon Project.

• Lib/PQClean/crypto_sign/sphincs*: Public domain (CC0).

• All other files under Lib/PQClean: Public domain (CC0).