Add aeg.cipher(alg) for loading modules by name in str. Added aeg.CIPHERS mapping of the nominal names to module names and Cipher for typing literals.

src/aeg/__init__.py

@@ -0,0 +1,16 @@
+import importlib
+
+from ._ciphers import CIPHERS, CipherName
+from ._typing import Cipher
+
+__all__ = ["cipher", "CIPHERS", "Cipher", "CipherName"]
+
+
+def cipher(alg: CipherName) -> Cipher:
+    """Acquire a cipher module by name."""
+    name = alg.lower().replace("-", "")
+    if name == "aegis128":
+        name = "aegis128l"  # AEGIS-128 is dead, the user meant AEGIS-128L
+    if name in CIPHERS.values():
+        return importlib.import_module(f".{name}", __package__)  # type: ignore[return-value]
+    raise ValueError(f"Unknown algorithm {alg!r}. Valid options: {', '.join(CIPHERS)}")

src/aeg/_ciphers.py

@@ -0,0 +1,20 @@
+# This file is generated by tools/generate.py. Do not edit.
+from typing import Literal
+
+CipherName = Literal[
+    "AEGIS-128L",
+    "AEGIS-128X2",
+    "AEGIS-128X4",
+    "AEGIS-256",
+    "AEGIS-256X2",
+    "AEGIS-256X4",
+]
+
+CIPHERS: dict[CipherName, str] = {
+    "AEGIS-128L": "aegis128l",
+    "AEGIS-128X2": "aegis128x2",
+    "AEGIS-128X4": "aegis128x4",
+    "AEGIS-256": "aegis256",
+    "AEGIS-256X2": "aegis256x2",
+    "AEGIS-256X4": "aegis256x4",
+}

src/aeg/_typing.py

@@ -0,0 +1,122 @@
+from typing import TYPE_CHECKING, Protocol
+
+if TYPE_CHECKING:
+    from .util import Buffer
+
+__all__ = ["Cipher"]
+
+
+class _Mac(Protocol):
+    def reset(self) -> None: ...
+    def clone(self) -> "_Mac": ...
+    def update(self, data: "Buffer") -> None: ...
+    def final(self, into: "Buffer | None" = None) -> bytearray | memoryview: ...
+    def digest(self) -> bytes: ...
+    def hexdigest(self) -> str: ...
+    def verify(self, mac: "Buffer") -> None: ...
+
+
+class _Encryptor(Protocol):
+    def update(
+        self, message: "Buffer", into: "Buffer | None" = None
+    ) -> bytearray | memoryview: ...
+    def final(self, into: "Buffer | None" = None) -> bytearray | memoryview: ...
+
+
+class _Decryptor(Protocol):
+    def update(
+        self, ct: "Buffer", into: "Buffer | None" = None
+    ) -> bytearray | memoryview: ...
+    def final(self, mac: "Buffer") -> None: ...
+
+
+class Cipher(Protocol):
+    NAME: str
+    KEYBYTES: int
+    NONCEBYTES: int
+    MACBYTES: int
+    MACBYTES_LONG: int
+    ALIGNMENT: int
+    RATE: int
+
+    Mac: type[_Mac]
+    Encryptor: type[_Encryptor]
+    Decryptor: type[_Decryptor]
+
+    @staticmethod
+    def random_key() -> bytearray: ...
+    @staticmethod
+    def random_nonce() -> bytearray: ...
+    @staticmethod
+    def encrypt_detached(
+        key: "Buffer",
+        nonce: "Buffer",
+        message: "Buffer",
+        ad: "Buffer | None" = None,
+        *,
+        maclen: int = ...,
+        ct_into: "Buffer | None" = None,
+        mac_into: "Buffer | None" = None,
+    ) -> tuple[bytearray | memoryview, bytearray | memoryview]: ...
+    @staticmethod
+    def decrypt_detached(
+        key: "Buffer",
+        nonce: "Buffer",
+        ct: "Buffer",
+        mac: "Buffer",
+        ad: "Buffer | None" = None,
+        *,
+        into: "Buffer | None" = None,
+    ) -> bytearray | memoryview: ...
+    @staticmethod
+    def encrypt(
+        key: "Buffer",
+        nonce: "Buffer",
+        message: "Buffer",
+        ad: "Buffer | None" = None,
+        *,
+        maclen: int = ...,
+        into: "Buffer | None" = None,
+    ) -> bytearray | memoryview: ...
+    @staticmethod
+    def decrypt(
+        key: "Buffer",
+        nonce: "Buffer",
+        ct: "Buffer",
+        ad: "Buffer | None" = None,
+        *,
+        maclen: int = ...,
+        into: "Buffer | None" = None,
+    ) -> bytearray | memoryview: ...
+    @staticmethod
+    def stream(
+        key: "Buffer",
+        nonce: "Buffer | None",
+        length: int | None = None,
+        *,
+        into: "Buffer | None" = None,
+    ) -> "bytearray | Buffer": ...
+    @staticmethod
+    def encrypt_unauthenticated(
+        key: "Buffer",
+        nonce: "Buffer",
+        message: "Buffer",
+        *,
+        into: "Buffer | None" = None,
+    ) -> bytearray | memoryview: ...
+    @staticmethod
+    def decrypt_unauthenticated(
+        key: "Buffer",
+        nonce: "Buffer",
+        ct: "Buffer",
+        *,
+        into: "Buffer | None" = None,
+    ) -> bytearray | memoryview: ...
+    @staticmethod
+    def mac(
+        key: "Buffer",
+        nonce: "Buffer",
+        data: "Buffer",
+        maclen: int = ...,
+        into: "Buffer | None" = None,
+    ) -> bytearray | memoryview: ...