-
Notifications
You must be signed in to change notification settings - Fork 9
API Reference
Mattias Aabmets edited this page Jan 28, 2024
·
12 revisions
- Key Encapsulation Mechanisms
- Digital Signature Schemes
- The Krypton Cipher
- Key Derivation Functions
- Utilities
- Links to Source Code
class Kyber(BaseKEM):
variant: PQAVariant
def __init__(self, variant: PQAVariant = None) -> None:
"""Initializes the Kyber instance with 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 Dilithium(BaseDSS):
variant: PQAVariant
def __init__(self, variant: PQAVariant = None) -> None:
"""Initializes the Dilithium instance with 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(BaseDSS):
variant: PQAVariant
def __init__(self, variant: PQAVariant = None) -> None:
"""Initializes the Falcon instance with 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 FastSphincs(BaseDSS):
variant: PQAVariant
def __init__(self, variant: PQAVariant = None) -> None:
"""Initializes the FastSphincs instance with 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 SmallSphincs(BaseDSS):
variant: PQAVariant
def __init__(self, variant: PQAVariant = None) -> None:
"""Initializes the SmallSphincs instance with 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(Enum):
CLEAN = "clean"
AVX2 = "avx2"@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."""All components are defined in the quantcrypt/internal subpath.
| Component | Link |
|---|---|
| KEM | pqa/kem.py |
| DSS | pqa/dss.py |
| Krypton | cipher/krypton.py |
| KryptonFile | cipher/krypton_file.py |
| KryptonKEM | cipher/krypton_kem.py |
| Argon2 | kdf/argon2_kdf.py |
| Argon2Hash | kdf/argon2_kdf.py |
| Argon2Key | kdf/argon2_kdf.py |
| KKDF | kdf/kmac_kdf.py |
| DecryptedFile | cipher/krypton_file.py |
| MemCost | kdf/common.py |
| KDFParams | kdf/common.py |
| PQAVariant | pqa/common.py |
| SignedFile | pqa/dss.py |
| ChunkSize | chunksize.py |