ghostbytes 1.0.0__py3-none-any.whl

ghostbytes/__init__.py

@@ -0,0 +1,3 @@
+__version__ = "1.0.0"
+__license__ = "MIT"
+__link__ = "http://github.com/maxttkam/ghostbytes"

ghostbytes/__main__.py

@@ -0,0 +1,9 @@
+from .gui import gui
+
+def main() -> None:
+    app = gui.App()
+    app.mainloop()
+
+
+if __name__ == "__main__":
+    main()

ghostbytes/crypto/config.py

@@ -0,0 +1,155 @@
+"""
+config.py
+
+Defines encryption configuration used by Ghostbytes:
+which cipher, hash function, KDF parameters, and random source to use,
+plus helper functions (import, export, and generate configuration)
+to save / load configurations to / from a config file.
+
+See docs/confguration.md
+"""
+import base64
+import configparser
+from hashlib import md5
+from Crypto.Hash import SHA3_512, SHA3_256, SHA512, SHA256, BLAKE2b, BLAKE2s
+from ghostbytes.error import invalid_configuration
+
+AVAIL_HASH = [SHA3_512, SHA3_256, SHA512, SHA256, BLAKE2b, BLAKE2s, md5]
+AVAIL_HASH_STR = [
+    "sha3_512",
+    "sha3_256",
+    "sha512",
+    "sha256",
+    "blake2b",
+    "blake2s",
+    "md5"]
+AVAIL_ALG = ["aes", "rsa-oaep", "extended_oaep", "ML-KEM-768", "ML-KEM-1024"]
+AVAIL_RANDOM_STR = [
+    "os.urandom",
+    "cryptodome_random",
+    "random lib (python)",
+    "secrets_random",
+    "/dev/urandom (*nux only)",
+    "/dev/random (*nux only)",
+    "/dev/urandom (dd, out file only) (*nux only)",
+    "/dev/random (dd, out file only) (*nux only)",
+]
+ENCRYPTED_SUFFIX = ".enc"
+RSA_KEY_OUT_FORMAT = ["PEM", "DER", "OpenSSH"]
+COMMON_RSA_SIZE = [2048, 4096, 8192]
+RSA_SIZE_WARNING_THRESHOLD = 4096
+
+OVERWRITE_OPTIONS = [
+    'random',
+    'zero',
+    'one',
+    'gutmann'
+]
+
+RANDOM_SALT_SIZE = 64
+
+
+class CryptoConfig:
+    """
+    Holds cryptographic parameters used to encrypt / decrypt a file.
+
+    An instance can be created via `CryptoConfig()`, randomised via
+    `CryptoConfig.generate_random_salt()`, or restored from disk via
+    `CryptoConfig.import_file(path)`. Use `export_file(path)` to persist it.
+
+    Fields such as `algorithm`, `store_iv`, `mac_len`, and all kdf parameters must
+    remain the identical between encryptor and decryptor to allow ciphertext
+    to be successfully decrypted.
+
+    It is also recommended to use a DIFFERERNT SALT per encryption pair to prevent
+    rainbow table attacks. Use `export_file` and `import_file` to ensure the
+    cryptographic configurations are the same.
+    """
+    algorithm = AVAIL_ALG[0]
+
+    store_iv = "append"  # or "prepend"
+    mac_len = 16
+    kdf_salt = b"CHANGE_ME_F1L3_3NCRYP710N_53CR37_54L7_70_3N5UR3_R4ND0MN355"
+    kdf_time_cost = 16
+    kdf_memory_cost = 128 * 1024  # 128 MB, times 1024 to get KB
+    kdf_parallelism = 8
+
+    hash_func = AVAIL_HASH[0]
+    rand_func = AVAIL_RANDOM_STR[0]
+
+    def generate_random_salt(self, length=64):
+        """Generate and store a new KDF salt using this config's random source."""
+
+        # Imports random within the function prevents cross-import error
+        from ghostbytes.tools.rand import random
+
+        self.kdf_salt = random(self.rand_func, length)
+        return self.kdf_salt
+
+    def export_file(self, path):
+        """Exports the current `CryptoConfig` state to a `.conf` file"""
+        parser = configparser.ConfigParser()
+        parser["CryptoConfig"] = {
+            "algorithm": self.algorithm,
+            "store_iv": self.store_iv,
+            "mac_len": str(self.mac_len),
+            "kdf_salt": base64.b64encode(self.kdf_salt).decode("ascii"),
+            "kdf_time_cost": str(self.kdf_time_cost),
+            "kdf_memory_cost": str(self.kdf_memory_cost),
+            "kdf_parallelism": str(self.kdf_parallelism),
+            "hash_func": AVAIL_HASH_STR[AVAIL_HASH.index(self.hash_func)],
+            "rand_func": self.rand_func,
+        }
+        with open(path, "w", encoding="utf-8") as file:
+            parser.write(file)
+
+    @classmethod
+    def import_file(cls, path):
+        """Imports the previous `CryptoConfig` state through a `.conf` file"""
+        parser = configparser.ConfigParser()
+        try:
+            if not parser.read(
+                    path,
+                    encoding="utf-8") or "CryptoConfig" not in parser:
+                raise invalid_configuration("missing CryptoConfig section")
+        except (OSError, UnicodeDecodeError, configparser.Error) as exc:
+            raise invalid_configuration("file could not be read") from exc
+
+        values = parser["CryptoConfig"]
+        try:
+            algorithm = values["algorithm"]
+            store_iv = values["store_iv"]
+            mac_len = values.getint("mac_len")
+            kdf_salt = base64.b64decode(values["kdf_salt"], validate=True)
+            kdf_time_cost = values.getint("kdf_time_cost")
+            kdf_memory_cost = values.getint("kdf_memory_cost")
+            kdf_parallelism = values.getint("kdf_parallelism")
+            hash_name = values["hash_func"]
+            rand_func = values["rand_func"]
+        except (KeyError, ValueError) as e:
+            raise invalid_configuration(
+                "one or more values are malformed") from e
+
+        if algorithm not in AVAIL_ALG:
+            raise invalid_configuration("unsupported algorithm")
+        if store_iv not in ("append", "prepend"):
+            raise invalid_configuration("invalid IV storage mode")
+        if not 4 <= mac_len <= 16:
+            raise invalid_configuration(
+                "MAC length must be between 4 and 16 bytes")
+        if not kdf_salt or kdf_time_cost < 1 or kdf_memory_cost < 1 or kdf_parallelism < 1:
+            raise invalid_configuration("invalid KDF settings")
+        if hash_name not in AVAIL_HASH_STR or rand_func not in AVAIL_RANDOM_STR:
+            raise invalid_configuration("unsupported hash or random function")
+
+        config = cls()
+        config.algorithm = algorithm
+        config.store_iv = store_iv
+        config.mac_len = mac_len
+        config.kdf_salt = kdf_salt
+        config.kdf_time_cost = kdf_time_cost
+        config.kdf_memory_cost = kdf_memory_cost
+        config.kdf_parallelism = kdf_parallelism
+        config.hash_func = AVAIL_HASH[AVAIL_HASH_STR.index(hash_name)]
+        config.rand_func = rand_func
+        return config

ghostbytes/crypto/crypto.py

@@ -0,0 +1,162 @@
+"""
+crypto.py
+
+This is the main module provides a unified interface for encryption and decryption
+using symmetric, asymmetric, and post-quantum cryptographic algorithms.
+
+Supported algorithms are defined in `./config.py`
+"""
+
+
+import re
+from Crypto.PublicKey import RSA as _rsa
+from ghostbytes.crypto.kyber import kyber_decrypt, kyber_encrypt
+from ghostbytes.crypto.oaep_extension import oaep_extended_decrypt, oaep_extended_encrypt
+from ghostbytes.crypto.config import CryptoConfig
+from ghostbytes.error import algorithm_not_supported, parameter_not_exist, \
+    keyfile_cannot_crypt, keyfile_passphrase_incorrect, invalid_keyfile, \
+    invalid_configuration_type
+from ghostbytes.crypto.primitives import derive_key, \
+    aes_decrypt, aes_encrypt, rsa_oaep_decrypt, rsa_oaep_encrypt
+
+
+def encrypt(
+    config,
+    key,
+    plaintext,
+    rsa_passphrase=None
+):
+    """
+    Encrypts plaintext using the specified algorithm in `CryptoConfig`
+
+    Args:
+        config: Cryptographic configuration for the operation, includes the algorithm,
+            KDF parameters, and all necessary configuration to complete the operation.
+        key: Encryption key or key material. The expected format depends on the algorithm.
+            For symmetric encryption, key is typically a password or other secret key material.
+        plaintext:  ata to encrypt. Must be provided as bytes.
+        rsa_passphrase: Optional passphrase used to decrypt a password-protected RSA keyfile
+                        Must be provided as bytes.
+
+    Returns:
+        bytes: The encrypted ciphertext
+
+    Raises:
+        TypeError: If config args is not an instance of CryptoConfig.
+        CryptoError: Cryptographic errors likely raised due to invalid keys, malformed
+            ciphertext, invalid cryptographic parameters, or failures during
+            the underlying encryption/decryption operation.
+        GeneralError: Incorrect Usage of the function that are not cryptography-related.
+    """
+    _must_be_valid("config", config)
+    _must_be_valid("key", key)
+    _must_be_valid("plaintext", plaintext)
+
+    if not isinstance(config, CryptoConfig):
+        raise invalid_configuration_type()
+
+    algorithm = config.algorithm
+    if algorithm == "aes":
+        raw_key = derive_key(config, key)
+        return aes_encrypt(config, raw_key, plaintext)
+
+    if algorithm == "extended_oaep":
+        try:
+            rsa_key = _rsa.import_key(key, rsa_passphrase)
+        except (ValueError, TypeError, IndexError) as e:
+            if rsa_passphrase is not None:
+                raise keyfile_passphrase_incorrect() from e
+            raise invalid_keyfile() from e
+        if not rsa_key.can_encrypt():
+            raise keyfile_cannot_crypt("encrypt")
+
+        return oaep_extended_encrypt(config, rsa_key, plaintext)
+
+    if algorithm == "rsa-oaep":
+        try:
+            rsa_key = _rsa.import_key(key, rsa_passphrase)
+        except (ValueError, TypeError, IndexError) as e:
+            if rsa_passphrase is not None:
+                raise keyfile_passphrase_incorrect() from e
+            raise invalid_keyfile() from e
+        if not rsa_key.can_encrypt():
+            raise keyfile_cannot_crypt("encrypt")
+
+        return rsa_oaep_encrypt(config, rsa_key, plaintext)
+    if re.search(r"^ML-KEM-(768|1024)$", algorithm):
+        return kyber_encrypt(config, key, plaintext, rsa_passphrase)
+    raise algorithm_not_supported()
+
+
+def decrypt(
+    config,
+    key,
+    ciphertext,
+    rsa_passphrase=None
+):
+    """
+    Decrypts ciphertext using the specified algorithm in `CryptoConfig`
+
+    Args:
+        config: Cryptographic configuration for the operation, includes the algorithm,
+            KDF parameters, and all necessary configuration to complete the operation.
+        key: Encryption key or key material. The expected format depends on the algorithm.
+            For symmetric encryption, key is typically a password or other secret key material.
+        ciphertext: Encrypted data to decrypt. Must be provided as bytes.
+        rsa_passphrase: Optional passphrase used to decrypt a password-protected RSA keyfile
+                        Must be provided as bytes.
+
+    Returns:
+        bytes: The encrypted ciphertext
+
+    Raises:
+        TypeError: If config args is not an instance of CryptoConfig.
+        CryptoError: Cryptographic errors likely raised due to invalid keys, malformed
+            ciphertext, invalid cryptographic parameters, or failures during
+            the underlying encryption/decryption operation.
+        GeneralError: Incorrect Usage of the function that are not cryptography-related.
+    """
+
+    if not isinstance(config, CryptoConfig):
+        raise invalid_configuration_type()
+
+    _must_be_valid("config", config)
+    _must_be_valid("key", key)
+    _must_be_valid("ciphertext", ciphertext)
+
+    algorithm = config.algorithm
+    if algorithm == "aes":
+        raw_key = derive_key(config, key)
+        return aes_decrypt(config, raw_key, ciphertext)
+
+    if algorithm == "extended_oaep":
+        try:
+            rsa_key = _rsa.import_key(key, rsa_passphrase)
+        except (ValueError, TypeError, IndexError) as e:
+            if rsa_passphrase is not None:
+                raise keyfile_passphrase_incorrect() from e
+            raise invalid_keyfile() from e
+        if not rsa_key.has_private():
+            raise keyfile_cannot_crypt("decrypt")
+
+        return oaep_extended_decrypt(config, rsa_key, ciphertext)
+
+    if algorithm == "rsa-oaep":
+        try:
+            rsa_key = _rsa.import_key(key, rsa_passphrase)
+        except (ValueError, TypeError, IndexError) as e:
+            if rsa_passphrase is not None:
+                raise keyfile_passphrase_incorrect() from e
+            raise invalid_keyfile() from e
+        if not rsa_key.has_private():
+            raise keyfile_cannot_crypt("decrypt")
+
+        return rsa_oaep_decrypt(config, rsa_key, ciphertext)
+    if re.search(r"^ML-KEM-(768|1024)$", algorithm):
+        return kyber_decrypt(config, key, ciphertext, rsa_passphrase)
+    raise algorithm_not_supported()
+
+
+def _must_be_valid(name, param):
+    if param is None:
+        raise parameter_not_exist(name)

ghostbytes/crypto/crypto.pyi

@@ -0,0 +1,149 @@
+from typing import Literal, TypeAlias
+
+from Crypto.PublicKey.RSA import RsaKey
+
+from ghostbytes.crypto.config import (
+    AVAIL_ALG,
+    AVAIL_HASH,
+    AVAIL_HASH_STR,
+    AVAIL_RANDOM_STR,
+    COMMON_RSA_SIZE,
+    ENCRYPTED_SUFFIX,
+    OVERWRITE_OPTIONS,
+    RANDOM_SALT_SIZE,
+    RSA_KEY_OUT_FORMAT,
+    RSA_SIZE_WARNING_THRESHOLD,
+    CryptoConfig,
+)
+
+
+# Public configuration values
+Algorithm: TypeAlias = Literal[
+    "aes",
+    "rsa-oaep",
+    "extended_oaep",
+    "ML-KEM-768",
+    "ML-KEM-1024",
+]
+HashName: TypeAlias = Literal[
+    "sha3_512",
+    "sha3_256",
+    "sha512",
+    "sha256",
+    "blake2b",
+    "blake2s",
+    "md5",
+]
+KeyEncoding: TypeAlias = Literal["PEM", "DER", "OpenSSH"]
+MLKEMEncoding: TypeAlias = Literal["PEM", "DER"]
+
+
+# crypto.py
+def encrypt(
+    config: CryptoConfig,
+    key: bytes,
+    plaintext: bytes,
+    rsa_passphrase: str | bytes | None = None,
+) -> bytes: ...
+
+
+def decrypt(
+    config: CryptoConfig,
+    key: bytes,
+    ciphertext: bytes,
+    rsa_passphrase: str | bytes | None = None,
+) -> bytes: ...
+
+
+# primitives.py
+def aes_encrypt(config: CryptoConfig, key: bytes, plaintext: bytes) -> bytes: ...
+
+
+def aes_decrypt(config: CryptoConfig, key: bytes, ciphertext: bytes) -> bytes: ...
+
+
+def derive_key(config: CryptoConfig, secret: bytes) -> bytes: ...
+
+
+def rsa_oaep_encrypt(
+    config: CryptoConfig,
+    key: RsaKey,
+    plaintext: bytes,
+) -> bytes: ...
+
+
+def rsa_oaep_decrypt(
+    config: CryptoConfig,
+    key: RsaKey,
+    ciphertext: bytes,
+) -> bytes: ...
+
+
+def genrsa(
+    length: int,
+    exp: int,
+    passphrase: str | bytes | None,
+    out_format: KeyEncoding = "PEM",
+) -> tuple[bytes, bytes]: ...
+
+
+def verify_rsa(
+    public_key: bytes,
+    private_key: bytes,
+    passphrase: str | bytes | None = None,
+) -> bool: ...
+
+
+def detect_key_format(key_bytes: bytes) -> Literal["PEM", "DER"]: ...
+
+
+def keytype(
+    key_bytes: bytes,
+    passphrase: str | bytes | None = None,
+) -> Literal["RSA", "ML-KEM"]: ...
+
+
+# oaep_extension.py
+def oaep_extended_encrypt(
+    config: CryptoConfig,
+    rsa: RsaKey,
+    plaintext: bytes,
+) -> bytes: ...
+
+
+def oaep_extended_decrypt(
+    config: CryptoConfig,
+    rsa: RsaKey,
+    ciphertext: bytes,
+) -> bytes: ...
+
+
+# kyber.py
+def genkey(
+    alg: Literal["ML-KEM-768", "ML-KEM-1024"],
+    encoding: MLKEMEncoding,
+    passphrase: bytes | None = None,
+) -> tuple[bytes, bytes]: ...
+
+
+def verify_key(
+    pubkey: bytes,
+    privkey: bytes,
+    passphrase: str | bytes | None = None,
+) -> bool: ...
+
+
+def kyber_encrypt(
+    config: CryptoConfig,
+    pubkey: bytes,
+    plaintext: bytes,
+    passphrase: str | bytes | None = None,
+) -> bytes: ...
+
+
+def kyber_decrypt(
+    config: CryptoConfig,
+    privkey: bytes,
+    ciphertext: bytes,
+    passphrase: str | bytes | None = None,
+) -> bytes: ...