Skip to content

API Reference

Jump to bottom
Mattias Aabmets edited this page Mar 18, 2025 · 12 revisions

Table of Contents

  1. Key Encapsulation Mechanisms
  2. Digital Signature Schemes
  3. The Krypton Cipher
  4. Key Derivation Functions
  5. Utilities
  6. Compilation Tools

Key Encapsulation Mechanisms

MLKEM_512

classMLKEM_512(BaseKEM):
variant: PQAVariantspec: AlgoSpecdef__init__(self, variant: const.PQAVariant=None, *, allow_fallback: bool=True) ->None:
"""Initializes the MLKEM_512 key encapsulation mechanism algorithm instance with compiled C extension binaries."""@propertydefparam_sizes(self) ->KEMParamSizes: """Returns the size of the params of this KEM algorithm."""defkeygen(self) ->tuple[bytes, bytes]: """Returns a tuple of public key and secret key bytes."""defencaps(self, public_key: bytes) ->tuple[bytes, bytes]:
"""Returns a tuple of ciphertext and shared secret bytes."""defdecaps(self, secret_key: bytes, cipher_text: bytes) ->bytes:
"""Returns the bytes of the decapsulated shared secret."""defarmor(self, key_bytes: bytes) ->str:
"""Returns a base64-encoded ASCII string of the key bytes."""defdearmor(self, armored_key: str) ->bytes:
"""Returns the key bytes from an armored key ASCII string."""

Back to Top

MLKEM_768

classMLKEM_768(BaseKEM):
variant: PQAVariantspec: AlgoSpecdef__init__(self, variant: const.PQAVariant=None, *, allow_fallback: bool=True) ->None:
"""Initializes the MLKEM_768 key encapsulation mechanism algorithm instance with compiled C extension binaries."""@propertydefparam_sizes(self) ->KEMParamSizes: """Returns the size of the params of this KEM algorithm."""defkeygen(self) ->tuple[bytes, bytes]: """Returns a tuple of public key and secret key bytes."""defencaps(self, public_key: bytes) ->tuple[bytes, bytes]:
"""Returns a tuple of ciphertext and shared secret bytes."""defdecaps(self, secret_key: bytes, cipher_text: bytes) ->bytes:
"""Returns the bytes of the decapsulated shared secret."""defarmor(self, key_bytes: bytes) ->str:
"""Returns a base64-encoded ASCII string of the key bytes."""defdearmor(self, armored_key: str) ->bytes:
"""Returns the key bytes from an armored key ASCII string."""

Back to Top

MLKEM_1024

classMLKEM_1024(BaseKEM):
variant: PQAVariantspec: AlgoSpecdef__init__(self, variant: const.PQAVariant=None, *, allow_fallback: bool=True) ->None:
"""Initializes the MLKEM_1024 key encapsulation mechanism algorithm instance with compiled C extension binaries."""@propertydefparam_sizes(self) ->KEMParamSizes: """Returns the size of the params of this KEM algorithm."""defkeygen(self) ->tuple[bytes, bytes]: """Returns a tuple of public key and secret key bytes."""defencaps(self, public_key: bytes) ->tuple[bytes, bytes]:
"""Returns a tuple of ciphertext and shared secret bytes."""defdecaps(self, secret_key: bytes, cipher_text: bytes) ->bytes:
"""Returns the bytes of the decapsulated shared secret."""defarmor(self, key_bytes: bytes) ->str:
"""Returns a base64-encoded ASCII string of the key bytes."""defdearmor(self, armored_key: str) ->bytes:
"""Returns the key bytes from an armored key ASCII string."""

Back to Top

Digital Signature Schemes

MLDSA_44

classMLDSA_44(BaseDSS):
variant: PQAVariantspec: AlgoSpecdef__init__(self, variant: const.PQAVariant=None, *, allow_fallback: bool=True) ->None:
"""Initializes the MLDSA_44 digital signature scheme algorithm instance with compiled C extension binaries."""@propertydefparam_sizes(self) ->DSSParamSizes: """Returns the size of the params of this DSS algorithm."""defkeygen(self) ->tuple[bytes, bytes]: """Returns a tuple of public key and secret key bytes."""defsign(self, secret_key: bytes, message: bytes) ->bytes:
"""Returns bytes of the generated signature."""defverify(
self, public_key: bytes, message: bytes, signature: bytes, *, raises: bool=True
) ->bool:
"""Returns True on successful signature verification."""defsign_file(
self, secret_key: str|bytes, data_file: str|Path, callback: Optional[Callable] =None
) ->SignedFile:
"""Computes and signs the hash of the data file to generate the signature."""defverify_file(
self, public_key: str|bytes, data_file: str|Path, signature: bytes, callback: Optional[Callable] =None, *, raises: bool=True
) ->bool:
"""Verifies the signature against the computed hash of the data file."""defarmor(self, key_bytes: bytes) ->str:
"""Returns a base64-encoded ASCII string of the key bytes."""defdearmor(self, armored_key: str) ->bytes:
"""Returns the key bytes from an armored key ASCII string."""

Back to Top

MLDSA_65

classMLDSA_65(BaseDSS):
variant: PQAVariantspec: AlgoSpecdef__init__(self, variant: const.PQAVariant=None, *, allow_fallback: bool=True) ->None:
"""Initializes the MLDSA_65 digital signature scheme algorithm instance with compiled C extension binaries."""@propertydefparam_sizes(self) ->DSSParamSizes: """Returns the size of the params of this DSS algorithm."""defkeygen(self) ->tuple[bytes, bytes]: """Returns a tuple of public key and secret key bytes."""defsign(self, secret_key: bytes, message: bytes) ->bytes:
"""Returns bytes of the generated signature."""defverify(
self, public_key: bytes, message: bytes, signature: bytes, *, raises: bool=True
) ->bool:
"""Returns True on successful signature verification."""defsign_file(
self, secret_key: str|bytes, data_file: str|Path, callback: Optional[Callable] =None
) ->SignedFile:
"""Computes and signs the hash of the data file to generate the signature."""defverify_file(
self, public_key: str|bytes, data_file: str|Path, signature: bytes, callback: Optional[Callable] =None, *, raises: bool=True
) ->bool:
"""Verifies the signature against the computed hash of the data file."""defarmor(self, key_bytes: bytes) ->str:
"""Returns a base64-encoded ASCII string of the key bytes."""defdearmor(self, armored_key: str) ->bytes:
"""Returns the key bytes from an armored key ASCII string."""

Back to Top

MLDSA_87

classMLDSA_87(BaseDSS):
variant: PQAVariantspec: AlgoSpecdef__init__(self, variant: const.PQAVariant=None, *, allow_fallback: bool=True) ->None:
"""Initializes the MLDSA_87 digital signature scheme algorithm instance with compiled C extension binaries."""@propertydefparam_sizes(self) ->DSSParamSizes: """Returns the size of the params of this DSS algorithm."""defkeygen(self) ->tuple[bytes, bytes]: """Returns a tuple of public key and secret key bytes."""defsign(self, secret_key: bytes, message: bytes) ->bytes:
"""Returns bytes of the generated signature."""defverify(
self, public_key: bytes, message: bytes, signature: bytes, *, raises: bool=True
) ->bool:
"""Returns True on successful signature verification."""defsign_file(
self, secret_key: str|bytes, data_file: str|Path, callback: Optional[Callable] =None
) ->SignedFile:
"""Computes and signs the hash of the data file to generate the signature."""defverify_file(
self, public_key: str|bytes, data_file: str|Path, signature: bytes, callback: Optional[Callable] =None, *, raises: bool=True
) ->bool:
"""Verifies the signature against the computed hash of the data file."""defarmor(self, key_bytes: bytes) ->str:
"""Returns a base64-encoded ASCII string of the key bytes."""defdearmor(self, armored_key: str) ->bytes:
"""Returns the key bytes from an armored key ASCII string."""

Back to Top

FALCON_512

classFALCON_512(BaseDSS):
variant: PQAVariantspec: AlgoSpecdef__init__(self, variant: const.PQAVariant=None, *, allow_fallback: bool=True) ->None:
"""Initializes the FALCON_512 digital signature scheme algorithm instance with compiled C extension binaries."""@propertydefparam_sizes(self) ->DSSParamSizes: """Returns the size of the params of this DSS algorithm."""defkeygen(self) ->tuple[bytes, bytes]: """Returns a tuple of public key and secret key bytes."""defsign(self, secret_key: bytes, message: bytes) ->bytes:
"""Returns bytes of the generated signature."""defverify(
self, public_key: bytes, message: bytes, signature: bytes, *, raises: bool=True
) ->bool:
"""Returns True on successful signature verification."""defsign_file(
self, secret_key: str|bytes, data_file: str|Path, callback: Optional[Callable] =None
) ->SignedFile:
"""Computes and signs the hash of the data file to generate the signature."""defverify_file(
self, public_key: str|bytes, data_file: str|Path, signature: bytes, callback: Optional[Callable] =None, *, raises: bool=True
) ->bool:
"""Verifies the signature against the computed hash of the data file."""defarmor(self, key_bytes: bytes) ->str:
"""Returns a base64-encoded ASCII string of the key bytes."""defdearmor(self, armored_key: str) ->bytes:
"""Returns the key bytes from an armored key ASCII string."""

Back to Top

FALCON_1024

classFALCON_1024(BaseDSS):
variant: PQAVariantspec: AlgoSpecdef__init__(self, variant: const.PQAVariant=None, *, allow_fallback: bool=True) ->None:
"""Initializes the FALCON_1024 digital signature scheme algorithm instance with compiled C extension binaries."""@propertydefparam_sizes(self) ->DSSParamSizes: """Returns the size of the params of this DSS algorithm."""defkeygen(self) ->tuple[bytes, bytes]: """Returns a tuple of public key and secret key bytes."""defsign(self, secret_key: bytes, message: bytes) ->bytes:
"""Returns bytes of the generated signature."""defverify(
self, public_key: bytes, message: bytes, signature: bytes, *, raises: bool=True
) ->bool:
"""Returns True on successful signature verification."""defsign_file(
self, secret_key: str|bytes, data_file: str|Path, callback: Optional[Callable] =None
) ->SignedFile:
"""Computes and signs the hash of the data file to generate the signature."""defverify_file(
self, public_key: str|bytes, data_file: str|Path, signature: bytes, callback: Optional[Callable] =None, *, raises: bool=True
) ->bool:
"""Verifies the signature against the computed hash of the data file."""defarmor(self, key_bytes: bytes) ->str:
"""Returns a base64-encoded ASCII string of the key bytes."""defdearmor(self, armored_key: str) ->bytes:
"""Returns the key bytes from an armored key ASCII string."""

Back to Top

FAST_SPHINCS

classFAST_SPHINCS(BaseDSS):
variant: PQAVariantspec: AlgoSpecdef__init__(self, variant: const.PQAVariant=None, *, allow_fallback: bool=True) ->None:
"""Initializes the FAST_SPHINCS digital signature scheme algorithm instance with compiled C extension binaries."""@propertydefparam_sizes(self) ->DSSParamSizes: """Returns the size of the params of this DSS algorithm."""defkeygen(self) ->tuple[bytes, bytes]: """Returns a tuple of public key and secret key bytes."""defsign(self, secret_key: bytes, message: bytes) ->bytes:
"""Returns bytes of the generated signature."""defverify(
self, public_key: bytes, message: bytes, signature: bytes, *, raises: bool=True
) ->bool:
"""Returns True on successful signature verification."""defsign_file(
self, secret_key: str|bytes, data_file: str|Path, callback: Optional[Callable] =None
) ->SignedFile:
"""Computes and signs the hash of the data file to generate the signature."""defverify_file(
self, public_key: str|bytes, data_file: str|Path, signature: bytes, callback: Optional[Callable] =None, *, raises: bool=True
) ->bool:
"""Verifies the signature against the computed hash of the data file."""defarmor(self, key_bytes: bytes) ->str:
"""Returns a base64-encoded ASCII string of the key bytes."""defdearmor(self, armored_key: str) ->bytes:
"""Returns the key bytes from an armored key ASCII string."""

Back to Top

SMALL_SPHINCS

classSMALL_SPHINCS(BaseDSS):
variant: PQAVariantspec: AlgoSpecdef__init__(self, variant: const.PQAVariant=None, *, allow_fallback: bool=True) ->None:
"""Initializes the SMALL_SPHINCS digital signature scheme algorithm instance with compiled C extension binaries."""@propertydefparam_sizes(self) ->DSSParamSizes: """Returns the size of the params of this DSS algorithm."""defkeygen(self) ->tuple[bytes, bytes]: """Returns a tuple of public key and secret key bytes."""defsign(self, secret_key: bytes, message: bytes) ->bytes:
"""Returns bytes of the generated signature."""defverify(
self, public_key: bytes, message: bytes, signature: bytes, *, raises: bool=True
) ->bool:
"""Returns True on successful signature verification."""defsign_file(
self, secret_key: str|bytes, data_file: str|Path, callback: Optional[Callable] =None
) ->SignedFile:
"""Computes and signs the hash of the data file to generate the signature."""defverify_file(
self, public_key: str|bytes, data_file: str|Path, signature: bytes, callback: Optional[Callable] =None, *, raises: bool=True
) ->bool:
"""Verifies the signature against the computed hash of the data file."""defarmor(self, key_bytes: bytes) ->str:
"""Returns a base64-encoded ASCII string of the key bytes."""defdearmor(self, armored_key: str) ->bytes:
"""Returns the key bytes from an armored key ASCII string."""

Back to Top

The Krypton Cipher

Krypton

classKrypton:
def__init__(
self, secret_key: bytes, context: bytes=b'', chunk_size: ChunkSize.Atd=None
) ->None:
""" Creates a new Krypton instance for encrypting and/or decrypting multiple messages with the same secret key and configuration. """defflush(self) ->None:
"""Resets the ciphers internal state."""defbegin_encryption(self, header: bytes=b'') ->None:
"""Prepares the Krypton instance for encryption mode."""defencrypt(self, plaintext: bytes) ->bytes:
"""Encrypts plaintext into ciphertext."""deffinish_encryption(self) ->bytes:
"""Finalizes the encryption process."""defbegin_decryption(self, verif_data: bytes, header: bytes=b'') ->None:
"""Prepares the Krypton instance for decryption mode."""defdecrypt(self, ciphertext: bytes) ->bytes:
"""Decrypts ciphertext into plaintext."""deffinish_decryption(self) ->None:
"""Finalizes the decryption process."""

Back to Top

KryptonFile

classKryptonFile:
def__init__(
self, secret_key: bytes, context: bytes=b'', callback: Optional[Callable] =None, chunk_size: ChunkSize.Atd=None
) ->None:
""" Creates a new KryptonFile instance for encrypting and/or decrypting multiple files of arbitrary sizes with the same secret key using the same configuration. """defencrypt(
self, data_file: str|Path, output_file: str|Path, header: bytes=b''
) ->None:
""" Reads plaintext from the `data_file` in chunks and encrypts them into ciphertext, writing the encrypted ciphertext chunks into the output_file. The header data is also written into the `output_file`. """defdecrypt_to_file(
self, encrypted_file: str|Path, output_file: str|Path
) ->bytes:
""" Reads ciphertext from the `encrypted_file` in chunks and decrypts them into plaintext, writing the decrypted plaintext chunks into the output_file. """defdecrypt_to_memory(self, encrypted_file: str|Path) ->DecryptedFile:
""" Reads ciphertext from the `encrypted_file` in chunks and decrypts them into plaintext, storing the entire decrypted plaintext into memory. """@classmethoddefread_file_header(cls, encrypted_file: str|Path) ->bytes:
"""Reads the header bytes from a Krypton ciphertext file."""

Back to Top

KryptonKEM

classKryptonKEM:
def__init__(
self, kem_class: Type[BaseKEM],
kdf_params: KDFParams=None,
context: bytes=b"quantcrypt",
callback: Optional[Callable] =None, chunk_size: ChunkSize.Atd=None
) ->None:
""" Creates a new KryptonKEM instance for encrypting and/or decrypting multiple files of arbitrary sizes with KEM public and private keys using the same configuration. Internally uses **KryptonFile** class. """defencrypt(
self, public_key: str|bytes,
data_file: str|Path, output_file: str|Path
) ->None:
""" Encapsulates the provided public_key into a shared secret, which is transformed with Argon2.Key into a 64 byte key for the KryptonFile class. Then, encrypts the plaintext data from the data_file and writes it into  the output_file along with any necessary metadata to decrypt the file  with the secret_key of the KEM keypair. """defdecrypt_to_file(
self, secret_key: str|bytes,
encrypted_file: str|Path, output_file: str|Path=None
) ->bytes:
""" Decapsulates the shared secret from the file metadata using the  provided KEM secret key, which is then transformed with Argon2.Key into a 64 byte key for the KryptonFile class. Then, decrypts the ciphertext data from the encrypted file and writes the plaintext  into the output_file, recreating the original plaintext file. """defdecrypt_to_memory(
self, secret_key: str|bytes, encrypted_file: str|Path
) ->DecryptedFile:
""" Decapsulates the shared secret from the file metadata using the  provided KEM secret key, which is then transformed with Argon2.Key into a 64 byte key for the KryptonFile class. Then, decrypts the ciphertext data from the encrypted file and writes the plaintext  into memory. **Note:** Do NOT decrypt huge files (>100MB) into  memory, use your best judgement. """

Back to Top

Key Derivation Functions

Argon2

classArgon2:
Hash=Argon2HashKey=Argon2Key

Back to Top

Argon2Hash

classArgon2Hash(BaseArgon2):
public_hash: Optional[str] =Nonerehashed: bool=Falseverified: bool=Falsedef__init__(
self,
password: str|bytes,
verif_hash: str|bytes=None,
*,
min_years: int=1,
params: KDFParams=None
) ->None:
""" Computes the Argon2 hash immediately on class  instantiation using the provided parameters. """

Back to Top

Argon2Key

classArgon2Key(BaseArgon2):
secret_key: Optional[bytes] =Nonepublic_salt: Optional[str] =Nonedef__init__(
self,
password: str|bytes,
public_salt: str|bytes=None,
*,
min_years: int=10,
params: KDFParams=None
) ->None:
""" Computes the Argon2 derived secret key immediately on  class instantiation using the provided parameters. """

Back to Top

KKDF

classKKDF:
def__new__(
cls,
master: bytes,
key_len: int=32,
num_keys: int=1,
salt: bytes=None,
context: bytes=None
) ->tuple[bytes, ...]:
""" Computes the KMAC-KDF derived secret keys immediately  on class instantiation using the provided parameters.  Returns the generated keys as a tuple of bytes. """

Back to Top

Utilities

DecryptedFile

@dataclassclassDecryptedFile:
plaintext: bytesheader: bytes

Back to Top

MemCost

classMemCost:
MB=MemCostMBGB=MemCostGBclassMemCostMB(dict):
def__init__(self, size: Literal[32, 64, 128, 256, 512]) ->None:
"""Converts the size input argument value of megabytes to kilobytes."""classMemCostGB(dict):
def__init__(self, size: Literal[1, 2, 3, 4, 5, 6, 7, 8]) ->None:
"""Converts the size input argument value of gigabytes to kilobytes."""

Back to Top

KDFParams

classKDFParams(DotMap):
def__init__(
self,
memory_cost: MemCostMB|MemCostGB,
parallelism: int,
time_cost: int,
hash_len: int=32,
salt_len: int=32
) ->None:
""" Custom parameters for altering the security level of key derivation functions. """

Back to Top

PQAVariant

classPQAVariant(ExtendedEnum):
REF="clean"OPT_AMD="avx2"OPT_ARM="aarch64"

Back to Top

PQAType

classPQAType(ExtendedEnum):
KEM="crypto_kem"DSS="crypto_sign"

Back to Top

AlgoSpec

@dataclass(frozen=True)classAlgoSpec:
type: PQATypesrc_subdir: Pathpqclean_name: strclass_name: str

Back to Top

SupportedAlgos

classAlgoSpecsList(list):
defpqclean_names(self: list[AlgoSpec]) ->list[str]:
"""Returns the pqclean_names of all contained AlgoSpecs."""defarmor_names(self: list[AlgoSpec], pqa_type: PQAType|None=None) ->list[str]:
"""Returns the armor_names of all contained AlgoSpecs. Permits filtering by PQAType."""deffilter(self, armor_names: list[str], invert: bool=False) ->list[AlgoSpec]:
"""Returns specs which exist in armor_names. Can invert filtering behavior."""SupportedAlgos: AlgoSpecList[AlgoSpec]

Back to Top

SignedFile

@dataclassclassSignedFile:
algo_name: strsignature: bytesfile_digest: bytes

Back to Top

ChunkSize

classChunkSize:
KB=ChunkSizeKBMB=ChunkSizeMBclassChunkSizeKB(dict):
def__init__(self, size: Literal[1, 2, 4, 8, 16, 32, 64, 128, 256]) ->None:
"""Converts the size input argument value of kilobytes to bytes."""classChunkSizeMB(dict):
def__init__(self, size: Literal[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]) ->None:
"""Converts the size input argument value of megabytes to bytes."""

Back to Top

Compilation Tools

Target

@dataclass(frozen=True)classTarget:
spec: const.AlgoSpecvariant: const.PQAVariantsource_dir: Pathrequired_flags: list[str]
accepted: bool

Back to Top

Compiler

classCompiler:
@classmethoddefrun(cls,
target_variants: list[const.PQAVariant] =None,
target_algos: list[const.AlgoSpec] =None,
*,
in_subprocess: bool=False,
verbose: bool=False,
debug: bool=False,
) ->subprocess.Popen|list[Target]:
""" Compiles the target variants of the target algorithms and stores the  compiled binaries within the internals of the QuantCrypt library. """

Back to Top

Clone this wiki locally