ghostbytes 1.0.0__py3-none-any.whl

ghostbytes/crypto/kyber.py

@@ -0,0 +1,257 @@
+"""
+kyber.py
+
+Implementation of ML-KEM (CRYSTALS-Kyber, Module-Lattice-Based Key-Encapsulation Mechanism Standard)
+according to FIPS 203. ML-KEM is one of the 7 finalists selected in the third round of the NIST
+Post-Quantum Cryptography (PQC) standardisation process.
+
+2 of 3 Standard Parameter sets are implemented here, ML-KEM-768 and ML-KEM-1024.
+ML-KEM-768 is classified in NIST Security Category 3 (AES-192 Equivalent)
+ML-KEM-1024 is classified in NIST Security Category 5 (AES-256 Equivalent)
+
+More about ML-KEM here: https://en.wikipedia.org/wiki/ML-KEM
+
+This module uses ML-KEM to derive a symmetric key,
+which is then used for AES encryption of the plaintext.
+"""
+
+import re
+import secrets
+
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric import mlkem
+from ghostbytes.crypto.primitives import detect_key_format
+from ghostbytes.error import CryptoError, \
+    algorithm_not_supported, envelope_too_small, invalid_keyfile, key_encoding_not_found, \
+    invalid_configuration_type, keyfile_passphrase_incorrect, store_iv_choice_mismatch, \
+    text_not_in_bytes, keyfile_cannot_crypt
+from ghostbytes.crypto.config import CryptoConfig
+from ghostbytes.crypto.primitives import aes_decrypt, aes_encrypt, derive_key
+
+
+def genkey(alg, encoding, passphrase=None):
+    """
+    Generate and serialise an ML-KEM key pair
+
+    Args:
+        alg: ML-KEM algorithm name. Supported values are ``"ML-KEM-768"`` and ``"ML-KEM-1024"``
+        encoding: Key encoding. Supported values are ``"PEM"`` and ``"DER"``
+        passphrase: Optional passphrase used to encrypt the serialised private key
+
+    Return:
+        A tuple containing ``(publickey, privatekey)`` as serialised bytes
+
+    Raises:
+        algorithm_not_supported: if ``alg`` is not supported
+        key_encoding_not_found: if ``encoding`` is not supported
+    """
+    _, kem = _alg_to_class(alg)
+    privkey = kem.generate()
+    pubkey = privkey.public_key()
+
+    privkey = privkey.private_bytes(
+        encoding=_get_encoding(encoding),
+        format=serialization.PrivateFormat.PKCS8,
+        encryption_algorithm=serialization.BestAvailableEncryption(passphrase)
+        if passphrase else serialization.NoEncryption()
+    )
+    pubkey = pubkey.public_bytes(
+        encoding=_get_encoding(encoding),
+        format=serialization.PublicFormat.SubjectPublicKeyInfo
+    )
+
+    return (pubkey, privkey)
+
+
+def verify_key(pubkey, privkey, passphrase=None):
+    """
+    Verify that a public and private ML-KEM key belong together
+
+    The function encapsulates a shared secret with the public key and
+    decapsulates it with the private key. The two resulting secrets
+    are then compared.
+
+    Args:
+        pubkey: Serialised ML-KEM public key.
+        privkey: Serialised ML-KEM private key.
+        passphrase: Optional passphrase for decrypting the private key.
+
+    Returns:
+        ``True`` if both keys produce the same shared secret, otherwise ``False``
+
+    Raises:
+        invalid_keyfile: if either key is invalid.
+        keyfile_passphrase_incorrect: if the privatekey passphrase is incorrect.
+    """
+    pubkeytype = detect_key_format(pubkey)
+    privkeytype = detect_key_format(privkey)
+    pubkey = _import_public_key(pubkeytype, pubkey)
+    privkey = _import_private_key(privkeytype, privkey, passphrase)
+
+    shared_secret_sender, ciphertext = pubkey.encapsulate()
+    shared_secret_receiver = privkey.decapsulate(ciphertext)
+
+    return secrets.compare_digest(shared_secret_sender, shared_secret_receiver)
+
+
+def kyber_encrypt(config, pubkey, plaintext, passphrase=None):
+    """
+    Encrypt plaintext using ML-KEM key encapsulation and AES.
+
+    The function encapsulates a share secret using the public key,
+    derives a symmetric key from that secret, and encrypts the
+    plaintext with AES. The ML-KEM ciphertext is stored with the
+    ciphertext and returns as bytes.
+
+    Args:
+        config: encryption configuration passed to ``derive_key``
+            (KDF parameters)
+        pubkey: serialised ML-KEM public key
+        plaintext: Data to encrypt. Must be a ``bytes`` object
+        passphrase: optional passphrase for decrypting ``pubkey``
+            when it is a private key
+
+    Returns:
+        The combined ML-KEM and AES ciphertext as bytes
+
+    Raises:
+        invalid_configuration_type: when config is not a ``CryptoConfig`` instance
+        text_not_in_bytes: if ``plaintext`` is not bytes
+        store_iv_choice_mismatch: if ``config.store_iv`` is invalid
+        invalid_keyfile: if the supplied key is invalid
+    """
+    if not isinstance(config, CryptoConfig):
+        raise invalid_configuration_type()
+    if not isinstance(plaintext, bytes):
+        raise text_not_in_bytes()
+    keytype = detect_key_format(pubkey)
+    try:
+        pubkeyclass = _import_public_key(keytype, pubkey)
+    except CryptoError:
+        pubkeyclass = _import_private_key(
+            keytype, pubkey, passphrase).public_key()
+    shared_secret, kemciphertext = pubkeyclass.encapsulate()
+    masterkey = derive_key(config, shared_secret)
+
+    ciphertext = aes_encrypt(config, masterkey, plaintext)
+
+    if config.store_iv == "append":
+        ciphertext += kemciphertext
+    elif config.store_iv == "prepend":
+        ciphertext = kemciphertext + ciphertext
+    else:
+        raise store_iv_choice_mismatch()
+
+    return ciphertext
+
+
+def kyber_decrypt(config, privkey, ciphertext, passphrase=None):
+    """
+    Decrypt ciphertext using ML-KEM key decapsulation and AES.
+
+    The function extracts the ML-KEM ciphertext from the envelop,
+    decapsulate it with the private key, derives the symmetric AES
+    key, and decrypts the remaining ciphertext.
+
+    Args:
+        config: encryption configuration passed to ``derive_key``
+            (KDF parameters)
+        privkey: serialised ML-KEM private key
+        plaintext: Data to encrypt. Must be a ``bytes`` object
+        passphrase: optional passphrase for decrypting ``privkey``
+
+    Returns:
+        The decrypted plaintext as bytes
+
+    Raises:
+        invalid_configuration_type: when config is not a ``CryptoConfig`` instance
+        text_not_in_bytes: if ``plaintext`` is not bytes
+        envelop_too_small: if the size of the envelop is too small
+            to contain a complete ML-KEM ciphertext
+        keyfile_cannot_crypt: If a public key is supplied instead
+            of a private key
+        store_iv_choice_mismatch: if ``config.store_iv`` is invalid
+        invalid_keyfile: if the supplied key is invalid
+    """
+    if not isinstance(config, CryptoConfig):
+        raise invalid_configuration_type()
+    if not isinstance(ciphertext, bytes):
+        raise text_not_in_bytes()
+    keytype = detect_key_format(privkey)
+    kem = _import_private_key(keytype, privkey, passphrase)
+    if isinstance(kem, mlkem.MLKEM768PrivateKey):
+        kem_len = 1088
+    elif isinstance(kem, mlkem.MLKEM1024PrivateKey):
+        kem_len = 1568
+    elif isinstance(kem, (mlkem.MLKEM1024PublicKey, mlkem.MLKEM768PublicKey)):
+        raise keyfile_cannot_crypt("decrypt")
+    else:
+        raise invalid_keyfile()
+    if len(ciphertext) < kem_len:
+        raise envelope_too_small()
+    if config.store_iv == "append":
+        kem_ciphertext = ciphertext[-kem_len:]
+        ciphertext = ciphertext[:-kem_len]
+    elif config.store_iv == "prepend":
+        kem_ciphertext = ciphertext[:kem_len]
+        ciphertext = ciphertext[kem_len:]
+    else:
+        raise store_iv_choice_mismatch()
+
+    shared_secret = kem.decapsulate(kem_ciphertext)
+
+    masterkey = derive_key(config, shared_secret)
+
+    plaintext = aes_decrypt(config, masterkey, ciphertext)
+
+    return plaintext
+
+
+def _alg_to_class(alg):
+    match = re.search(r"^ML-KEM-(768|1024)$", alg)
+    if match:
+        if match.group(1) == "768":
+            return (mlkem.MLKEM768PublicKey, mlkem.MLKEM768PrivateKey)
+        return (mlkem.MLKEM1024PublicKey, mlkem.MLKEM1024PrivateKey)
+    raise algorithm_not_supported()
+
+
+def _get_encoding(encoding):
+    match encoding:
+        case "PEM":
+            return serialization.Encoding.PEM
+        case "DER":
+            return serialization.Encoding.DER
+    raise key_encoding_not_found()
+
+
+def _import_private_key(keytype, privkey, passphrase=None):
+    if isinstance(passphrase, str):
+        passphrase = passphrase.encode('utf-8')
+    try:
+        match keytype:
+            case "PEM":
+                return serialization.load_pem_private_key(
+                    privkey, password=passphrase)
+            case "DER":
+                return serialization.load_der_private_key(
+                    privkey, password=passphrase)
+            case _:
+                raise key_encoding_not_found()
+    except (ValueError, TypeError) as e:
+        if passphrase is None:
+            raise invalid_keyfile() from e
+        raise keyfile_passphrase_incorrect() from e
+
+
+def _import_public_key(keytype, pubkey):
+    try:
+        match keytype:
+            case "PEM":
+                return serialization.load_pem_public_key(pubkey)
+            case "DER":
+                return serialization.load_der_public_key(pubkey)
+            case _:
+                raise key_encoding_not_found()
+    except (ValueError, TypeError) as e:
+        raise invalid_keyfile() from e

ghostbytes/crypto/oaep_extension.py

@@ -0,0 +1,125 @@
+"""
+oaep_extension.py
+
+This module extends RSA-OAEP by generating a random AES-256 key for each message.
+The plaintext is encrypted with AES, while the AES key is encrypted with RSA-OAEP.
+
+The resulting envelope contains the AES ciphertext and the RSA-encrypted AES key.
+The RSA-encrypted key is stored with the AES ciphertext.
+"""
+
+from Crypto.Cipher import PKCS1_OAEP as _oaep
+from ghostbytes.crypto.primitives import aes_encrypt, aes_decrypt
+from ghostbytes.crypto.config import AVAIL_HASH, CryptoConfig
+from ghostbytes.tools.rand import random
+from ghostbytes.error import decryption_key_incorrect, envelope_too_small, \
+    hash_not_supported, invalid_configuration_type, keyfile_cannot_crypt, store_iv_choice_mismatch
+
+
+def oaep_extended_encrypt(config, rsa, plaintext):
+    """
+    Encrypt plaintext using AES and wrap the AES key with RSA-OAEP
+
+    A random 256-bit AES key is generated using the configured random
+    function. The plaintext is encrypted with AES, and the AES key is
+    encrypted with RSA-OAEP. The encrypted AES key is then joined to
+    the AES ciphertext.
+
+    Args:
+        config: Cryptographic configuration for the operation, includes the algorithm,
+            KDF parameters, and all necessary configuration to complete the operation.
+        rsa: An RSA public Key used to encrypt the AES Key
+        plaintext: the data to encrypt in bytes.
+
+    Returns:
+        The combined RSA-OAEP and AES ciphertext as bytes
+
+    Raises:
+        invalid_configuration_types: if ``config`` is not ``CryptoConfig`` instance.
+        hash_not_supported: if the configured hash function is unsupported.
+        keyfile_cannot_crypt: If the RSA key cannot encrypt
+        store_iv_choice_mismatch: if ``config.store_iv`` is invalid
+    """
+    if not isinstance(config, CryptoConfig):
+        raise invalid_configuration_type()
+    if config.hash_func not in AVAIL_HASH:
+        raise hash_not_supported()
+
+    oaep = _oaep.new(
+        key=rsa,
+        hashAlgo=config.hash_func
+    )
+    if not oaep.can_encrypt():
+        raise keyfile_cannot_crypt("encrypt")
+
+    key = random(config.rand_func, 32)  # AES-256 32 bytes key length
+
+    ciphertext = aes_encrypt(config, key, plaintext)
+
+    key = oaep.encrypt(key)
+
+    if config.store_iv == 'append':
+        ciphertext += key
+    elif config.store_iv == 'prepend':
+        ciphertext = key + ciphertext
+    else:
+        raise store_iv_choice_mismatch()
+
+    return ciphertext
+
+
+def oaep_extended_decrypt(config, rsa, ciphertext):
+    """
+    Decrypt an RSA-OAEP and AES encrypted envelop.
+
+    The function extracts the RSA-encrypted AES key from the ciphertext. It then decrypts
+    the AES key with RSA-OAEP and uses that key to decrypt the remaining AES ciphertext.
+
+    Args:
+        config: Cryptographic configuration for the operation, includes the algorithm,
+            KDF parameters, and all necessary configuration to complete the operation.
+        rsa: An RSA private Key used to derypt the AES Key
+        ciphertext: the data to decrypt in bytes.
+
+    Returns:
+        The decrypted plaintext as bytes
+
+    Raises:
+        invalid_configuration_types: if ``config`` is not ``CryptoConfig`` instance.
+        hash_not_supported: if the configured hash function is unsupported.
+        keyfile_cannot_crypt: If the RSA key cannot encrypt
+        envelop_too_small: if the size of the envelop is too small to contain a
+            complete ML-KEM ciphertext
+        decryption_key_incorrect: if RSA-OAEP decryption fails
+        store_iv_choice_mismatch: if ``config.store_iv`` is invalid
+    """
+    if not isinstance(config, CryptoConfig):
+        raise invalid_configuration_type()
+    oaep = _oaep.new(
+        key=rsa,
+        hashAlgo=config.hash_func
+    )
+    if not rsa.has_private():
+        raise keyfile_cannot_crypt("decrypt")
+
+    rsa_size = rsa.size_in_bytes()
+    if len(ciphertext) - rsa_size <= 0:
+        raise envelope_too_small()
+
+    if config.store_iv == 'append':
+        encrypted_key = ciphertext[len(ciphertext) - rsa_size:]
+        ciphertext = ciphertext[:len(ciphertext) - rsa_size]
+    elif config.store_iv == 'prepend':
+        encrypted_key = ciphertext[:rsa_size]
+        ciphertext = ciphertext[rsa_size:]
+    else:
+        raise store_iv_choice_mismatch()
+
+    try:
+        decrypted_key = oaep.decrypt(encrypted_key)
+    except ValueError as e:
+        raise decryption_key_incorrect() from e
+
+    plaintext = aes_decrypt(config, decrypted_key, ciphertext)
+
+    return plaintext