### Asymmetric File Encryption Setup with KryptonKEM

Source: https://github.com/aabmets/quantcrypt/wiki/Code-Examples

Initializes KryptonKEM for asymmetric file encryption by instantiating a KEM algorithm and generating a key pair.

```python
from pathlib import Path
from quantcrypt.kem import MLKEM_1024
from quantcrypt.cipher import KryptonKEM

# First we instantiate the KEM algorithm to generate a keypair.
kem = MLKEM_1024()
public_key, secret_key = kem.keygen()

# We need to provide KryptonKEM with the class of the 
```

--------------------------------

### Install QuantCrypt with UV

Source: https://github.com/aabmets/quantcrypt/blob/main/README.md

Use this command to add QuantCrypt to your project with UV, the recommended package installer.

```shell
uv add quantcrypt
```

--------------------------------

### Install QuantCrypt with Pip

Source: https://github.com/aabmets/quantcrypt/blob/main/README.md

Install QuantCrypt using pip, the standard Python package installer.

```shell
pip install quantcrypt
```

--------------------------------

### Install QuantCrypt with Poetry

Source: https://github.com/aabmets/quantcrypt/blob/main/README.md

Add QuantCrypt to your project dependencies using Poetry.

```shell
poetry add quantcrypt
```

--------------------------------

### Import QuantCrypt Modules

Source: https://github.com/aabmets/quantcrypt/blob/main/README.md

Import key modules from the QuantCrypt library for cryptographic operations. Ensure optional dependencies are installed if using the 'compiler' module.

```python
from quantcrypt import (
    kem,      # Key Encapsulation Mechanism algos   - public-key cryptography
    dss,      # Digital Signature Scheme algos      - secret-key signatures
    cipher,   # The Krypton Cipher                  - symmetric cipher based on AES-256
    kdf,      # Argon2 helpers + KMAC-KDF           - key derivation functions
    errors,   # All errors QuantCrypt may raise     - also available from other modules
    utils,    # Helper utilities from all modules   - gathered into one module
    compiler  # Tools for compiling PQA binaries    - requires optional dependencies
)
```

--------------------------------

### Fast Key Derivation with KKDF

Source: https://github.com/aabmets/quantcrypt/wiki/Code-Examples

Provides an example of fast key derivation using the KKDF function. This method is efficient for deriving multiple keys from a master secret key.

```python
import secrets
from quantcrypt.kdf import KKDF

secret_key = secrets.token_bytes(64)

keys = KKDF(
    master=secret_key, 
    key_len=64,
    num_keys=1
)

assert isinstance(keys, tuple)
assert isinstance(keys[0], bytes)
assert len(keys[0]) == 64
```

--------------------------------

### QuantCrypt CLI Help Commands

Source: https://github.com/aabmets/quantcrypt/blob/main/README.md

View help information and versions for the QuantCrypt command-line interface (qclib). Activate your virtual environment to access these commands.

```shell
qclib --help
qclib --version

qclib info --help
qclib keygen --help
qclib encrypt --help
qclib decrypt --help
qclib sign --help
qclib verify --help
qclib remove --help
qclib compile --help
```

--------------------------------

### FAST_SPHINCS Algorithm

Source: https://github.com/aabmets/quantcrypt/wiki/API-Reference

Provides methods for initializing, generating keys, signing, and verifying messages and files using the FAST_SPHINCS algorithm. Supports key armoring and de-armoring.

```python
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."""

```

--------------------------------

### Encrypt and Decrypt Files with KryptonKEM

Source: https://github.com/aabmets/quantcrypt/wiki/Code-Examples

Demonstrates how to encrypt a plaintext file to a ciphertext file and decrypt it back using KryptonKEM. Ensure the plaintext file exists and ciphertext file will be overwritten if it exists.

```python
from quantcrypt.kem import KryptonKEM
from pathlib import Path

krypton = KryptonKEM(MLKEM_1024)

plaintext_file = Path("/absolute/path/to/plaintext_file.any")
ciphertext_file = Path("/absolute/path/to/ciphertext_file.any")

krypton.encrypt(public_key, plaintext_file, ciphertext_file)

plaintext_file_copy = Path("/absolute/path/to/plaintext_file_copy.any")
krypton.decrypt_to_file(secret_key, ciphertext_file, plaintext_file_copy)
plaintext_data = krypton.decrypt_to_memory(secret_key, ciphertext_file)
```

--------------------------------

### FALCON_1024 Algorithm

Source: https://github.com/aabmets/quantcrypt/wiki/API-Reference

Provides methods for initializing, generating keys, signing, and verifying messages and files using the FALCON_1024 algorithm. Supports key armoring and de-armoring.

```python
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."""

```

--------------------------------

### Symmetric File Encryption with KryptonFile

Source: https://github.com/aabmets/quantcrypt/wiki/Code-Examples

Demonstrates symmetric encryption and decryption of files using KryptonFile. The secret key must be 64 bytes long.

```python
import secrets
from pathlib import Path
from quantcrypt.cipher import KryptonFile

# Krypton requires the symmetric secret key to be 64 bytes long.
secret_key = secrets.token_bytes(64)

# The plaintext file, which must exist, can be of any type and any size. 
plaintext_file = Path("/absolute/path/to/plaintext_file.any")

# If the ciphertext_file exists, it will be overwritten.
ciphertext_file = Path("/absolute/path/to/ciphertext_file.any")

# Create a Krypton instance with the secret key and encrypt the
# plaintext file contents into the designated ciphertext file.
krypton = KryptonFile(secret_key)
krypton.encrypt(plaintext_file, ciphertext_file)

# The ciphertext file can be decrypted into another file or into memory.
# Note: Do not decrypt huge files into memory, use your best judgement.
plaintext_file_copy = Path("/absolute/path/to/plaintext_file_copy.any")
krypton.decrypt_to_file(ciphertext_file, plaintext_file_copy)
plaintext_data = krypton.decrypt_to_memory(ciphertext_file)
```

--------------------------------

### Compiler.run

Source: https://github.com/aabmets/quantcrypt/wiki/API-Reference

Compiles the target variants of the target algorithms and stores the compiled binaries within the internals of the QuantCrypt library.

```APIDOC
## Compiler.run

### Description
Compiles the target variants of the target algorithms and stores the compiled binaries within the internals of the QuantCrypt library.

### Method
`run(target_variants: list[const.PQAVariant] = None, target_algos: list[const.AlgoSpec] = None, *, in_subprocess: bool = False, verbose: bool = False, debug: bool = False)`

### Parameters
#### Keyword Arguments
- **target_variants** (list[const.PQAVariant] | None) - Optional list of target variants to compile.
- **target_algos** (list[const.AlgoSpec] | None) - Optional list of target algorithms to compile.
- **in_subprocess** (bool) - If True, run compilation in a subprocess. Defaults to False.
- **verbose** (bool) - If True, enable verbose output. Defaults to False.
- **debug** (bool) - If True, enable debug output. Defaults to False.

### Returns
- `subprocess.Popen` if `in_subprocess` is True.
- `list[Target]` if `in_subprocess` is False.
```

--------------------------------

### SupportedAlgos

Source: https://github.com/aabmets/quantcrypt/wiki/API-Reference

A list of supported algorithm specifications.

```APIDOC
## SupportedAlgos

### Description
A list of supported algorithm specifications.

### Methods
- **pqclean_names()**: Returns the pqclean_names of all contained AlgoSpecs.
- **armor_names(pqa_type: PQAType | None = None)**: Returns the armor_names of all contained AlgoSpecs. Permits filtering by PQAType.
- **filter(armor_names: list[str], invert: bool = False)**: Returns specs which exist in armor_names. Can invert filtering behavior.

### Type Alias
SupportedAlgos: AlgoSpecList[AlgoSpec]
```

--------------------------------

### MLKEM_768

Source: https://github.com/aabmets/quantcrypt/wiki/API-Reference

Initializes the MLKEM_768 key encapsulation mechanism algorithm instance with compiled C extension binaries. Provides methods for key generation, encapsulation, decapsulation, and key armoring/dearmoring.

```APIDOC
## MLKEM_768

### Description
Initializes the MLKEM_768 key encapsulation mechanism algorithm instance with compiled C extension binaries. Provides methods for key generation, encapsulation, decapsulation, and key armoring/dearmoring.

### Methods
- `__init__(self, variant: PQAVariant = None, *, allow_fallback: bool = True)`: Initializes the MLKEM_768 algorithm instance.
- `param_sizes(self)`: Returns the size of the parameters of this KEM algorithm.
- `keygen(self)`: Returns a tuple of public key and secret key bytes.
- `encaps(self, public_key: bytes)`: Returns a tuple of ciphertext and shared secret bytes.
- `decaps(self, secret_key: bytes, cipher_text: bytes)`: Returns the bytes of the decapsulated shared secret.
- `armor(self, key_bytes: bytes)`: Returns a base64-encoded ASCII string of the key bytes.
- `dearmor(self, armored_key: str)`: Returns the key bytes from an armored key ASCII string.

### Properties
- `variant` (PQAVariant): The PQA variant used.
- `spec` (AlgoSpec): The algorithm specification.

### Returns
- `keygen()`: `tuple[bytes, bytes]` - Public key and secret key.
- `encaps()`: `tuple[bytes, bytes]` - Ciphertext and shared secret.
- `decaps()`: `bytes` - Decapsulated shared secret.
- `armor()`: `str` - Base64 encoded key string.
- `dearmor()`: `bytes` - Decoded key bytes.
- `param_sizes()`: `KEMParamSizes` - Parameter sizes for the KEM.
```

--------------------------------

### MemCost

Source: https://github.com/aabmets/quantcrypt/wiki/API-Reference

Utility classes for specifying memory costs, with support for megabytes (MB) and gigabytes (GB).

```APIDOC
## MemCost

### Description
Utility classes for specifying memory costs, with support for megabytes (MB) and gigabytes (GB).

### Classes

- `MemCostMB`: Represents memory cost in megabytes. Accepts sizes of 32, 64, 128, 256, or 512 MB.
- `MemCostGB`: Represents memory cost in gigabytes. Accepts sizes of 1, 2, 3, 4, 5, 6, 7, or 8 GB.

These classes convert the input size values into kilobytes.
```

--------------------------------

### Key Encapsulation with MLKEM_1024

Source: https://github.com/aabmets/quantcrypt/wiki/Code-Examples

Demonstrates the process of generating a key pair, encapsulating a shared secret, and decapsulating it using MLKEM_1024.

```python
from quantcrypt.kem import MLKEM_1024

# First, we create an instance of a KEM algorithm.
kem = MLKEM_1024()

# Next, we generate a PK and SK pair.
public_key, secret_key = kem.keygen()

# Then, we use the PK to encapsulate the internally 
# generated shared_secret bytes into cipher_text bytes.
cipher_text, shared_secret = kem.encaps(public_key)

# Finally, the secret_key is used to decapsulate the
# original shared_secret from the cipher_text bytes.
shared_secret_copy = kem.decaps(secret_key, cipher_text)

# Check that the shared secrets match
assert shared_secret_copy == shared_secret
```

--------------------------------

### MLKEM_512

Source: https://github.com/aabmets/quantcrypt/wiki/API-Reference

Initializes the MLKEM_512 key encapsulation mechanism algorithm instance with compiled C extension binaries. Provides methods for key generation, encapsulation, decapsulation, and key armoring/dearmoring.

```APIDOC
## MLKEM_512

### Description
Initializes the MLKEM_512 key encapsulation mechanism algorithm instance with compiled C extension binaries. Provides methods for key generation, encapsulation, decapsulation, and key armoring/dearmoring.

### Methods
- `__init__(self, variant: PQAVariant = None, *, allow_fallback: bool = True)`: Initializes the MLKEM_512 algorithm instance.
- `param_sizes(self)`: Returns the size of the parameters of this KEM algorithm.
- `keygen(self)`: Returns a tuple of public key and secret key bytes.
- `encaps(self, public_key: bytes)`: Returns a tuple of ciphertext and shared secret bytes.
- `decaps(self, secret_key: bytes, cipher_text: bytes)`: Returns the bytes of the decapsulated shared secret.
- `armor(self, key_bytes: bytes)`: Returns a base64-encoded ASCII string of the key bytes.
- `dearmor(self, armored_key: str)`: Returns the key bytes from an armored key ASCII string.

### Properties
- `variant` (PQAVariant): The PQA variant used.
- `spec` (AlgoSpec): The algorithm specification.

### Returns
- `keygen()`: `tuple[bytes, bytes]` - Public key and secret key.
- `encaps()`: `tuple[bytes, bytes]` - Ciphertext and shared secret.
- `decaps()`: `bytes` - Decapsulated shared secret.
- `armor()`: `str` - Base64 encoded key string.
- `dearmor()`: `bytes` - Decoded key bytes.
- `param_sizes()`: `KEMParamSizes` - Parameter sizes for the KEM.
```

--------------------------------

### MLKEM_1024

Source: https://github.com/aabmets/quantcrypt/wiki/API-Reference

Initializes the MLKEM_1024 key encapsulation mechanism algorithm instance with compiled C extension binaries. Provides methods for key generation, encapsulation, decapsulation, and key armoring/dearmoring.

```APIDOC
## MLKEM_1024

### Description
Initializes the MLKEM_1024 key encapsulation mechanism algorithm instance with compiled C extension binaries. Provides methods for key generation, encapsulation, decapsulation, and key armoring/dearmoring.

### Methods
- `__init__(self, variant: PQAVariant = None, *, allow_fallback: bool = True)`: Initializes the MLKEM_1024 algorithm instance.
- `param_sizes(self)`: Returns the size of the parameters of this KEM algorithm.
- `keygen(self)`: Returns a tuple of public key and secret key bytes.
- `encaps(self, public_key: bytes)`: Returns a tuple of ciphertext and shared secret bytes.
- `decaps(self, secret_key: bytes, cipher_text: bytes)`: Returns the bytes of the decapsulated shared secret.
- `armor(self, key_bytes: bytes)`: Returns a base64-encoded ASCII string of the key bytes.
- `dearmor(self, armored_key: str)`: Returns the key bytes from an armored key ASCII string.

### Properties
- `variant` (PQAVariant): The PQA variant used.
- `spec` (AlgoSpec): The algorithm specification.

### Returns
- `keygen()`: `tuple[bytes, bytes]` - Public key and secret key.
- `encaps()`: `tuple[bytes, bytes]` - Ciphertext and shared secret.
- `decaps()`: `bytes` - Decapsulated shared secret.
- `armor()`: `str` - Base64 encoded key string.
- `dearmor()`: `bytes` - Decoded key bytes.
- `param_sizes()`: `KEMParamSizes` - Parameter sizes for the KEM.
```

--------------------------------

### Hash Passwords with Argon2

Source: https://github.com/aabmets/quantcrypt/wiki/Code-Examples

Shows how to hash a user's password for database storage and verify login attempts using Argon2. Password strength is checked by default using zxcvbn, but this can be disabled.

```python
from quantcrypt.kdf import Argon2

strong_password = "A8c7hBBTnVC90kP5AIe2"

a1 = Argon2.Hash(strong_password)
a2 = Argon2.Hash(strong_password, a1.public_hash)
assert a2.verified is True

# This line raises quantcrypt.errors.KDFWeakPasswordError:
# Argon2.Hash("my_weak_password")

# Disable password minimum strength check:
Argon2.Hash("my_weak_password", min_years=0)
Argon2.Hash(b"my_weak_password")  # bytes
```

--------------------------------

### Basic Encryption with Krypton Cipher

Source: https://github.com/aabmets/quantcrypt/wiki/Code-Examples

Illustrates symmetric encryption and decryption of arbitrary byte data using the Krypton cipher. Requires a 64-byte secret key.

```python
import secrets
from quantcrypt.cipher import Krypton

# Krypton requires the symmetric secret key to be 64 bytes long.
secret_key = secrets.token_bytes(64)
plaintext = b"Hello World"

krypton = Krypton(secret_key)

# Encrypt the plaintext and generate the verification data packet.
krypton.begin_encryption()
ciphertext = krypton.encrypt(plaintext)
verif_dp = krypton.finish_encryption()

# Decrypt the plaintext and verify its validity in finish_decryption call.
krypton.begin_decryption(verif_dp)
plaintext_copy = krypton.decrypt(ciphertext)
krypton.finish_decryption()

assert plaintext_copy == plaintext
```

--------------------------------

### MemCostGB Constructor

Source: https://github.com/aabmets/quantcrypt/wiki/API-Reference

Converts a memory size specified in gigabytes to kilobytes. Use this for configuring memory costs in KDF parameters.

```python
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."""
```

--------------------------------

### Sign and Verify Arbitrary Data with MLDSA_87

Source: https://github.com/aabmets/quantcrypt/wiki/Code-Examples

Shows how to sign arbitrary byte messages and verify their signatures using the MLDSA_87 digital signature scheme.

```python
from quantcrypt.dss import MLDSA_87

# First, we create an instance of a DSS algorithm
# and also define a message to be signed.
dss = MLDSA_87()
message = b'Hello World'

# Next, we generate a PK and SK pair.
public_key, secret_key = kem.keygen()

# Then, we use the secret_key to sign the message.
signature = dss.sign(secret_key, message)

# Finally, we use the public_key to verify the validity of the signature.
dss.verify(public_key, message, signature)
```

--------------------------------

### Sign and Verify Files with MLDSA_87

Source: https://github.com/aabmets/quantcrypt/wiki/Code-Examples

Demonstrates signing and verifying the integrity of files using the MLDSA_87 digital signature scheme.

```python
from pathlib import Path
from quantcrypt.dss import MLDSA_87

# First, we create an instance of a DSS algorithm 
# and obtain a path to the file to be signed.
dss = MLDSA_87()
file_path = Path("/absolute/path/to/target/file.any")

# Next, we generate a PK and SK pair.
public_key, secret_key = kem.keygen()

# Then, we use the secret_key to sign the file.
signed_file = dss.sign_file(secret_key, file_path)

# Finally, we use the public_key to verify the validity of the signature.
dss.verify_file(public_key, file_path, signed_file.signature)
```

--------------------------------

### MemCostMB Constructor

Source: https://github.com/aabmets/quantcrypt/wiki/API-Reference

Converts a memory size specified in megabytes to kilobytes. Use this for configuring memory costs in KDF parameters.

```python
class MemCostMB(dict):
    def __init__(self, size: Literal[32, 64, 128, 256, 512]) -> None:
        """Converts the size input argument value of megabytes to kilobytes."""
```

--------------------------------

### Compiler Class with Run Method

Source: https://github.com/aabmets/quantcrypt/wiki/API-Reference

Provides a class for compiling target variants of algorithms. The `run` class method can compile specified targets, optionally in a subprocess, with verbose or debug output.

```python
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.
        """
```

--------------------------------

### Argon2Hash Constructor

Source: https://github.com/aabmets/quantcrypt/wiki/API-Reference

Computes the Argon2 hash immediately upon instantiation. Use this for hashing passwords with specified parameters and minimum security duration.

```python
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.
        """
```

--------------------------------

### SMALL_SPHINCS Digital Signature Scheme

Source: https://github.com/aabmets/quantcrypt/wiki/API-Reference

Provides methods for key generation, signing, and verification using the SMALL_SPHINCS algorithm. Supports file signing and verification, as well as key armoring/dearmoring.

```python
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."""
```

--------------------------------

### SignedFile

Source: https://github.com/aabmets/quantcrypt/wiki/API-Reference

Represents a file that has been signed.

```APIDOC
## SignedFile

### Description
Represents a file that has been signed.

### Fields
- **algo_name** (str) - The name of the algorithm used for signing.
- **signature** (bytes) - The signature of the file.
- **file_digest** (bytes) - The digest of the file.

### Class Definition
```python
@dataclass
class SignedFile:
    algo_name: str
    signature: bytes
    file_digest: bytes
```
```

--------------------------------

### MLKEM_512 Key Encapsulation Mechanism

Source: https://github.com/aabmets/quantcrypt/wiki/API-Reference

Implements the MLKEM_512 algorithm for key encapsulation. Initializes with compiled C extension binaries and supports key generation, encapsulation, and decapsulation.

```python
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."""
```

--------------------------------

### MLKEM_768 Key Encapsulation Mechanism

Source: https://github.com/aabmets/quantcrypt/wiki/API-Reference

Implements the MLKEM_768 algorithm for key encapsulation. Initializes with compiled C extension binaries and supports key generation, encapsulation, and decapsulation.

```python
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."""
```

--------------------------------

### ChunkSize Definitions

Source: https://github.com/aabmets/quantcrypt/wiki/API-Reference

Provides classes for defining chunk sizes in kilobytes (KB) and megabytes (MB). These classes convert the input size in the respective unit to bytes.

```python
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."""
```

--------------------------------

### MLKEM_1024 Key Encapsulation Mechanism

Source: https://github.com/aabmets/quantcrypt/wiki/API-Reference

Implements the MLKEM_1024 algorithm for key encapsulation. Initializes with compiled C extension binaries and supports key generation, encapsulation, and decapsulation.

```python
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."""
```

--------------------------------

### KryptonKEM

Source: https://github.com/aabmets/quantcrypt/wiki/API-Reference

Provides methods for encrypting and decrypting files using a Key Encapsulation Mechanism (KEM). It supports encrypting data to a file and decrypting data either to a file or directly into memory.

```APIDOC
## KryptonKEM

### Description
Provides methods for encrypting and decrypting files using a Key Encapsulation Mechanism (KEM). It supports encrypting data to a file and decrypting data either to a file or directly into memory.

### Methods

- `__init__(kem_class: Type[BaseKEM], kdf_params: KDFParams = None, context: bytes = b"quantcrypt", callback: Optional[Callable] = None, chunk_size: ChunkSize.Atd = None)`: Creates a new KryptonKEM instance.
- `encrypt(public_key: str | bytes, data_file: str | Path, output_file: str | Path)`: Encrypts plaintext data from a file to an output file using a public key.
- `decrypt_to_file(secret_key: str | bytes, encrypted_file: str | Path, output_file: str | Path = None)`: Decrypts data from an encrypted file to an output file using a secret key.
- `decrypt_to_memory(secret_key: str | bytes, encrypted_file: str | Path)`: Decrypts data from an encrypted file into memory.
```

--------------------------------

### FALCON_1024

Source: https://github.com/aabmets/quantcrypt/wiki/API-Reference

Documentation for the FALCON_1024 digital signature scheme. This class provides methods for key generation, signing, verification, file operations, and key armor/dearmor.

```APIDOC
## FALCON_1024

### Description
Provides functionalities for the FALCON_1024 digital signature scheme, including key management, signing, verification, and file processing.

### Methods

- **__init__(self, variant: const.PQAVariant = None, *, allow_fallback: bool = True)**: Initializes the FALCON_1024 digital signature scheme algorithm instance with compiled C extension binaries.

- **param_sizes**: Returns the size of the params of this DSS algorithm.

- **keygen()**: Returns a tuple of public key and secret key bytes.

- **sign(secret_key: bytes, message: bytes)**: Returns bytes of the generated signature.

- **verify(public_key: bytes, message: bytes, signature: bytes, *, raises: bool = True)**: Returns True on successful signature verification.

- **sign_file(secret_key: str | bytes, data_file: str | Path, callback: Optional[Callable] = None)**: Computes and signs the hash of the data file to generate the signature.

- **verify_file(public_key: str | bytes, data_file: str | Path, signature: bytes, callback: Optional[Callable] = None, *, raises: bool = True)**: Verifies the signature against the computed hash of the data file.

- **armor(key_bytes: bytes)**: Returns a base64-encoded ASCII string of the key bytes.

- **dearmor(armored_key: str)**: Returns the key bytes from an armored key ASCII string.
```

--------------------------------

### Argon2Key Constructor

Source: https://github.com/aabmets/quantcrypt/wiki/API-Reference

Computes the Argon2 derived secret key immediately upon instantiation. Use this for deriving secret keys from passwords with specified parameters and minimum security duration.

```python
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.
        """
```

--------------------------------

### Derive Keys for Krypton Cipher with Argon2Key

Source: https://github.com/aabmets/quantcrypt/wiki/Code-Examples

Demonstrates expanding a secret key using Argon2Key for use with the Krypton cipher. This is suitable for high-cost key derivation.

```python
import secrets
from quantcrypt.kdf import Argon2
from quantcrypt.cipher import Krypton

secret_key = secrets.token_bytes(32)

argon = Argon2.Key(secret_key)
krypton = Krypton(argon.secret_key)
```

--------------------------------

### KryptonFile

Source: https://github.com/aabmets/quantcrypt/wiki/API-Reference

Facilitates encryption and decryption of files of arbitrary sizes using a single secret key and configuration.

```APIDOC
## KryptonFile

### Description
Creates a new KryptonFile instance for encrypting and/or decrypting multiple files of arbitrary sizes with the same secret key using the same configuration.

### Methods

- **__init__(self, secret_key: bytes, context: bytes = b'', callback: Optional[Callable] = None, chunk_size: ChunkSize.Atd = None)**: Creates a new KryptonFile instance.
- **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`.
- **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.
- **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.
- **read_file_header(cls, encrypted_file: str | Path) -> bytes**: Reads the header bytes from a Krypton ciphertext file.
```

--------------------------------

### FALCON_512

Source: https://github.com/aabmets/quantcrypt/wiki/API-Reference

Provides methods for the FALCON_512 digital signature scheme, including key generation, signing, verification, file operations, and key armor/dearmor.

```APIDOC
## FALCON_512

### Description
Provides methods for the FALCON_512 digital signature scheme, including key generation, signing, verification, file operations, and key armor/dearmor.

### Methods

- `__init__(self, variant: const.PQAVariant = None, *, allow_fallback: bool = True)`: Initializes the FALCON_512 digital signature scheme algorithm instance with compiled C extension binaries.
- `param_sizes(self) -> DSSParamSizes`: Returns the size of the params of this DSS algorithm.
- `keygen(self) -> tuple[bytes, bytes]`: Returns a tuple of public key and secret key bytes.
- `sign(self, secret_key: bytes, message: bytes) -> bytes`: Returns bytes of the generated signature.
- `verify(self, public_key: bytes, message: bytes, signature: bytes, *, raises: bool = True) -> bool`: Returns True on successful signature verification.
- `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.
- `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.
- `armor(self, key_bytes: bytes) -> str`: Returns a base64-encoded ASCII string of the key bytes.
- `dearmor(self, armored_key: str) -> bytes`: Returns the key bytes from an armored key ASCII string.
```

--------------------------------

### KryptonKEM Class

Source: https://github.com/aabmets/quantcrypt/wiki/API-Reference

Provides methods for encrypting and decrypting files using a KEM. It internally utilizes the KryptonFile class for handling file operations. Use this class for encrypting or decrypting multiple files with consistent KEM configurations.

```python
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.
        """

```

--------------------------------

### AlgoSpecsList Methods

Source: https://github.com/aabmets/quantcrypt/wiki/API-Reference

Extends the list class to provide utility methods for managing and querying algorithm specifications. Supports retrieving names, filtering by type, and filtering by armor names.

```python
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]
```

--------------------------------

### KryptonFile for File Encryption/Decryption

Source: https://github.com/aabmets/quantcrypt/wiki/API-Reference

Handles encryption and decryption of files of arbitrary sizes. Supports encrypting data from one file to another, decrypting to a file, and decrypting to memory. Also provides a utility to read file headers.

```python
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."""
```

--------------------------------

### ChunkSize

Source: https://github.com/aabmets/quantcrypt/wiki/API-Reference

Represents chunk sizes in kilobytes or megabytes.

```APIDOC
## ChunkSize

### Description
Represents chunk sizes in kilobytes or megabytes.

### Subclasses
- **KB**: Represents chunk size in kilobytes.
- **MB**: Represents chunk size in megabytes.

### ChunkSizeKB
Converts the size input argument value of kilobytes to bytes.

### ChunkSizeMB
Converts the size input argument value of megabytes to bytes.
```

--------------------------------

### FAST_SPHINCS

Source: https://github.com/aabmets/quantcrypt/wiki/API-Reference

Documentation for the FAST_SPHINCS digital signature scheme. This class offers methods for key generation, signing, verification, file operations, and key armor/dearmor.

```APIDOC
## FAST_SPHINCS

### Description
Provides functionalities for the FAST_SPHINCS digital signature scheme, including key management, signing, verification, and file processing.

### Methods

- **__init__(self, variant: const.PQAVariant = None, *, allow_fallback: bool = True)**: Initializes the FAST_SPHINCS digital signature scheme algorithm instance with compiled C extension binaries.

- **param_sizes**: Returns the size of the params of this DSS algorithm.

- **keygen()**: Returns a tuple of public key and secret key bytes.

- **sign(secret_key: bytes, message: bytes)**: Returns bytes of the generated signature.

- **verify(public_key: bytes, message: bytes, signature: bytes, *, raises: bool = True)**: Returns True on successful signature verification.

- **sign_file(secret_key: str | bytes, data_file: str | Path, callback: Optional[Callable] = None)**: Computes and signs the hash of the data file to generate the signature.

- **verify_file(public_key: str | bytes, data_file: str | Path, signature: bytes, callback: Optional[Callable] = None, *, raises: bool = True)**: Verifies the signature against the computed hash of the data file.

- **armor(key_bytes: bytes)**: Returns a base64-encoded ASCII string of the key bytes.

- **dearmor(armored_key: str)**: Returns the key bytes from an armored key ASCII string.
```