Backends (quantum_safe.backends)

Cryptographic backend adapters. You rarely need to interact with these directly — use get_kem_backend() and get_signature_backend() only when you need to force a specific backend.

quantum_safe.backends.get_kem_backend(name='auto')

Return the KEM backend for the given name.

Parameters:

name (str) – “auto”, “liboqs”, or “rustcrypto”. Falls back through the priority list if “auto”.

Raises:

• BackendNotAvailable – if the requested backend is not installed.

• ValueError – if the backend name is unknown.

Return type:

AbstractKEMBackend

quantum_safe.backends.get_signature_backend(name='auto')

Return the signature backend for the given name.

Parameters:

name (str)

Return type:

AbstractSignatureBackend

quantum_safe.backends.list_available_backends()

Return availability status for all known backends.

Useful for diagnostics: python -c “from quantum_safe.backends import list_available_backends; print(list_available_backends())”.

Return type:

dict[str, bool]

Abstract base classes

class quantum_safe.backends.base.AbstractKEMBackend

Bases: ABC

Interface for KEM (Key Encapsulation Mechanism) backends.

Implementations wrap a specific cryptographic library (liboqs, RustCrypto, etc.) and expose a uniform interface for keygen, encap, and decap.

All methods are synchronous. If you need async, call from a thread pool.

abstractmethod supported_algorithms()

Return metadata for all KEM algorithms this backend supports.

Return type:

list[AlgorithmInfo]

abstractmethod keygen(algorithm)

Generate a key pair.

Parameters:

algorithm (str) – Algorithm name, e.g. “ML-KEM-768”

Return type:

tuple[bytes, bytes]

Returns:

(public_key_bytes, secret_key_bytes)

Raises:

• UnsupportedAlgorithm – if the algorithm is not supported

• KeyGenerationError – if keygen fails (RNG failure, etc.)

abstractmethod encapsulate(algorithm, public_key)

Encapsulate: generate a ciphertext and shared secret.

Parameters:

• algorithm (str) – Algorithm name

• public_key (bytes) – Recipient’s public key bytes

Return type:

tuple[bytes, bytes]

Returns:

(ciphertext_bytes, shared_secret_bytes)

Raises:

• UnsupportedAlgorithm – if the algorithm is not supported

• CryptoError – if encapsulation fails

abstractmethod decapsulate(algorithm, secret_key, ciphertext)

Decapsulate: recover the shared secret from a ciphertext.

Parameters:

• algorithm (str) – Algorithm name

• secret_key (bytes) – Recipient’s secret key bytes

• ciphertext (bytes) – Ciphertext from encapsulate()

Return type:

bytes

Returns:

shared_secret_bytes (32 bytes for all standardized algorithms)

Raises:

• DecapsulationError – if decapsulation fails — NEVER reveal why

• UnsupportedAlgorithm – if the algorithm is not supported

is_available()

Return True if this backend is installed and functional.

Default implementation tries to generate a key with the first supported algorithm. Override if there’s a cheaper availability check.

Return type:

bool

class quantum_safe.backends.base.AbstractSignatureBackend

Bases: ABC

Interface for digital signature backends.

abstractmethod supported_algorithms()

Return metadata for all signature algorithms this backend supports.

Return type:

list[AlgorithmInfo]

abstractmethod keygen(algorithm)

Generate a signing key pair.

Return type:

tuple[bytes, bytes]

Returns:

(public_key_bytes, secret_key_bytes)

Parameters:

algorithm (str)

abstractmethod sign(algorithm, secret_key, message, context=b'')

Sign a message.

Parameters:

• algorithm (str) – Algorithm name, e.g. “ML-DSA-65”

• secret_key (bytes) – Signer’s secret key bytes

• message (bytes) – Message to sign (arbitrary length)

• context (bytes) – Domain-separation context (up to 255 bytes, per FIPS 204)

Return type:

bytes

Returns:

signature_bytes

Raises:

• UnsupportedAlgorithm – if the algorithm is not supported

• CryptoError – if signing fails

abstractmethod verify(algorithm, public_key, message, signature, context=b'')

Verify a signature.

Parameters:

• algorithm (str) – Algorithm name

• public_key (bytes) – Signer’s public key bytes

• message (bytes) – The signed message

• signature (bytes) – Signature bytes from sign()

• context (bytes) – Must match the context used during signing

Return type:

bool

Returns:

True if valid, False if invalid.

Note: This returns bool rather than raising on invalid signatures. The caller (Sign.verify()) is responsible for raising VerificationError. Backends should NOT raise on invalid signatures — return False.

is_available()

Return True if this backend is installed and functional.

Return type:

bool

liboqs backend

class quantum_safe.backends.liboqs.LiboqsKEMBackend

Bases: AbstractKEMBackend

KEM backend using liboqs-python.

supported_algorithms()

Return algorithms supported by this backend.

We only return algorithms that are actually enabled in the installed liboqs build — some builds omit BIKE or HQC for size/license reasons.

Return type:

list[AlgorithmInfo]

keygen(algorithm)

Generate an ML-KEM (or other KEM) key pair.

Returns (public_key_bytes, secret_key_bytes).

Parameters:

algorithm (str)

Return type:

tuple[bytes, bytes]

encapsulate(algorithm, public_key)

Encapsulate a shared secret under the given public key.

Returns (ciphertext_bytes, shared_secret_bytes).

Parameters:

• algorithm (str)

• public_key (bytes)

Return type:

tuple[bytes, bytes]

decapsulate(algorithm, secret_key, ciphertext)

Decapsulate a shared secret from a ciphertext.

Returns shared_secret_bytes.

IMPORTANT: liboqs ML-KEM implements implicit rejection (per FIPS 203 §6.3) — a malformed ciphertext returns a pseudorandom value rather than raising an exception. We check the output length to detect the most obvious failure modes, but we cannot distinguish a bad ciphertext from a good one by inspecting the output.

Parameters:

• algorithm (str)

• secret_key (bytes)

• ciphertext (bytes)

Return type:

bytes

is_available()

Check if liboqs is importable and has at least ML-KEM-768.

Return type:

bool

class quantum_safe.backends.liboqs.LiboqsSignatureBackend

Bases: AbstractSignatureBackend

Signature backend using liboqs-python.

supported_algorithms()

Return metadata for all signature algorithms this backend supports.

Return type:

list[AlgorithmInfo]

keygen(algorithm)

Generate a signing key pair.

Return type:

tuple[bytes, bytes]

Returns:

(public_key_bytes, secret_key_bytes)

Parameters:

algorithm (str)

sign(algorithm, secret_key, message, context=b'')

Sign a message.

FIPS 204 §5.2 specifies that the context is prepended to the message before hashing. liboqs-python’s Signature.sign() doesn’t directly expose the context parameter in older versions, so we prepend it manually using the format:

context_len (1 byte) || context || message

This is consistent with the HashML-DSA construction in FIPS 204 §5.4. When liboqs exposes context natively (v0.11+), we’ll use that instead.

Parameters:

• algorithm (str)

• secret_key (bytes)

• message (bytes)

• context (bytes)

Return type:

bytes

verify(algorithm, public_key, message, signature, context=b'')

Verify a signature. Returns True if valid, False if not.

Parameters:

• algorithm (str)

• public_key (bytes)

• message (bytes)

• signature (bytes)

• context (bytes)

Return type:

bool

is_available()

Return True if this backend is installed and functional.

Return type:

bool