Make random_key and random_nonce return bytearray, and add a nonce_increment utility function.

pyaegis/aegis128l.py

@@ -7,7 +7,7 @@ import secrets
 
 from ._loader import ffi
 from ._loader import lib as _lib
-from .util import Buffer, new_aligned_struct
+from .util import Buffer, new_aligned_struct, nonce_inc_inplace
 
 # Constants exposed as functions in C; mirror them as integers at module import time
 KEYBYTES = _lib.aegis128l_keybytes()
@@ -19,14 +19,14 @@ ALIGNMENT = 32
 RATE = 32
 
 
-def random_key() -> bytes:
+def random_key() -> bytearray:
     """Generate a random key using cryptographically secure random bytes."""
-    return secrets.token_bytes(KEYBYTES)
+    return bytearray(secrets.token_bytes(KEYBYTES))
 
 
-def random_nonce() -> bytes:
+def random_nonce() -> bytearray:
     """Generate a random nonce using cryptographically secure random bytes."""
-    return secrets.token_bytes(NPUBBYTES)
+    return bytearray(secrets.token_bytes(NPUBBYTES))
 
 
 def _ptr(buf):
@@ -802,6 +802,10 @@ __all__ = [
     "TAILBYTES_MAX",
     "ALIGNMENT",
     "RATE",
+    # utility functions
+    "random_key",
+    "random_nonce",
+    "nonce_inc_inplace",
     # one-shot functions
     "encrypt_detached",
     "decrypt_detached",

pyaegis/aegis128x2.py

@@ -7,7 +7,7 @@ import secrets
 
 from ._loader import ffi
 from ._loader import lib as _lib
-from .util import Buffer, new_aligned_struct
+from .util import Buffer, new_aligned_struct, nonce_inc_inplace
 
 # Constants exposed as functions in C; mirror them as integers at module import time
 KEYBYTES = _lib.aegis128x2_keybytes()
@@ -19,14 +19,14 @@ ALIGNMENT = 64
 RATE = 64
 
 
-def random_key() -> bytes:
+def random_key() -> bytearray:
     """Generate a random key using cryptographically secure random bytes."""
-    return secrets.token_bytes(KEYBYTES)
+    return bytearray(secrets.token_bytes(KEYBYTES))
 
 
-def random_nonce() -> bytes:
+def random_nonce() -> bytearray:
     """Generate a random nonce using cryptographically secure random bytes."""
-    return secrets.token_bytes(NPUBBYTES)
+    return bytearray(secrets.token_bytes(NPUBBYTES))
 
 
 def _ptr(buf):
@@ -802,6 +802,10 @@ __all__ = [
     "TAILBYTES_MAX",
     "ALIGNMENT",
     "RATE",
+    # utility functions
+    "random_key",
+    "random_nonce",
+    "nonce_inc_inplace",
     # one-shot functions
     "encrypt_detached",
     "decrypt_detached",

pyaegis/aegis128x4.py

@@ -7,7 +7,7 @@ import secrets
 
 from ._loader import ffi
 from ._loader import lib as _lib
-from .util import Buffer, new_aligned_struct
+from .util import Buffer, new_aligned_struct, nonce_inc_inplace
 
 # Constants exposed as functions in C; mirror them as integers at module import time
 KEYBYTES = _lib.aegis128x4_keybytes()
@@ -19,14 +19,14 @@ ALIGNMENT = 64
 RATE = 128
 
 
-def random_key() -> bytes:
+def random_key() -> bytearray:
     """Generate a random key using cryptographically secure random bytes."""
-    return secrets.token_bytes(KEYBYTES)
+    return bytearray(secrets.token_bytes(KEYBYTES))
 
 
-def random_nonce() -> bytes:
+def random_nonce() -> bytearray:
     """Generate a random nonce using cryptographically secure random bytes."""
-    return secrets.token_bytes(NPUBBYTES)
+    return bytearray(secrets.token_bytes(NPUBBYTES))
 
 
 def _ptr(buf):
@@ -802,6 +802,10 @@ __all__ = [
     "TAILBYTES_MAX",
     "ALIGNMENT",
     "RATE",
+    # utility functions
+    "random_key",
+    "random_nonce",
+    "nonce_inc_inplace",
     # one-shot functions
     "encrypt_detached",
     "decrypt_detached",

pyaegis/aegis256.py

@@ -7,7 +7,7 @@ import secrets
 
 from ._loader import ffi
 from ._loader import lib as _lib
-from .util import Buffer, new_aligned_struct
+from .util import Buffer, new_aligned_struct, nonce_inc_inplace
 
 # Constants exposed as functions in C; mirror them as integers at module import time
 KEYBYTES = _lib.aegis256_keybytes()
@@ -19,14 +19,14 @@ ALIGNMENT = 16
 RATE = 16
 
 
-def random_key() -> bytes:
+def random_key() -> bytearray:
     """Generate a random key using cryptographically secure random bytes."""
-    return secrets.token_bytes(KEYBYTES)
+    return bytearray(secrets.token_bytes(KEYBYTES))
 
 
-def random_nonce() -> bytes:
+def random_nonce() -> bytearray:
     """Generate a random nonce using cryptographically secure random bytes."""
-    return secrets.token_bytes(NPUBBYTES)
+    return bytearray(secrets.token_bytes(NPUBBYTES))
 
 
 def _ptr(buf):
@@ -802,6 +802,10 @@ __all__ = [
     "TAILBYTES_MAX",
     "ALIGNMENT",
     "RATE",
+    # utility functions
+    "random_key",
+    "random_nonce",
+    "nonce_inc_inplace",
     # one-shot functions
     "encrypt_detached",
     "decrypt_detached",

pyaegis/aegis256x2.py

@@ -7,7 +7,7 @@ import secrets
 
 from ._loader import ffi
 from ._loader import lib as _lib
-from .util import Buffer, new_aligned_struct
+from .util import Buffer, new_aligned_struct, nonce_inc_inplace
 
 # Constants exposed as functions in C; mirror them as integers at module import time
 KEYBYTES = _lib.aegis256x2_keybytes()
@@ -19,14 +19,14 @@ ALIGNMENT = 32
 RATE = 32
 
 
-def random_key() -> bytes:
+def random_key() -> bytearray:
     """Generate a random key using cryptographically secure random bytes."""
-    return secrets.token_bytes(KEYBYTES)
+    return bytearray(secrets.token_bytes(KEYBYTES))
 
 
-def random_nonce() -> bytes:
+def random_nonce() -> bytearray:
     """Generate a random nonce using cryptographically secure random bytes."""
-    return secrets.token_bytes(NPUBBYTES)
+    return bytearray(secrets.token_bytes(NPUBBYTES))
 
 
 def _ptr(buf):
@@ -802,6 +802,10 @@ __all__ = [
     "TAILBYTES_MAX",
     "ALIGNMENT",
     "RATE",
+    # utility functions
+    "random_key",
+    "random_nonce",
+    "nonce_inc_inplace",
     # one-shot functions
     "encrypt_detached",
     "decrypt_detached",

pyaegis/aegis256x4.py

@@ -7,7 +7,7 @@ import secrets
 
 from ._loader import ffi
 from ._loader import lib as _lib
-from .util import Buffer, new_aligned_struct
+from .util import Buffer, new_aligned_struct, nonce_inc_inplace
 
 # Constants exposed as functions in C; mirror them as integers at module import time
 KEYBYTES = _lib.aegis256x4_keybytes()
@@ -19,14 +19,14 @@ ALIGNMENT = 64
 RATE = 64
 
 
-def random_key() -> bytes:
+def random_key() -> bytearray:
     """Generate a random key using cryptographically secure random bytes."""
-    return secrets.token_bytes(KEYBYTES)
+    return bytearray(secrets.token_bytes(KEYBYTES))
 
 
-def random_nonce() -> bytes:
+def random_nonce() -> bytearray:
     """Generate a random nonce using cryptographically secure random bytes."""
-    return secrets.token_bytes(NPUBBYTES)
+    return bytearray(secrets.token_bytes(NPUBBYTES))
 
 
 def _ptr(buf):
@@ -802,6 +802,10 @@ __all__ = [
     "TAILBYTES_MAX",
     "ALIGNMENT",
     "RATE",
+    # utility functions
+    "random_key",
+    "random_nonce",
+    "nonce_inc_inplace",
     # one-shot functions
     "encrypt_detached",
     "decrypt_detached",

pyaegis/util.py

@@ -10,7 +10,7 @@ from typing import Protocol
 
 from ._loader import ffi
 
-__all__ = ["new_aligned_struct", "aligned_address", "Buffer"]
+__all__ = ["new_aligned_struct", "aligned_address", "Buffer", "nonce_increment"]
 
 try:
     from collections.abc import Buffer as _Buffer
@@ -45,3 +45,19 @@ def new_aligned_struct(ctype: str, alignment: int) -> tuple[object, object]:
     aligned_uc = ffi.addressof(base, offset)
     ptr = ffi.cast(f"{ctype} *", aligned_uc)
     return ptr, base
+
+
+def nonce_increment(nonce: Buffer) -> None:
+    """Increment the nonce in place using little-endian byte order.
+
+    Useful for generating unique nonces for each consecutive message.
+
+    Args:
+        nonce: The nonce buffer to increment (modified in place).
+    """
+    n = memoryview(nonce)
+    for i in range(len(n)):
+        if n[i] < 255:
+            n[i] += 1
+            return
+        n[i] = 0