alt-python-pysypt 1.0.0__py3-none-any.whl

alt_python_pysypt-1.0.0.dist-info/METADATA

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: alt-python-pysypt
+Version: 1.0.0
+Summary: Jasypt-compatible PBE encryption and digest for Python
+Requires-Python: >=3.12
+Requires-Dist: alt-python-common
+Requires-Dist: cryptography>=42.0

alt_python_pysypt-1.0.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+pysypt/__init__.py,sha256=fhi4y7ZAL_U5_E85uMpr7IGrkYzz12TuhtM72iGLjZk,801
+pysypt/digester.py,sha256=PZ-52U8SraTR1JEs_cMrzvpN5VluJyy33l1biti7aqg,5544
+pysypt/encryptor.py,sha256=f-5IBZ0kn2wYMdxjz16yFLst07O4Zcr-wITMSK6x1Qs,12110
+pysypt/jasypt.py,sha256=Sa1ZEUiRVJNLAxkagXFe2vXWyf2ZbOyUwCrZ4BR-MBI,2498
+alt_python_pysypt-1.0.0.dist-info/METADATA,sha256=7L_Mq6IAJ7V-hB79BVw7dtKZ0AQO2SfMdO51HymslWw,216
+alt_python_pysypt-1.0.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+alt_python_pysypt-1.0.0.dist-info/RECORD,,

alt_python_pysypt-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pysypt/__init__.py

@@ -0,0 +1,31 @@
+"""
+pysypt — Jasypt-compatible PBE encryption and digest for Python.
+
+Mirrors the JS @alt-javascript/jasypt package.
+
+Quick start::
+
+    from pysypt import Jasypt, Encryptor, Digester
+
+    jasypt = Jasypt()
+    ciphertext = jasypt.encrypt("admin", "mypassword")
+    plaintext  = jasypt.decrypt(ciphertext, "mypassword")
+
+    stored = jasypt.digest("admin")
+    assert jasypt.matches("admin", stored) is True
+"""
+
+__author__ = "Craig Parravicini"
+__collaborators__ = ["Claude (Anthropic)"]
+
+from pysypt.jasypt import Jasypt
+from pysypt.encryptor import Encryptor, SUPPORTED_ALGORITHMS
+from pysypt.digester import Digester, SUPPORTED_ALGORITHMS as SUPPORTED_DIGEST_ALGORITHMS
+
+__all__ = [
+    "Jasypt",
+    "Encryptor",
+    "Digester",
+    "SUPPORTED_ALGORITHMS",
+    "SUPPORTED_DIGEST_ALGORITHMS",
+]

pysypt/digester.py

@@ -0,0 +1,176 @@
+"""
+pysypt.digester — Jasypt-compatible iterated-hash digest.
+
+Output format: base64(salt_bytes + hash_bytes)
+  - Random salt is prepended when no fixed salt is provided.
+  - matches() extracts the salt from the stored digest for verification.
+
+Algorithm map mirrors the JS Digester ALGO_MAP.
+"""
+
+from __future__ import annotations
+
+__author__ = "Craig Parravicini"
+__collaborators__ = ["Claude (Anthropic)"]
+
+import hashlib
+import hmac as _hmac
+import os
+import base64
+from typing import Optional
+
+from common import is_empty
+
+# ---------------------------------------------------------------------------
+# Algorithm table
+# ---------------------------------------------------------------------------
+
+_ALGO_MAP: dict[str, str] = {
+    "MD2": "md2",       # may not be available
+    "MD5": "md5",
+    "SHA-1": "sha1",
+    "SHA-224": "sha224",
+    "SHA-256": "sha256",
+    "SHA-384": "sha384",
+    "SHA-512": "sha512",
+    "SHA-512/224": "sha512_224",
+    "SHA-512/256": "sha512_256",
+    "SHA3-224": "sha3_224",
+    "SHA3-256": "sha3_256",
+    "SHA3-384": "sha3_384",
+    "SHA3-512": "sha3_512",
+}
+
+_AVAILABLE = set(hashlib.algorithms_available)
+
+# Normalise hashlib naming differences (sha512_224 vs sha512-224)
+def _normalise_algo(name: str) -> Optional[str]:
+    """Return the hashlib name if available, else None."""
+    if name in _AVAILABLE:
+        return name
+    # Try underscored variant
+    alt = name.replace("-", "_")
+    if alt in _AVAILABLE:
+        return alt
+    # Try dashed variant
+    alt2 = name.replace("_", "-")
+    if alt2 in _AVAILABLE:
+        return alt2
+    return None
+
+
+def _resolve(algo_key: str) -> Optional[str]:
+    raw = _ALGO_MAP.get(algo_key)
+    if raw is None:
+        return None
+    return _normalise_algo(raw)
+
+
+SUPPORTED_ALGORITHMS: list[str] = [k for k in _ALGO_MAP if _resolve(k) is not None]
+
+
+# ---------------------------------------------------------------------------
+# Digester
+# ---------------------------------------------------------------------------
+
+class Digester:
+    """
+    Jasypt-compatible iterated-hash digester.
+
+    Default: SHA-256, 1000 iterations, random 8-byte salt.
+    """
+
+    DEFAULT_SALT_SIZE = 8
+
+    def __init__(
+        self,
+        algorithm: str = "SHA-256",
+        salt: Optional[str] = None,
+        iterations: int = 1000,
+    ) -> None:
+        self.set_algorithm(algorithm)
+        self.salt: Optional[str] = salt
+        self.salt_size = self.DEFAULT_SALT_SIZE
+        self.iterations = iterations
+
+    def set_algorithm(self, algorithm: str) -> None:
+        resolved = _resolve(algorithm)
+        if resolved is None:
+            raise ValueError(f"Unsupported digest algorithm: {algorithm}")
+        self.algorithm = algorithm
+        self._hashlib_algo = resolved
+
+    def set_salt(self, salt: Optional[str]) -> None:
+        self.salt = salt
+
+    def set_iterations(self, iterations: int) -> None:
+        self.iterations = iterations
+
+    # ------------------------------------------------------------------
+    # Core compute
+    # ------------------------------------------------------------------
+
+    def _compute(self, salt_bytes: bytes, message: str, iterations: int) -> bytes:
+        """
+        Iterated hash: first = Hash(salt + message), subsequent = Hash(digest).
+        Mirrors the JS Digester._compute().
+        """
+        msg = message.encode("utf-8")
+        digest = hashlib.new(self._hashlib_algo, salt_bytes + msg).digest()
+        for _ in range(1, iterations):
+            digest = hashlib.new(self._hashlib_algo, digest).digest()
+        return digest
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def digest(
+        self,
+        message: str,
+        salt: Optional[str] = None,
+        iterations: Optional[int] = None,
+    ) -> str:
+        """
+        Digest a message.  Returns base64(salt_bytes + hash_bytes).
+        """
+        if not is_empty(salt):
+            salt_bytes = salt.encode("utf-8")  # type: ignore[union-attr]
+        elif not is_empty(self.salt):
+            salt_bytes = self.salt.encode("utf-8")  # type: ignore[union-attr]
+        else:
+            salt_bytes = os.urandom(self.salt_size)
+
+        _iters = iterations if iterations is not None else self.iterations
+        digest_bytes = self._compute(salt_bytes, message, _iters)
+        return base64.b64encode(salt_bytes + digest_bytes).decode("ascii")
+
+    def matches(
+        self,
+        message: str,
+        stored_digest: str,
+        salt: Optional[str] = None,
+        iterations: Optional[int] = None,
+    ) -> bool:
+        """
+        Verify message against a stored digest.
+
+        For random-salt digests, the salt is extracted from the first salt_size
+        bytes of the decoded stored value.  For fixed-salt digests, that salt is
+        used directly.
+        """
+        stored_bytes = base64.b64decode(stored_digest)
+
+        if not is_empty(salt):
+            salt_bytes = salt.encode("utf-8")  # type: ignore[union-attr]
+        elif not is_empty(self.salt):
+            salt_bytes = self.salt.encode("utf-8")  # type: ignore[union-attr]
+        else:
+            salt_bytes = stored_bytes[: self.salt_size]
+
+        expected = stored_bytes[len(salt_bytes) :]
+        _iters = iterations if iterations is not None else self.iterations
+        computed = self._compute(salt_bytes, message, _iters)
+
+        # Constant-time comparison
+        return _hmac.compare_digest(computed, expected)

pysypt/encryptor.py

@@ -0,0 +1,336 @@
+"""
+pysypt.encryptor — Jasypt-compatible PBE encryption.
+
+Supports the same algorithm table as the JS alt-javascript/jasypt Encryptor:
+
+PBE1 (EVP_BytesToKey-style KDF + DES / 3DES):
+  PBEWITHMD5ANDDES, PBEWITHMD5ANDTRIPLEDES, PBEWITHSHA1ANDDESEDE
+
+PBE2 (PBKDF2 + AES-CBC):
+  PBEWITHHMACSHA{1,224,256,384,512}ANDAES_{128,256}
+
+Wire format (base64-encoded):
+  PBE1 / PBE1N:  salt(8) + ciphertext
+  PBE2:          salt(16) + iv(16) + ciphertext
+
+All algorithms operate in CBC mode.  RC2 / RC4 variants from the JS version
+are intentionally omitted — they are removed from modern OpenSSL and have no
+safe analogue in the cryptography package.
+"""
+
+from __future__ import annotations
+
+__author__ = "Craig Parravicini"
+__collaborators__ = ["Claude (Anthropic)"]
+
+import os
+from typing import Any
+
+from cryptography.hazmat.primitives.ciphers import Cipher, modes
+from cryptography.hazmat.primitives.ciphers import algorithms as std_algorithms
+from cryptography.hazmat.primitives import hashes, padding as sym_padding
+from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC
+from cryptography.hazmat.backends import default_backend
+
+# TripleDES moved to decrepit in cryptography 44+; fall back gracefully
+try:
+    from cryptography.hazmat.decrepit.ciphers.algorithms import TripleDES as _TripleDES
+except ImportError:
+    _TripleDES = std_algorithms.TripleDES  # type: ignore[attr-defined]
+import hashlib
+import base64
+
+from common import is_empty
+
+# ---------------------------------------------------------------------------
+# Algorithm table
+# ---------------------------------------------------------------------------
+
+_PBE1_SALT_LEN = 8
+_PBE2_SALT_LEN = 16
+_PBE2_IV_LEN = 16
+
+_HASH_MAP = {
+    "md5": hashes.MD5,
+    "sha1": hashes.SHA1,
+    "sha224": hashes.SHA224,
+    "sha256": hashes.SHA256,
+    "sha384": hashes.SHA384,
+    "sha512": hashes.SHA512,
+}
+
+# Each entry:  type, hash/hmac name, key_len (bytes), iv_len (bytes)
+# PBE1 uses DES/3DES; PBE2 uses AES-CBC via PBKDF2
+_ALGO_CONFIG: dict[str, dict[str, Any]] = {
+    # PBE1 — EVP_BytesToKey KDF + DES
+    "PBEWITHMD5ANDDES": {
+        "type": "pbe1",
+        "hash": "md5",
+        "cipher": "des-cbc",
+        "key_len": 8,
+        "iv_len": 8,
+    },
+    # PBE1 — EVP_BytesToKey KDF + 3DES
+    "PBEWITHMD5ANDTRIPLEDES": {
+        "type": "pbe1",
+        "hash": "md5",
+        "cipher": "3des-cbc",
+        "key_len": 24,
+        "iv_len": 8,
+    },
+    "PBEWITHSHA1ANDDESEDE": {
+        "type": "pbe1",
+        "hash": "sha1",
+        "cipher": "3des-cbc",
+        "key_len": 24,
+        "iv_len": 8,
+    },
+    # PBE2 — PBKDF2 + AES-CBC
+    "PBEWITHHMACSHA1ANDAES_128": {"type": "pbe2", "hmac": "sha1", "key_len": 16},
+    "PBEWITHHMACSHA1ANDAES_256": {"type": "pbe2", "hmac": "sha1", "key_len": 32},
+    "PBEWITHHMACSHA224ANDAES_128": {"type": "pbe2", "hmac": "sha224", "key_len": 16},
+    "PBEWITHHMACSHA224ANDAES_256": {"type": "pbe2", "hmac": "sha224", "key_len": 32},
+    "PBEWITHHMACSHA256ANDAES_128": {"type": "pbe2", "hmac": "sha256", "key_len": 16},
+    "PBEWITHHMACSHA256ANDAES_256": {"type": "pbe2", "hmac": "sha256", "key_len": 32},
+    "PBEWITHHMACSHA384ANDAES_128": {"type": "pbe2", "hmac": "sha384", "key_len": 16},
+    "PBEWITHHMACSHA384ANDAES_256": {"type": "pbe2", "hmac": "sha384", "key_len": 32},
+    "PBEWITHHMACSHA512ANDAES_128": {"type": "pbe2", "hmac": "sha512", "key_len": 16},
+    "PBEWITHHMACSHA512ANDAES_256": {"type": "pbe2", "hmac": "sha512", "key_len": 32},
+}
+
+SUPPORTED_ALGORITHMS = list(_ALGO_CONFIG.keys())
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+def _pkcs7_pad(data: bytes, block_size: int) -> bytes:
+    padder = sym_padding.PKCS7(block_size * 8).padder()
+    return padder.update(data) + padder.finalize()
+
+
+def _pkcs7_unpad(data: bytes, block_size: int) -> bytes:
+    unpadder = sym_padding.PKCS7(block_size * 8).unpadder()
+    return unpadder.update(data) + unpadder.finalize()
+
+
+def _evp_bytes_to_key(
+    hash_name: str, password: bytes, salt: bytes, iterations: int, key_len: int, iv_len: int
+) -> tuple[bytes, bytes]:
+    """
+    OpenSSL EVP_BytesToKey-compatible KDF.
+
+    Produces successive hash blocks: H_i = Hash^n(H_{i-1} || password || salt)
+    Returns (key[:key_len], key[key_len:key_len+iv_len])
+    """
+    total = key_len + iv_len
+    result = b""
+    prev = b""
+    while len(result) < total:
+        block = prev + password + salt
+        for _ in range(iterations):
+            block = hashlib.new(hash_name, block).digest()
+        result += block
+        prev = block
+    key = result[:key_len]
+    iv = result[key_len : key_len + iv_len]
+    return key, iv
+
+
+def _pbkdf2_key(
+    hmac_name: str, password: bytes, salt: bytes, iterations: int, key_len: int
+) -> bytes:
+    """PBKDF2 key derivation using the cryptography library."""
+    hash_cls = _HASH_MAP[hmac_name]
+    kdf = PBKDF2HMAC(
+        algorithm=hash_cls(),
+        length=key_len,
+        salt=salt,
+        iterations=iterations,
+        backend=default_backend(),
+    )
+    return kdf.derive(password)
+
+
+# ---------------------------------------------------------------------------
+# Encryptor
+# ---------------------------------------------------------------------------
+
+class Encryptor:
+    """
+    Jasypt-compatible PBE encryptor.
+
+    Default algorithm: PBEWITHMD5ANDDES (same as Java jasypt default).
+    """
+
+    def __init__(
+        self,
+        algorithm: str = "PBEWITHMD5ANDDES",
+        salt: bytes | None = None,
+        iterations: int = 1000,
+    ) -> None:
+        self.set_algorithm(algorithm)
+        cfg = _ALGO_CONFIG[self.algorithm]
+        salt_len = _PBE2_SALT_LEN if cfg["type"] == "pbe2" else _PBE1_SALT_LEN
+        self.salt: bytes = salt if salt is not None else os.urandom(salt_len)
+        self.iterations = iterations
+
+    def set_algorithm(self, algorithm: str) -> None:
+        norm = algorithm.upper()
+        if norm not in _ALGO_CONFIG:
+            raise ValueError(f"Unsupported algorithm: {algorithm}")
+        self.algorithm = norm
+
+    def set_salt(self, salt: bytes | str | None) -> None:
+        cfg = _ALGO_CONFIG[self.algorithm]
+        salt_len = _PBE2_SALT_LEN if cfg["type"] == "pbe2" else _PBE1_SALT_LEN
+        if salt is None:
+            self.salt = os.urandom(salt_len)
+            return
+        if isinstance(salt, str):
+            b = salt.encode("utf-8")
+        else:
+            b = bytes(salt)
+        # Empty → random; short → zero-pad to required length; long → truncate
+        if len(b) == 0:
+            self.salt = os.urandom(salt_len)
+        elif len(b) < salt_len:
+            self.salt = b.ljust(salt_len, b"\x00")
+        else:
+            self.salt = b[:salt_len]
+
+    def set_iterations(self, iterations: int) -> None:
+        self.iterations = iterations or 1000
+
+    # ------------------------------------------------------------------
+    # Encrypt
+    # ------------------------------------------------------------------
+
+    def encrypt(
+        self,
+        payload: str,
+        password: str,
+        salt: bytes | None = None,
+        iterations: int | None = None,
+    ) -> str:
+        cfg = _ALGO_CONFIG[self.algorithm]
+        _salt = salt if salt is not None else self.salt
+        _iters = iterations if iterations is not None else self.iterations
+        pwd_bytes = (password or "").encode("utf-8")
+        data = payload.encode("utf-8")
+
+        if cfg["type"] == "pbe1":
+            return self._encrypt_pbe1(cfg, _salt, _iters, pwd_bytes, data)
+        # pbe2
+        return self._encrypt_pbe2(cfg, _salt, _iters, pwd_bytes, data)
+
+    def _encrypt_pbe1(
+        self,
+        cfg: dict,
+        salt: bytes,
+        iterations: int,
+        password: bytes,
+        data: bytes,
+    ) -> str:
+        key, iv = _evp_bytes_to_key(cfg["hash"], password, salt, iterations, cfg["key_len"], cfg["iv_len"])
+        ciphertext = self._pbe1_cipher_encrypt(cfg["cipher"], key, iv, data)
+        return base64.b64encode(salt + ciphertext).decode("ascii")
+
+    def _encrypt_pbe2(
+        self,
+        cfg: dict,
+        salt: bytes,
+        iterations: int,
+        password: bytes,
+        data: bytes,
+    ) -> str:
+        iv = os.urandom(_PBE2_IV_LEN)
+        key = _pbkdf2_key(cfg["hmac"], password, salt, iterations, cfg["key_len"])
+        padded = _pkcs7_pad(data, 16)
+        cipher = Cipher(std_algorithms.AES(key), modes.CBC(iv), backend=default_backend())
+        enc = cipher.encryptor()
+        ciphertext = enc.update(padded) + enc.finalize()
+        return base64.b64encode(salt + iv + ciphertext).decode("ascii")
+
+    # ------------------------------------------------------------------
+    # Decrypt
+    # ------------------------------------------------------------------
+
+    def decrypt(
+        self,
+        payload: str,
+        password: str,
+        iterations: int | None = None,
+    ) -> str:
+        cfg = _ALGO_CONFIG[self.algorithm]
+        _iters = iterations if iterations is not None else self.iterations
+        pwd_bytes = (password or "").encode("utf-8")
+        buf = base64.b64decode(payload)
+
+        if cfg["type"] == "pbe1":
+            return self._decrypt_pbe1(cfg, buf, _iters, pwd_bytes)
+        return self._decrypt_pbe2(cfg, buf, _iters, pwd_bytes)
+
+    def _decrypt_pbe1(
+        self,
+        cfg: dict,
+        buf: bytes,
+        iterations: int,
+        password: bytes,
+    ) -> str:
+        salt = buf[:_PBE1_SALT_LEN]
+        ciphertext = buf[_PBE1_SALT_LEN:]
+        key, iv = _evp_bytes_to_key(cfg["hash"], password, salt, iterations, cfg["key_len"], cfg["iv_len"])
+        plaintext = self._pbe1_cipher_decrypt(cfg["cipher"], key, iv, ciphertext)
+        return plaintext.decode("utf-8")
+
+    def _decrypt_pbe2(
+        self,
+        cfg: dict,
+        buf: bytes,
+        iterations: int,
+        password: bytes,
+    ) -> str:
+        salt = buf[:_PBE2_SALT_LEN]
+        iv = buf[_PBE2_SALT_LEN : _PBE2_SALT_LEN + _PBE2_IV_LEN]
+        ciphertext = buf[_PBE2_SALT_LEN + _PBE2_IV_LEN :]
+        key = _pbkdf2_key(cfg["hmac"], password, salt, iterations, cfg["key_len"])
+        cipher = Cipher(std_algorithms.AES(key), modes.CBC(iv), backend=default_backend())
+        dec = cipher.decryptor()
+        padded = dec.update(ciphertext) + dec.finalize()
+        return _pkcs7_unpad(padded, 16).decode("utf-8")
+
+    # ------------------------------------------------------------------
+    # Internal cipher wrappers
+    # ------------------------------------------------------------------
+
+    def _pbe1_cipher_encrypt(self, cipher_name: str, key: bytes, iv: bytes, data: bytes) -> bytes:
+        if cipher_name == "des-cbc":
+            # Single DES: cryptography library has no DES primitive; emulate using
+            # TripleDES-EDE with k1=k2=k3 (same 8-byte key repeated 3 times).
+            padded = _pkcs7_pad(data, 8)
+            c = Cipher(_TripleDES(key * 3), modes.CBC(iv), backend=default_backend())
+            enc = c.encryptor()
+            return enc.update(padded) + enc.finalize()
+        elif cipher_name == "3des-cbc":
+            padded = _pkcs7_pad(data, 8)
+            c = Cipher(_TripleDES(key), modes.CBC(iv), backend=default_backend())
+            enc = c.encryptor()
+            return enc.update(padded) + enc.finalize()
+        else:
+            raise ValueError(f"Unknown PBE1 cipher: {cipher_name}")
+
+    def _pbe1_cipher_decrypt(self, cipher_name: str, key: bytes, iv: bytes, data: bytes) -> bytes:
+        if cipher_name == "des-cbc":
+            c = Cipher(_TripleDES(key * 3), modes.CBC(iv), backend=default_backend())
+            dec = c.decryptor()
+            padded = dec.update(data) + dec.finalize()
+            return _pkcs7_unpad(padded, 8)
+        elif cipher_name == "3des-cbc":
+            c = Cipher(_TripleDES(key), modes.CBC(iv), backend=default_backend())
+            dec = c.decryptor()
+            padded = dec.update(data) + dec.finalize()
+            return _pkcs7_unpad(padded, 8)
+        else:
+            raise ValueError(f"Unknown PBE1 cipher: {cipher_name}")

pysypt/jasypt.py

@@ -0,0 +1,79 @@
+"""
+pysypt.jasypt — Thin facade matching the JS Jasypt class API.
+"""
+
+from __future__ import annotations
+
+__author__ = "Craig Parravicini"
+__collaborators__ = ["Claude (Anthropic)"]
+
+from typing import Optional
+
+from common import is_empty
+from pysypt.encryptor import Encryptor
+from pysypt.digester import Digester
+
+
+class Jasypt:
+    """
+    Facade providing encrypt / decrypt / digest / matches — mirrors the JS Jasypt class.
+
+    Each call constructs a fresh Encryptor or Digester with the provided options
+    so this class is stateless and thread-safe.
+    """
+
+    def encrypt(
+        self,
+        message: str,
+        password: str,
+        algorithm: str = "PBEWITHMD5ANDDES",
+        iterations: int = 1000,
+        salt: Optional[bytes] = None,
+    ) -> Optional[str]:
+        """Encrypt a plaintext message.  Returns None for empty input."""
+        if is_empty(message):
+            return None
+        enc = Encryptor(algorithm=algorithm, salt=salt, iterations=iterations)
+        return enc.encrypt(message, password)
+
+    def decrypt(
+        self,
+        encrypted_message: Optional[str],
+        password: str = "",
+        algorithm: str = "PBEWITHMD5ANDDES",
+        iterations: int = 1000,
+        salt: Optional[bytes] = None,
+    ) -> Optional[str]:
+        """Decrypt an encrypted message.  Returns None for empty input."""
+        if is_empty(encrypted_message):
+            return None
+        enc = Encryptor(algorithm=algorithm, salt=salt, iterations=iterations)
+        return enc.decrypt(encrypted_message, password)  # type: ignore[arg-type]
+
+    def digest(
+        self,
+        message: str,
+        salt: Optional[str] = None,
+        iterations: int = 1000,
+        algorithm: str = "SHA-256",
+    ) -> Optional[str]:
+        """One-way digest a message.  Returns None for empty input."""
+        if is_empty(message):
+            return None
+        digester = Digester(algorithm=algorithm, iterations=iterations)
+        return digester.digest(message, salt=salt)
+
+    def matches(
+        self,
+        message: str,
+        stored_digest: str,
+        salt: Optional[str] = None,
+        iterations: int = 1000,
+        algorithm: str = "SHA-256",
+    ) -> Optional[bool]:
+        """Verify plaintext against a stored digest.  Returns None for empty message."""
+        if is_empty(message):
+            return None
+        return Digester(algorithm=algorithm, iterations=iterations).matches(
+            message, stored_digest, salt=salt
+        )