API Reference - aabmets/quantcrypt GitHub Wiki

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 = Argon2Key

class 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: bytes

class 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: str

class 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: bytes

class 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: bool

class 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.
        """