-
Notifications
You must be signed in to change notification settings - Fork 4
API Reference
Mattias Aabmets edited this page Mar 18, 2025
·
12 revisions
- Key Encapsulation Mechanisms
- Digital Signature Schemes
- The Krypton Cipher
- Key Derivation Functions
- Utilities
- Compilation Tools
class MLKEM_512(BaseKEM):
variant: PQAVariant
spec: AlgoSpec
def __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."""
@property
def param_sizes(self) -> KEMParamSizes:
"""Returns the size of the params of this KEM algorithm."""
def keygen(self) -> tuple[bytes, bytes]:
"""Returns a tuple of public key and secret key bytes."""
def encaps(self, public_key: bytes) -> tuple[bytes, bytes]:
"""Returns a tuple of ciphertext and shared secret bytes."""
def decaps(self, secret_key: bytes, cipher_text: bytes) -> bytes:
"""Returns the bytes of the decapsulated shared secret."""
def armor(self, key_bytes: bytes) -> str:
"""Returns a base64-encoded ASCII string of the key bytes."""
def dearmor(self, armored_key: str) -> bytes:
"""Returns the key bytes from an armored key ASCII string."""class MLKEM_768(BaseKEM):
variant: PQAVariant
spec: AlgoSpec
def __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."""
@property
def param_sizes(self) -> KEMParamSizes:
"""Returns the size of the params of this KEM algorithm."""
def keygen(self) -> tuple[bytes, bytes]:
"""Returns a tuple of public key and secret key bytes."""
def encaps(self, public_key: bytes) -> tuple[bytes, bytes]:
"""Returns a tuple of ciphertext and shared secret bytes."""
def decaps(self, secret_key: bytes, cipher_text: bytes) -> bytes:
"""Returns the bytes of the decapsulated shared secret."""
def armor(self, key_bytes: bytes) -> str:
"""Returns a base64-encoded ASCII string of the key bytes."""
def dearmor(self, armored_key: str) -> bytes:
"""Returns the key bytes from an armored key ASCII string."""class MLKEM_1024(BaseKEM):
variant: PQAVariant
spec: AlgoSpec
def __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."""
@property
def param_sizes(self) -> KEMParamSizes:
"""Returns the size of the params of this KEM algorithm."""
def keygen(self) -> tuple[bytes, bytes]:
"""Returns a tuple of public key and secret key bytes."""
def encaps(self, public_key: bytes) -> tuple[bytes, bytes]:
"""Returns a tuple of ciphertext and shared secret bytes."""
def decaps(self, secret_key: bytes, cipher_text: bytes) -> bytes:
"""Returns the bytes of the decapsulated shared secret."""
def armor(self, key_bytes: bytes) -> str:
"""Returns a base64-encoded ASCII string of the key bytes."""
def dearmor(self, armored_key: str) -> bytes:
"""Returns the key bytes from an armored key ASCII string."""class MLDSA_44(BaseDSS):
variant: PQAVariant
spec: AlgoSpec
def __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."""
@property
def param_sizes(self) -> DSSParamSizes:
"""Returns the size of the params of this DSS algorithm."""
def keygen(self) -> tuple[bytes, bytes]:
"""Returns a tuple of public key and secret key bytes."""
def sign(self, secret_key: bytes, message: bytes) -> bytes:
"""Returns bytes of the generated signature."""
def verify(
self,
public_key: bytes,
message: bytes,
signature: bytes,
*,
raises: bool = True
) -> bool:
"""Returns True on successful signature verification."""
def sign_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."""
def verify_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."""
def armor(self, key_bytes: bytes) -> str:
"""Returns a base64-encoded ASCII string of the key bytes."""
def dearmor(self, armored_key: str) -> bytes:
"""Returns the key bytes from an armored key ASCII string."""class MLDSA_65(BaseDSS):
variant: PQAVariant
spec: AlgoSpec
def __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."""
@property
def param_sizes(self) -> DSSParamSizes:
"""Returns the size of the params of this DSS algorithm."""
def keygen(self) -> tuple[bytes, bytes]:
"""Returns a tuple of public key and secret key bytes."""
def sign(self, secret_key: bytes, message: bytes) -> bytes:
"""Returns bytes of the generated signature."""
def verify(
self,
public_key: bytes,
message: bytes,
signature: bytes,
*,
raises: bool = True
) -> bool:
"""Returns True on successful signature verification."""
def sign_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."""
def verify_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."""
def armor(self, key_bytes: bytes) -> str:
"""Returns a base64-encoded ASCII string of the key bytes."""
def dearmor(self, armored_key: str) -> bytes:
"""Returns the key bytes from an armored key ASCII string."""class MLDSA_87(BaseDSS):
variant: PQAVariant
spec: AlgoSpec
def __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."""
@property
def param_sizes(self) -> DSSParamSizes:
"""Returns the size of the params of this DSS algorithm."""
def keygen(self) -> tuple[bytes, bytes]:
"""Returns a tuple of public key and secret key bytes."""
def sign(self, secret_key: bytes, message: bytes) -> bytes:
"""Returns bytes of the generated signature."""
def verify(
self,
public_key: bytes,
message: bytes,
signature: bytes,
*,
raises: bool = True
) -> bool:
"""Returns True on successful signature verification."""
def sign_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."""
def verify_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."""
def armor(self, key_bytes: bytes) -> str:
"""Returns a base64-encoded ASCII string of the key bytes."""
def dearmor(self, armored_key: str) -> bytes:
"""Returns the key bytes from an armored key ASCII string."""class FALCON_512(BaseDSS):
variant: PQAVariant
spec: AlgoSpec
def __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."""
@property
def param_sizes(self) -> DSSParamSizes:
"""Returns the size of the params of this DSS algorithm."""
def keygen(self) -> tuple[bytes, bytes]:
"""Returns a tuple of public key and secret key bytes."""
def sign(self, secret_key: bytes, message: bytes) -> bytes:
"""Returns bytes of the generated signature."""
def verify(
self,
public_key: bytes,
message: bytes,
signature: bytes,
*,
raises: bool = True
) -> bool:
"""Returns True on successful signature verification."""
def sign_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."""
def verify_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."""
def armor(self, key_bytes: bytes) -> str:
"""Returns a base64-encoded ASCII string of the key bytes."""
def dearmor(self, armored_key: str) -> bytes:
"""Returns the key bytes from an armored key ASCII string."""class FALCON_1024(BaseDSS):
variant: PQAVariant
spec: AlgoSpec
def __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."""
@property
def param_sizes(self) -> DSSParamSizes:
"""Returns the size of the params of this DSS algorithm."""
def keygen(self) -> tuple[bytes, bytes]:
"""Returns a tuple of public key and secret key bytes."""
def sign(self, secret_key: bytes, message: bytes) -> bytes:
"""Returns bytes of the generated signature."""
def verify(
self,
public_key: bytes,
message: bytes,
signature: bytes,
*,
raises: bool = True
) -> bool:
"""Returns True on successful signature verification."""
def sign_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."""
def verify_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."""
def armor(self, key_bytes: bytes) -> str:
"""Returns a base64-encoded ASCII string of the key bytes."""
def dearmor(self, armored_key: str) -> bytes:
"""Returns the key bytes from an armored key ASCII string."""class FAST_SPHINCS(BaseDSS):
variant: PQAVariant
spec: AlgoSpec
def __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."""
@property
def param_sizes(self) -> DSSParamSizes:
"""Returns the size of the params of this DSS algorithm."""
def keygen(self) -> tuple[bytes, bytes]:
"""Returns a tuple of public key and secret key bytes."""
def sign(self, secret_key: bytes, message: bytes) -> bytes:
"""Returns bytes of the generated signature."""
def verify(
self,
public_key: bytes,
message: bytes,
signature: bytes,
*,
raises: bool = True
) -> bool:
"""Returns True on successful signature verification."""
def sign_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."""
def verify_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."""
def armor(self, key_bytes: bytes) -> str:
"""Returns a base64-encoded ASCII string of the key bytes."""
def dearmor(self, armored_key: str) -> bytes:
"""Returns the key bytes from an armored key ASCII string."""class SMALL_SPHINCS(BaseDSS):
variant: PQAVariant
spec: AlgoSpec
def __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."""
@property
def param_sizes(self) -> DSSParamSizes:
"""Returns the size of the params of this DSS algorithm."""
def keygen(self) -> tuple[bytes, bytes]:
"""Returns a tuple of public key and secret key bytes."""
def sign(self, secret_key: bytes, message: bytes) -> bytes:
"""Returns bytes of the generated signature."""
def verify(
self,
public_key: bytes,
message: bytes,
signature: bytes,
*,
raises: bool = True
) -> bool:
"""Returns True on successful signature verification."""
def sign_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."""
def verify_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."""
def armor(self, key_bytes: bytes) -> str:
"""Returns a base64-encoded ASCII string of the key bytes."""
def dearmor(self, armored_key: str) -> bytes:
"""Returns the key bytes from an armored key ASCII string."""class Krypton:
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.
"""
def flush(self) -> None:
"""Resets the ciphers internal state."""
def begin_encryption(self, header: bytes = b'') -> None:
"""Prepares the Krypton instance for encryption mode."""
def encrypt(self, plaintext: bytes) -> bytes:
"""Encrypts plaintext into ciphertext."""
def finish_encryption(self) -> bytes:
"""Finalizes the encryption process."""
def begin_decryption(self, verif_data: bytes, header: bytes = b'') -> None:
"""Prepares the Krypton instance for decryption mode."""
def decrypt(self, ciphertext: bytes) -> bytes:
"""Decrypts ciphertext into plaintext."""
def finish_decryption(self) -> None:
"""Finalizes the decryption process."""class KryptonFile:
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.
"""
def encrypt(
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`.
"""
def decrypt_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.
"""
def decrypt_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.
"""
@classmethod
def read_file_header(cls, encrypted_file: str | Path) -> bytes:
"""Reads the header bytes from a Krypton ciphertext file."""class KryptonKEM:
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.
"""
def encrypt(
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.
"""
def decrypt_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.
"""
def decrypt_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.
"""class Argon2:
Hash = Argon2Hash
Key = Argon2Keyclass Argon2Hash(BaseArgon2):
public_hash: Optional[str] = None
rehashed: bool = False
verified: bool = False
def __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.
"""class Argon2Key(BaseArgon2):
secret_key: Optional[bytes] = None
public_salt: Optional[str] = None
def __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.
"""class KKDF:
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.
"""@dataclass
class DecryptedFile:
plaintext: bytes
header: bytesclass MemCost:
MB = MemCostMB
GB = MemCostGB
class MemCostMB(dict):
def __init__(self, size: Literal[32, 64, 128, 256, 512]) -> None:
"""Converts the size input argument value of megabytes to kilobytes."""
class MemCostGB(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."""class KDFParams(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.
"""class PQAVariant(ExtendedEnum):
REF = "clean"
OPT_AMD = "avx2"
OPT_ARM = "aarch64"class PQAType(ExtendedEnum):
KEM = "crypto_kem"
DSS = "crypto_sign"@dataclass(frozen=True)
class AlgoSpec:
type: PQAType
src_subdir: Path
pqclean_name: str
class_name: strclass AlgoSpecsList(list):
def pqclean_names(self: list[AlgoSpec]) -> list[str]:
"""Returns the pqclean_names of all contained AlgoSpecs."""
def armor_names(self: list[AlgoSpec], pqa_type: PQAType | None = None) -> list[str]:
"""Returns the armor_names of all contained AlgoSpecs. Permits filtering by PQAType."""
def filter(self, armor_names: list[str], invert: bool = False) -> list[AlgoSpec]:
"""Returns specs which exist in armor_names. Can invert filtering behavior."""
SupportedAlgos: AlgoSpecList[AlgoSpec]@dataclass
class SignedFile:
algo_name: str
signature: bytes
file_digest: bytesclass ChunkSize:
KB = ChunkSizeKB
MB = ChunkSizeMB
class ChunkSizeKB(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."""
class ChunkSizeMB(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."""@dataclass(frozen=True)
class Target:
spec: const.AlgoSpec
variant: const.PQAVariant
source_dir: Path
required_flags: list[str]
accepted: boolclass Compiler:
@classmethod
def run(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.
"""