pyaegis 0.1.0__tar.gz

pyaegis-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Frank Denis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyaegis-0.1.0/MANIFEST.in

@@ -0,0 +1,19 @@
+# Include C source files
+recursive-include c_src *.c *.h
+
+# Include build script
+include build_cffi.py
+
+# Include benchmark and demo scripts
+include benchmark.py
+include demo.py
+
+# Include documentation
+include README.md
+
+# Exclude unnecessary files
+global-exclude *.pyc
+global-exclude __pycache__
+global-exclude *.so
+global-exclude *.dylib
+global-exclude *.dll

pyaegis-0.1.0/PKG-INFO

@@ -0,0 +1,264 @@
+Metadata-Version: 2.4
+Name: pyaegis
+Version: 0.1.0
+Summary: Python bindings for libaegis - high-performance AEGIS authenticated encryption
+Author-email: Frank Denis <github@pureftpd.org>
+License: MIT
+Project-URL: Homepage, https://github.com/aegis-aead/pyaegis
+Project-URL: Repository, https://github.com/aegis-aead/pyaegis
+Project-URL: Issues, https://github.com/aegis-aead/pyaegis/issues
+Project-URL: Changelog, https://github.com/aegis-aead/pyaegis/blob/main/CHANGELOG.md
+Keywords: aegis,encryption,authenticated-encryption,aead,cryptography,cffi,security,crypto
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: C
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cffi>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.4.2; extra == "dev"
+Requires-Dist: pytest-cov>=7.0.0; extra == "dev"
+Requires-Dist: build>=1.3.0; extra == "dev"
+Requires-Dist: twine>=6.2.0; extra == "dev"
+Requires-Dist: ruff>=0.14.2; extra == "dev"
+Requires-Dist: mypy>=1.18.2; extra == "dev"
+Requires-Dist: pre-commit>=4.3.0; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest>=8.4.2; extra == "test"
+Requires-Dist: pytest-cov>=7.0.0; extra == "test"
+Dynamic: license-file
+
+# pyaegis
+
+[![CI](https://github.com/aegis-aead/pyaegis/actions/workflows/ci.yml/badge.svg)](https://github.com/aegis-aead/pyaegis/actions/workflows/ci.yml)
+[![PyPI version](https://badge.fury.io/py/pyaegis.svg)](https://badge.fury.io/py/pyaegis)
+[![Python versions](https://img.shields.io/pypi/pyversions/pyaegis.svg)](https://pypi.org/project/pyaegis/)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/aegis-aead/pyaegis/blob/main/LICENSE)
+[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
+
+Python bindings for libaegis - high-performance AEGIS authenticated encryption.
+
+## Overview
+
+pyaegis provides Pythonic interfaces to the AEGIS family of authenticated encryption algorithms.
+
+AEGIS is a high-performance authenticated cipher that provides both confidentiality and authenticity guarantees.
+
+### Supported Variants
+
+#### Authenticated Encryption (AEAD)
+
+- AEGIS-128L: 16-byte key, 16-byte nonce - optimized for performance
+- AEGIS-256: 32-byte key, 32-byte nonce - higher security margin
+- AEGIS-128X2: Dual-lane variant for higher throughput
+- AEGIS-128X4: Quad-lane variant for maximum throughput on AVX-512
+- AEGIS-256X2: Dual-lane variant with 256-bit security
+- AEGIS-256X4: Quad-lane variant with 256-bit security
+
+#### Message Authentication Codes (MAC)
+
+All AEAD variants have corresponding MAC variants for authentication without encryption:
+
+- AEGIS128L_MAC, AEGIS256_MAC
+- AEGIS128X2_MAC, AEGIS128X4_MAC
+- AEGIS256X2_MAC, AEGIS256X4_MAC
+
+## Installation
+
+### From PyPI
+
+Using [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv pip install pyaegis
+```
+
+Or using pip:
+
+```bash
+pip install pyaegis
+```
+
+### From Source
+
+The package compiles the C library automatically using any installed C compiler:
+
+```bash
+# Clone the repository
+git clone https://github.com/aegis-aead/pyaegis.git
+cd pyaegis
+
+# Install with uv (compiles C sources automatically)
+uv pip install .
+
+# Or for development
+uv pip install -e .
+```
+
+Alternatively with pip:
+
+```bash
+pip install .
+# Or for development
+pip install -e .
+```
+
+### Building a Distribution
+
+```bash
+# With uv
+uv run python -m build
+
+# Or with pip
+python -m build
+```
+
+This creates both source and wheel distributions in the `dist/` directory. The C sources are bundled in the package and compiled during installation.
+
+## Usage
+
+### Basic Encryption/Decryption
+
+```python
+from pyaegis import AEGIS128L
+
+# Create a cipher instance
+cipher = AEGIS128L()
+
+# Generate random key and nonce
+key = cipher.random_key()
+nonce = cipher.random_nonce()
+
+# Encrypt a message
+plaintext = b"Hello, World!"
+ciphertext = cipher.encrypt(key, nonce, plaintext)
+
+# Decrypt the message
+decrypted = cipher.decrypt(key, nonce, ciphertext)
+assert decrypted == plaintext
+```
+
+### With Additional Authenticated Data (AAD)
+
+```python
+from pyaegis import AEGIS256
+
+cipher = AEGIS256()
+key = cipher.random_key()
+nonce = cipher.random_nonce()
+
+# AAD is authenticated but not encrypted
+associated_data = b"metadata"
+
+ciphertext = cipher.encrypt(key, nonce, b"secret", associated_data=associated_data)
+plaintext = cipher.decrypt(key, nonce, ciphertext, associated_data=associated_data)
+```
+
+### Detached Tag Mode
+
+```python
+from pyaegis import AEGIS128L
+
+cipher = AEGIS128L()
+key = cipher.random_key()
+nonce = cipher.random_nonce()
+
+# Encrypt with detached tag
+ciphertext, tag = cipher.encrypt_detached(key, nonce, b"secret")
+
+# Decrypt with detached tag
+plaintext = cipher.decrypt_detached(key, nonce, ciphertext, tag)
+```
+
+### Tag Size
+
+By default, a 32-byte (256-bit) tag is used for maximum security. You can also use a 16-byte (128-bit) tag:
+
+```python
+cipher = AEGIS128L(tag_size=16)
+```
+
+### Stream Generation
+
+Generate a deterministic pseudo-random byte sequence (AEGIS-128L and AEGIS-256 only):
+
+```python
+from pyaegis import AEGIS128L
+
+key = AEGIS128L.random_key()
+nonce = AEGIS128L.random_nonce()
+
+# Generate 1024 pseudo-random bytes
+random_bytes = AEGIS128L.stream(key, nonce, 1024)
+```
+
+### Message Authentication Code (MAC)
+
+Generate and verify authentication tags without encryption:
+
+```python
+from pyaegis import AEGIS128L_MAC, DecryptionError
+
+key = AEGIS128L_MAC.random_key()
+nonce = AEGIS128L_MAC.random_nonce()
+
+# Generate MAC tag
+mac = AEGIS128L_MAC(key, nonce)
+mac.update(b"message part 1")
+mac.update(b"message part 2")
+tag = mac.final()
+
+# Verify MAC tag
+mac_verify = AEGIS128L_MAC(key, nonce)
+mac_verify.update(b"message part 1message part 2")
+try:
+    mac_verify.verify(tag)
+    print("Authentication successful!")
+except DecryptionError:
+    print("Authentication failed!")
+```
+
+Important: The same key must NOT be used for both MAC and encryption operations.
+
+## Error Handling
+
+```python
+from pyaegis import AEGIS128L, DecryptionError
+
+cipher = AEGIS128L()
+key = cipher.random_key()
+nonce = cipher.random_nonce()
+
+try:
+    # This will raise DecryptionError if authentication fails
+    plaintext = cipher.decrypt(key, nonce, tampered_ciphertext)
+except DecryptionError:
+    print("Authentication failed - ciphertext was tampered with!")
+```
+
+## Performance
+
+The library automatically detects CPU features at runtime and uses the most optimized implementation available:
+
+- AES-NI on Intel/AMD processors
+- ARM Crypto Extensions on ARM processors
+- AVX2 and AVX-512 for multi-lane variants
+- Software fallback for other platforms
+
+Multi-lane variants (X2, X4) provide higher throughput on systems with appropriate SIMD support.
+
+## Security Considerations
+
+- Nonce Uniqueness: Never reuse a nonce with the same key. If you can't maintain a counter, use `random_nonce()` for each message.
+- Key Management: Use `random_key()` to generate cryptographically secure keys. Keep keys secret.
+- AAD: Additional authenticated data is not encrypted but is protected against tampering.

pyaegis-0.1.0/README.md

@@ -0,0 +1,224 @@
+# pyaegis
+
+[![CI](https://github.com/aegis-aead/pyaegis/actions/workflows/ci.yml/badge.svg)](https://github.com/aegis-aead/pyaegis/actions/workflows/ci.yml)
+[![PyPI version](https://badge.fury.io/py/pyaegis.svg)](https://badge.fury.io/py/pyaegis)
+[![Python versions](https://img.shields.io/pypi/pyversions/pyaegis.svg)](https://pypi.org/project/pyaegis/)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/aegis-aead/pyaegis/blob/main/LICENSE)
+[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
+
+Python bindings for libaegis - high-performance AEGIS authenticated encryption.
+
+## Overview
+
+pyaegis provides Pythonic interfaces to the AEGIS family of authenticated encryption algorithms.
+
+AEGIS is a high-performance authenticated cipher that provides both confidentiality and authenticity guarantees.
+
+### Supported Variants
+
+#### Authenticated Encryption (AEAD)
+
+- AEGIS-128L: 16-byte key, 16-byte nonce - optimized for performance
+- AEGIS-256: 32-byte key, 32-byte nonce - higher security margin
+- AEGIS-128X2: Dual-lane variant for higher throughput
+- AEGIS-128X4: Quad-lane variant for maximum throughput on AVX-512
+- AEGIS-256X2: Dual-lane variant with 256-bit security
+- AEGIS-256X4: Quad-lane variant with 256-bit security
+
+#### Message Authentication Codes (MAC)
+
+All AEAD variants have corresponding MAC variants for authentication without encryption:
+
+- AEGIS128L_MAC, AEGIS256_MAC
+- AEGIS128X2_MAC, AEGIS128X4_MAC
+- AEGIS256X2_MAC, AEGIS256X4_MAC
+
+## Installation
+
+### From PyPI
+
+Using [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv pip install pyaegis
+```
+
+Or using pip:
+
+```bash
+pip install pyaegis
+```
+
+### From Source
+
+The package compiles the C library automatically using any installed C compiler:
+
+```bash
+# Clone the repository
+git clone https://github.com/aegis-aead/pyaegis.git
+cd pyaegis
+
+# Install with uv (compiles C sources automatically)
+uv pip install .
+
+# Or for development
+uv pip install -e .
+```
+
+Alternatively with pip:
+
+```bash
+pip install .
+# Or for development
+pip install -e .
+```
+
+### Building a Distribution
+
+```bash
+# With uv
+uv run python -m build
+
+# Or with pip
+python -m build
+```
+
+This creates both source and wheel distributions in the `dist/` directory. The C sources are bundled in the package and compiled during installation.
+
+## Usage
+
+### Basic Encryption/Decryption
+
+```python
+from pyaegis import AEGIS128L
+
+# Create a cipher instance
+cipher = AEGIS128L()
+
+# Generate random key and nonce
+key = cipher.random_key()
+nonce = cipher.random_nonce()
+
+# Encrypt a message
+plaintext = b"Hello, World!"
+ciphertext = cipher.encrypt(key, nonce, plaintext)
+
+# Decrypt the message
+decrypted = cipher.decrypt(key, nonce, ciphertext)
+assert decrypted == plaintext
+```
+
+### With Additional Authenticated Data (AAD)
+
+```python
+from pyaegis import AEGIS256
+
+cipher = AEGIS256()
+key = cipher.random_key()
+nonce = cipher.random_nonce()
+
+# AAD is authenticated but not encrypted
+associated_data = b"metadata"
+
+ciphertext = cipher.encrypt(key, nonce, b"secret", associated_data=associated_data)
+plaintext = cipher.decrypt(key, nonce, ciphertext, associated_data=associated_data)
+```
+
+### Detached Tag Mode
+
+```python
+from pyaegis import AEGIS128L
+
+cipher = AEGIS128L()
+key = cipher.random_key()
+nonce = cipher.random_nonce()
+
+# Encrypt with detached tag
+ciphertext, tag = cipher.encrypt_detached(key, nonce, b"secret")
+
+# Decrypt with detached tag
+plaintext = cipher.decrypt_detached(key, nonce, ciphertext, tag)
+```
+
+### Tag Size
+
+By default, a 32-byte (256-bit) tag is used for maximum security. You can also use a 16-byte (128-bit) tag:
+
+```python
+cipher = AEGIS128L(tag_size=16)
+```
+
+### Stream Generation
+
+Generate a deterministic pseudo-random byte sequence (AEGIS-128L and AEGIS-256 only):
+
+```python
+from pyaegis import AEGIS128L
+
+key = AEGIS128L.random_key()
+nonce = AEGIS128L.random_nonce()
+
+# Generate 1024 pseudo-random bytes
+random_bytes = AEGIS128L.stream(key, nonce, 1024)
+```
+
+### Message Authentication Code (MAC)
+
+Generate and verify authentication tags without encryption:
+
+```python
+from pyaegis import AEGIS128L_MAC, DecryptionError
+
+key = AEGIS128L_MAC.random_key()
+nonce = AEGIS128L_MAC.random_nonce()
+
+# Generate MAC tag
+mac = AEGIS128L_MAC(key, nonce)
+mac.update(b"message part 1")
+mac.update(b"message part 2")
+tag = mac.final()
+
+# Verify MAC tag
+mac_verify = AEGIS128L_MAC(key, nonce)
+mac_verify.update(b"message part 1message part 2")
+try:
+    mac_verify.verify(tag)
+    print("Authentication successful!")
+except DecryptionError:
+    print("Authentication failed!")
+```
+
+Important: The same key must NOT be used for both MAC and encryption operations.
+
+## Error Handling
+
+```python
+from pyaegis import AEGIS128L, DecryptionError
+
+cipher = AEGIS128L()
+key = cipher.random_key()
+nonce = cipher.random_nonce()
+
+try:
+    # This will raise DecryptionError if authentication fails
+    plaintext = cipher.decrypt(key, nonce, tampered_ciphertext)
+except DecryptionError:
+    print("Authentication failed - ciphertext was tampered with!")
+```
+
+## Performance
+
+The library automatically detects CPU features at runtime and uses the most optimized implementation available:
+
+- AES-NI on Intel/AMD processors
+- ARM Crypto Extensions on ARM processors
+- AVX2 and AVX-512 for multi-lane variants
+- Software fallback for other platforms
+
+Multi-lane variants (X2, X4) provide higher throughput on systems with appropriate SIMD support.
+
+## Security Considerations
+
+- Nonce Uniqueness: Never reuse a nonce with the same key. If you can't maintain a counter, use `random_nonce()` for each message.
+- Key Management: Use `random_key()` to generate cryptographically secure keys. Keep keys secret.
+- AAD: Additional authenticated data is not encrypted but is protected against tampering.