Merge pull request #100 from roberthdevries/add-typing

Start adding typing information.

Author: dgarske

ChangeLog.rst

@@ -1,3 +1,9 @@
+wolfCrypt-py Release NEXT (TBD, 2026)
+==========================================
+
+* Add extra nonce parameter to Random generator
+
+
 wolfCrypt-py Release 5.8.4 (Jan 7, 2026)
 ==========================================
 

requirements/test.txt

@@ -1,3 +1,4 @@
 -r prod.txt
 tox
 pytest
+types-cffi

setup.py

@@ -74,6 +74,7 @@
         u"Programming Language :: Python :: 3.7",
         u"Programming Language :: Python :: 3.8",
         u"Programming Language :: Python :: 3.9",
+        u"Programming Language :: Python :: 3.10",
         u"Topic :: Security",
         u"Topic :: Security :: Cryptography",
         u"Topic :: Software Development"
@@ -83,5 +84,5 @@
     install_requires=["cffi>=1.0.0"],
     cffi_modules=["./scripts/build_ffi.py:ffibuilder"],
 
-    package_data={"wolfcrypt": ["*.dll"]}
+    package_data={"wolfcrypt": ["*.dll", "**/*.pyi"]}
 )

wolfcrypt/_ffi/__init__.pyi

@@ -0,0 +1,6 @@
+import _cffi_backend
+import wolfcrypt._ffi.lib as lib
+
+ffi: _cffi_backend.FFI
+
+__all__ = ["ffi", "lib"]

wolfcrypt/_ffi/lib.pyi

@@ -0,0 +1,76 @@
+
+from _cffi_backend import FFI
+from typing import TypeAlias
+
+INVALID_DEVID: int
+
+AES_ENABLED: int
+AES_SIV_ENABLED: int
+AESGCM_STREAM_ENABLED: int
+ASN_ENABLED: int
+CHACHA_ENABLED: int
+CHACHA_STREAM_ENABLED: int
+CHACHA20_POLY1305_ENABLED: int
+DES3_ENABLED: int
+ECC_ENABLED: int
+ED25519_ENABLED: int
+ED448_ENABLED: int
+FIPS_ENABLED: int
+HMAC_ENABLED: int
+KEYGEN_ENABLED: int
+HKDF_ENABLED: int
+ML_DSA_ENABLED: int
+ML_KEM_ENABLED: int
+MPAPI_ENABLED: int
+PWDBASED_ENABLED: int
+RSA_ENABLED: int
+RSA_PSS_ENABLED: int
+SHA_ENABLED: int
+SHA3_ENABLED: int
+SHA256_ENABLED: int
+SHA384_ENABLED: int
+SHA512_ENABLED: int
+WC_RNG_SEED_CB_ENABLED: int
+
+FIPS_VERSION: int
+
+WC_MGF1NONE: int
+WC_MGF1SHA1: int
+WC_MGF1SHA224: int
+WC_MGF1SHA256: int
+WC_MGF1SHA384: int
+WC_MGF1SHA512: int
+
+WC_HASH_TYPE_NONE: int
+WC_HASH_TYPE_MD2: int
+WC_HASH_TYPE_MD4: int
+WC_HASH_TYPE_MD5: int
+WC_HASH_TYPE_SHA: int
+WC_HASH_TYPE_SHA224: int
+WC_HASH_TYPE_SHA256: int
+WC_HASH_TYPE_SHA384: int
+WC_HASH_TYPE_SHA512: int
+WC_HASH_TYPE_MD5_SHA: int
+WC_HASH_TYPE_SHA3_224: int
+WC_HASH_TYPE_SHA3_256: int
+WC_HASH_TYPE_SHA3_384: int
+WC_HASH_TYPE_SHA3_512: int
+WC_HASH_TYPE_BLAKE2B: int
+WC_HASH_TYPE_BLAKE2S: int
+
+WC_ML_KEM_512: int
+WC_ML_KEM_768: int
+WC_ML_KEM_1024: int
+
+WC_ML_DSA_44: int
+WC_ML_DSA_65: int
+WC_ML_DSA_87: int
+
+WC_KEYTYPE_ALL: int
+
+RNG: TypeAlias = FFI.CData
+
+def wc_InitRngNonce_ex(rng: RNG, nonce: bytes, nonce_size: int, heap: FFI.CData, device_id: int) -> int: ...
+def wc_RNG_GenerateByte(rng: RNG, buffer: FFI.CData) -> int: ...
+def wc_RNG_GenerateBlock(rng: RNG, buffer: FFI.CData, len: int) -> int: ...
+def wc_FreeRng(rng: RNG) -> None: ...

wolfcrypt/random.py

@@ -20,6 +20,8 @@
 
 # pylint: disable=no-member,no-name-in-module
 
+from __future__ import annotations
+
 from wolfcrypt._ffi import ffi as _ffi
 from wolfcrypt._ffi import lib as _lib
 
@@ -31,47 +33,45 @@ class Random:
     A Cryptographically Secure Pseudo Random Number Generator - CSPRNG
     """
 
-    def __init__(self, nonce=_ffi.NULL, device_id=_lib.INVALID_DEVID):
-        self.native_object = _ffi.new("WC_RNG *")
+    def __init__(self, nonce: __builtins__.bytes = b"", device_id: int = _lib.INVALID_DEVID) -> None:
+        self.native_object: _lib.RNG | None = _ffi.new("WC_RNG *")
 
-        if nonce == _ffi.NULL:
-            nonce_size = 0
-        else:
-            nonce_size = len(nonce)
-        ret = _lib.wc_InitRngNonce_ex(self.native_object, nonce, nonce_size, _ffi.NULL, device_id)
+        ret = _lib.wc_InitRngNonce_ex(self.native_object, nonce, len(nonce), _ffi.NULL, device_id)
         if ret < 0:  # pragma: no cover
             self.native_object = None
             raise WolfCryptError("RNG init error (%d)" % ret)
 
     # making sure _lib.wc_FreeRng outlives WC_RNG instances
     _delete = _lib.wc_FreeRng
 
-    def __del__(self):
+    def __del__(self) -> None:
         if self.native_object:
             try:
                 self._delete(self.native_object)
             except AttributeError:
                 # Can occur during interpreter shutdown
                 pass
 
-    def byte(self):
+    def byte(self) -> __builtins__.bytes:
         """
         Generate and return a random byte.
         """
-        result = _ffi.new('byte[1]')
+        result = _ffi.new("byte[1]")
 
+        assert self.native_object is not None
         ret = _lib.wc_RNG_GenerateByte(self.native_object, result)
         if ret < 0:  # pragma: no cover
             raise WolfCryptError("RNG generate byte error (%d)" % ret)
 
         return _ffi.buffer(result, 1)[:]
 
-    def bytes(self, length):
+    def bytes(self, length: int) -> __builtins__.bytes:
         """
         Generate and return a random sequence of length bytes.
         """
-        result = _ffi.new('byte[%d]' % length)
+        result = _ffi.new("byte[%d]" % length)
 
+        assert self.native_object is not None
         ret = _lib.wc_RNG_GenerateBlock(self.native_object, result, length)
         if ret < 0:  # pragma: no cover
             raise WolfCryptError("RNG generate block error (%d)" % ret)

wolfcrypt/utils.py

@@ -20,16 +20,26 @@
 
 # pylint: disable=unused-import
 
+from __future__ import annotations
+
 from binascii import hexlify as b2h, unhexlify as h2b  # noqa: F401
 
 
-def t2b(string):
+def t2b(string: bytes | bytearray | memoryview | str) -> bytes:
     """
-    Converts text to binary.
+    Converts text to bytes.
 
-    Passes through bytes, bytearray, and memoryview unchanged.
+    Passes through bytes unchanged.
+    Objects of type bytearray or memoryview are converted to bytes.
     Encodes str to UTF-8 bytes.
+
+    :param string: text to convert to bytes.
+    :raises TypeError: if string is not one of the supported types.
     """
-    if isinstance(string, (bytes, bytearray, memoryview)):
+    if isinstance(string, bytes):
         return string
-    return str(string).encode("utf-8")
+    if isinstance(string, (bytearray, memoryview)):
+        return bytes(string)
+    if isinstance(string, str):
+        return str(string).encode("utf-8")
+    raise TypeError(f"String parameter of wrong type {type(string).__name__}, expected bytes, bytearray, memoryview or str")