blockchainkit 0.2.0__py3-none-any.whl

blockchainkit/crypto/systems/commitments.py

@@ -0,0 +1,93 @@
+"""Commitments: salted hash commitments (Blum 1981) and Pedersen commitments (1991).
+
+A commitment is a sealed envelope: binding (the committer cannot change the
+contents later) and hiding (nobody can read them before the opening). A hash
+commitment is computationally hiding and binding. A Pedersen commitment is
+*perfectly* hiding and computationally binding, and commitments add.
+"""
+
+import hmac
+
+from blockchainkit._validation import integer
+from blockchainkit.constants import COMMIT_DOMAIN, PEDERSEN_DOMAIN
+from blockchainkit.crypto.systems.asymmetric import TEACHING_GROUP, DHGroup
+from blockchainkit.crypto.systems.hashing import sha256
+
+
+def commit(message: bytes, salt: bytes) -> bytes:
+    """Commit to a message with a secret salt of at least 16 bytes.
+
+    Parameters
+    ----------
+    message : bytes
+        Bytes to commit to.
+    salt : bytes
+        Random secret salt; fixed salts are only appropriate for experiments.
+
+    Returns
+    -------
+    bytes
+        Domain-separated digest. Length framing prevents ambiguous openings.
+
+    Notes
+    -----
+    Hiding depends on salt entropy; binding relies on collision resistance.
+    """
+    if not isinstance(message, bytes) or not isinstance(salt, bytes):
+        raise TypeError("message and salt must be bytes")
+    if len(salt) < 16:
+        raise ValueError("use at least 16 salt bytes")
+    return sha256(COMMIT_DOMAIN + len(salt).to_bytes(8, "big") + salt + message)
+
+
+def verify_commitment(digest: bytes, message: bytes, salt: bytes) -> bool:
+    """Check an opening against a commitment using constant-time comparison."""
+    return hmac.compare_digest(digest, commit(message, salt))
+
+
+def pedersen_generators(group: DHGroup = TEACHING_GROUP) -> tuple[int, int]:
+    """Return ``(g, h)``: the group generator and a second, independent generator.
+
+    ``h`` is derived by hashing the group parameters into the subgroup, so
+    nobody knows ``log_g(h)``. Anyone who did could open a commitment to any
+    value, which is why ``h`` must not be chosen by the committer.
+    """
+    counter = 0
+    while True:
+        seed = PEDERSEN_DOMAIN + f"{group.p}:{group.q}:{group.g}:{counter}".encode()
+        candidate = int.from_bytes(sha256(seed), "big") % group.p
+        h = pow(candidate, (group.p - 1) // group.q, group.p)
+        if h not in (0, 1, group.g):
+            return group.g, h
+        counter += 1  # Degenerate candidate (probability about 2/q): hash again.
+
+
+def pedersen_commit(value: int, blinding: int, group: DHGroup = TEACHING_GROUP) -> int:
+    """Commit to ``value`` as ``g**value * h**blinding mod p``.
+
+    With a uniformly random blinding factor the commitment is uniformly
+    distributed whatever the value (perfect hiding). Opening it to a
+    different value would reveal ``log_g(h)`` (computational binding).
+    Commitments multiply to a commitment of the sum:
+    ``C(a, r) * C(b, s) = C(a + b, r + s)``.
+
+    Parameters
+    ----------
+    value, blinding : int
+        Elements of the integers modulo the group order q.
+    group : DHGroup
+        A prime-order subgroup; defaults to
+        :data:`~blockchainkit.crypto.systems.asymmetric.TEACHING_GROUP`.
+
+    Examples
+    --------
+    >>> from blockchainkit.crypto import pedersen_commit, TEACHING_GROUP as G
+    >>> pedersen_commit(2, 5) * pedersen_commit(3, 7) % G.p == pedersen_commit(5, 12)
+    True
+    """
+    for number, name in ((value, "value"), (blinding, "blinding")):
+        integer(number, name)
+        if number >= group.q:
+            raise ValueError(f"{name} must be below the group order q")
+    g, h = pedersen_generators(group)
+    return pow(g, value, group.p) * pow(h, blinding, group.p) % group.p

blockchainkit/crypto/systems/curves.py

@@ -0,0 +1,205 @@
+"""Readable elliptic-curve group arithmetic, not constant-time cryptography.
+
+Points are ``(x, y)`` tuples; ``None`` denotes the point at infinity.
+The curve equation is y**2 = x**3 + a*x + b modulo p.
+"""
+
+from dataclasses import dataclass
+from math import isqrt
+
+from blockchainkit._validation import integer
+from blockchainkit.crypto.core.base import Point
+from blockchainkit.crypto.utils.primes import is_prime
+
+_SECP_P = 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEFFFFFC2F
+_SECP_N = 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364141
+
+
+@dataclass(frozen=True)
+class Curve:
+    """A nonsingular prime-field curve with a prime-order generator.
+
+    Parameters
+    ----------
+    p, a, b : int
+        Field modulus and reduced curve coefficients.
+    generator : tuple of int
+        Affine coordinates of the base point.
+    order : int
+        Prime order of the base point.
+    name : str
+        Human-readable label.
+
+    Notes
+    -----
+    Custom field/order primes must be below 2**64, which bounds the
+    educational primality check. secp256k1's own field prime and group
+    order are also accepted, each only in its own role.
+    """
+
+    p: int
+    a: int
+    b: int
+    generator: tuple[int, int]
+    order: int
+    name: str = "custom"
+
+    def __post_init__(self) -> None:
+        for value, known in ((self.p, _SECP_P), (self.order, _SECP_N)):
+            integer(value, "prime", 3)
+            if value == known:
+                continue
+            if value >= 2**64:
+                raise ValueError("custom primes must be below 2**64")
+            if not is_prime(value):
+                raise ValueError("field modulus and generator order must be prime")
+        for value in (self.a, self.b):
+            integer(value, "coefficient")
+            if value >= self.p:
+                raise ValueError("coefficients must be reduced modulo p")
+        if (4 * self.a**3 + 27 * self.b**2) % self.p == 0:
+            raise ValueError("singular curve")
+        if self.generator is None or not self.contains(self.generator):
+            raise ValueError("generator must be a finite point on the curve")
+        if multiply(self.order, self.generator, self) is not None:
+            raise ValueError("generator does not have the claimed order")
+
+    def contains(self, point: Point) -> bool:
+        """Return whether point is infinity or a canonical affine curve point."""
+        if point is None:
+            return True
+        if not isinstance(point, tuple) or len(point) != 2:
+            return False
+        x, y = point
+        return (
+            type(x) is int
+            and type(y) is int
+            and 0 <= x < self.p
+            and 0 <= y < self.p
+            and (y * y - x**3 - self.a * x - self.b) % self.p == 0
+        )
+
+    @property
+    def cofactor_is_one(self) -> bool:
+        """Whether the generator's subgroup is provably the whole curve group.
+
+        Hasse's theorem bounds the number of points: #E <= p + 1 + 2*sqrt(p).
+        The subgroup order n divides #E, so if 2n exceeds that bound the
+        cofactor #E/n must be 1. Every on-curve point then lies in the
+        subgroup, and verifiers can skip the n*P = O membership check.
+        """
+        return 2 * self.order > self.p + 1 + 2 * (isqrt(self.p) + 1)
+
+
+def _add(left: Point, right: Point, curve: Curve) -> Point:
+    if left is None:
+        return right
+    if right is None:
+        return left
+    x1, y1 = left
+    x2, y2 = right
+    p = curve.p
+    if x1 == x2 and (y1 + y2) % p == 0:
+        return None
+    if left == right:
+        slope = (3 * x1 * x1 + curve.a) * pow(2 * y1, -1, p) % p
+    else:
+        slope = (y2 - y1) * pow(x2 - x1, -1, p) % p
+    x3 = (slope * slope - x1 - x2) % p
+    return x3, (slope * (x1 - x3) - y1) % p
+
+
+def add(left: Point, right: Point, curve: Curve) -> Point:
+    """Add two validated points, including infinity and inverse pairs."""
+    if not curve.contains(left) or not curve.contains(right):
+        raise ValueError("points must lie on the curve")
+    return _add(left, right, curve)
+
+
+def multiply(scalar: int, point: Point, curve: Curve) -> Point:
+    """Multiply a point by a signed integer using double-and-add.
+
+    Scalars are not reduced modulo the generator order: this also allows
+    checking subgroup membership for arbitrary points on a custom curve.
+    """
+    if type(scalar) is not int:
+        raise TypeError(f"scalar must be an integer, not {type(scalar).__name__}")
+    if not curve.contains(point):
+        raise ValueError("point must lie on the curve")
+    if scalar < 0:
+        point = None if point is None else (point[0], -point[1] % curve.p)
+        scalar = -scalar
+    result = None
+    while scalar:
+        if scalar & 1:
+            result = _add(result, point, curve)
+        point = _add(point, point, curve)
+        scalar >>= 1
+    return result
+
+
+TOY_CURVE = Curve(17, 2, 2, (5, 1), 19, "toy17")
+SECP256K1 = Curve(
+    _SECP_P,
+    0,
+    7,
+    (
+        0x79BE667EF9DCBBAC55A06295CE870B07029BFCDB2DCE28D959F2815B16F81798,
+        0x483ADA7726A3C4655DA4FBFC0E1108A8FD17B448A68554199C47D08FFB10D4B8,
+    ),
+    _SECP_N,
+    "secp256k1",
+)
+
+
+def public_key(private: int, curve: Curve = SECP256K1) -> tuple[int, int]:
+    """Derive private*G for 1 <= private < generator order.
+
+    >>> from blockchainkit.crypto import public_key, TOY_CURVE
+    >>> public_key(2, TOY_CURVE)
+    (6, 3)
+    """
+    integer(private, "private", 1)
+    if private >= curve.order:
+        raise ValueError("private key must be below generator order")
+    point = multiply(private, curve.generator, curve)
+    assert point is not None
+    return point
+
+
+def enumerate_points(curve: Curve) -> tuple[tuple[int, int], ...]:
+    """List every finite point of a small curve, sorted, by trying each x.
+
+    Adding the point at infinity gives the whole group, so
+    ``len(enumerate_points(curve)) + 1`` is the group order #E. Useful for
+    plotting a toy curve and for checking Hasse's bound by hand.
+
+    Raises
+    ------
+    ValueError
+        The field has more than 10,000 elements; enumeration is O(p).
+
+    Examples
+    --------
+    >>> from blockchainkit.crypto import TOY_CURVE, enumerate_points
+    >>> len(enumerate_points(TOY_CURVE)) + 1 == TOY_CURVE.order
+    True
+    """
+    if curve.p > 10_000:
+        raise ValueError("enumeration is only for small curves (p <= 10000)")
+    roots: dict[int, list[int]] = {}
+    for y in range(curve.p):
+        roots.setdefault(y * y % curve.p, []).append(y)
+    return tuple(
+        (x, y)
+        for x in range(curve.p)
+        for y in roots.get((x**3 + curve.a * x + curve.b) % curve.p, ())
+    )
+
+
+def encode_point(point: Point, curve: Curve = SECP256K1) -> bytes:
+    """Return fixed-width uncompressed encoding (0x04 || x || y)."""
+    if point is None or not curve.contains(point):
+        raise ValueError("expected a finite on-curve point")
+    width = (curve.p.bit_length() + 7) // 8
+    return b"\x04" + point[0].to_bytes(width, "big") + point[1].to_bytes(width, "big")

blockchainkit/crypto/systems/discrete_log.py

@@ -0,0 +1,156 @@
+"""Generic discrete-logarithm algorithms: why group size and structure matter.
+
+Baby-step giant-step (Shanks 1971) solves base**x = target in any cyclic
+group of order n with about 2*sqrt(n) multiplications. Pohlig-Hellman (1978)
+splits the problem along the prime factors of n, so its cost is governed by
+the *largest prime factor*, not by n. Together they explain why
+Diffie-Hellman and Schnorr work in a subgroup of large prime order.
+"""
+
+from math import isqrt
+
+from blockchainkit._validation import integer
+from blockchainkit.crypto.core.base import DiscreteLogResult
+from blockchainkit.crypto.utils.primes import is_prime
+
+_TRIAL_DIVISION_BOUND = 2**20
+
+
+def _check(base: int, target: int, modulus: int, order: int) -> None:
+    for value, name in ((base, "base"), (target, "target")):
+        integer(value, name, 1)
+    integer(modulus, "modulus", 3)
+    integer(order, "order", 1)
+    if base >= modulus or target >= modulus:
+        raise ValueError("base and target must be reduced modulo the modulus")
+    if pow(base, order, modulus) != 1:
+        raise ValueError("base**order must be 1 modulo the modulus")
+
+
+def _bsgs(base: int, target: int, modulus: int, order: int) -> tuple[int, int]:
+    m = isqrt(order - 1) + 1 if order > 1 else 1
+    baby: dict[int, int] = {}
+    value = 1
+    for j in range(m):
+        baby.setdefault(value, j)
+        value = value * base % modulus
+    giant_step = pow(base, -m, modulus)
+    gamma = target
+    for i in range(m):
+        if gamma in baby:
+            return (i * m + baby[gamma]) % order, m + i + 1
+        gamma = gamma * giant_step % modulus
+    raise ValueError("target is not a power of base")
+
+
+def baby_step_giant_step(base: int, target: int, modulus: int, order: int) -> DiscreteLogResult:
+    """Solve ``base**x = target (mod modulus)`` in about ``2*sqrt(order)`` steps.
+
+    Writing ``x = i*m + j`` with ``m = ceil(sqrt(order))``, a table of baby
+    steps ``base**j`` is matched against giant steps ``target * base**(-i*m)``.
+
+    Parameters
+    ----------
+    base : int
+        A group element whose order divides ``order``.
+    target : int
+        The element whose logarithm is wanted.
+    modulus : int
+        The modulus of the multiplicative group.
+    order : int
+        A multiple of the order of ``base`` (the subgroup order).
+
+    Returns
+    -------
+    DiscreteLogResult
+        The exponent and the number of table multiplications.
+
+    Raises
+    ------
+    ValueError
+        ``target`` is not a power of ``base``.
+
+    Examples
+    --------
+    >>> from blockchainkit.crypto import baby_step_giant_step
+    >>> baby_step_giant_step(2, pow(2, 77, 1019), 1019, 1018).exponent
+    77
+    """
+    _check(base, target, modulus, order)
+    exponent, steps = _bsgs(base, target, modulus, order)
+    return DiscreteLogResult(exponent, steps)
+
+
+def factor_order(n: int) -> dict[int, int]:
+    """Factor a group order by trial division up to 2**20.
+
+    A cofactor left over after trial division must itself be prime, which
+    is all Pohlig-Hellman needs; otherwise the order is rejected.
+
+    >>> from blockchainkit.crypto.systems.discrete_log import factor_order
+    >>> factor_order(8100)
+    {2: 2, 3: 4, 5: 2}
+    """
+    integer(n, "n", 1)
+    factors: dict[int, int] = {}
+    d = 2
+    while d * d <= n and d <= _TRIAL_DIVISION_BOUND:
+        while n % d == 0:
+            factors[d] = factors.get(d, 0) + 1
+            n //= d
+        d += 1 if d == 2 else 2
+    if n > 1:
+        if n >= 2**64 or not is_prime(n):
+            raise ValueError("cannot factor the order by trial division")
+        factors[n] = factors.get(n, 0) + 1
+    return factors
+
+
+def pohlig_hellman(base: int, target: int, modulus: int, order: int) -> DiscreteLogResult:
+    """Solve a discrete log by splitting the group order into prime powers.
+
+    For each prime power ``p**e`` dividing ``order``, the problem is mapped
+    into the subgroup of order ``p**e`` and solved one base-``p`` digit at a
+    time with baby-step giant-step in a subgroup of order ``p``. The Chinese
+    Remainder Theorem combines the answers. The cost is about
+    ``sum(e * sqrt(p))``, tiny when every prime factor is small.
+
+    Parameters and return value are as for :func:`baby_step_giant_step`.
+
+    Examples
+    --------
+    >>> from blockchainkit.crypto import pohlig_hellman
+    >>> pohlig_hellman(6, pow(6, 4321, 8101), 8101, 8100).exponent
+    4321
+    """
+    _check(base, target, modulus, order)
+    # Reduce the given multiple to the exact order of base, prime by prime;
+    # otherwise a prime-power subproblem can have a trivial generator.
+    factors = factor_order(order)
+    for prime in factors:
+        while factors[prime] and pow(base, order // prime, modulus) == 1:
+            order //= prime
+            factors[prime] -= 1
+    residues, moduli, operations = [], [], 0
+    for prime, power in factors.items():
+        if power == 0:
+            continue
+        cofactor = order // prime**power
+        g = pow(base, cofactor, modulus)  # Order divides prime**power.
+        h = pow(target, cofactor, modulus)
+        generator = pow(g, prime ** (power - 1), modulus)  # Order divides prime.
+        digits = 0
+        for k in range(power):
+            # Strip the digits found so far, then project onto the order-p subgroup.
+            residual = h * pow(g, -digits, modulus) % modulus
+            projected = pow(residual, prime ** (power - 1 - k), modulus)
+            digit, steps = _bsgs(generator, projected, modulus, prime)
+            operations += steps
+            digits += digit * prime**k
+        residues.append(digits)
+        moduli.append(prime**power)
+    exponent = 0
+    for residue, m in zip(residues, moduli, strict=True):
+        rest = order // m
+        exponent += residue * rest * pow(rest, -1, m)
+    return DiscreteLogResult(exponent % order, operations)

blockchainkit/crypto/systems/hashing.py

@@ -0,0 +1,95 @@
+"""SHA-256 hashing, bit-level digest comparison, and birthday collisions."""
+
+import hashlib
+
+from blockchainkit._validation import integer
+from blockchainkit.crypto.core.base import CollisionResult
+
+
+def sha256(data: bytes) -> bytes:
+    """Return the 32-byte SHA-256 digest of bytes.
+
+    >>> from blockchainkit.crypto import sha256
+    >>> sha256(b"abc").hex()
+    'ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad'
+    """
+    if not isinstance(data, bytes):
+        raise TypeError("data must be bytes; encode text explicitly")
+    return hashlib.sha256(data).digest()
+
+
+def hash256(data: bytes) -> bytes:
+    """Return SHA-256(SHA-256(data)), as used in Bitcoin hashing."""
+    return sha256(sha256(data))
+
+
+def hamming_distance(left: bytes, right: bytes) -> int:
+    """Count differing bits between equally long byte strings.
+
+    >>> from blockchainkit.crypto import hamming_distance
+    >>> hamming_distance(bytes([0]), bytes([7]))
+    3
+    """
+    if len(left) != len(right):
+        raise ValueError("inputs must have equal length")
+    return sum((a ^ b).bit_count() for a, b in zip(left, right, strict=True))
+
+
+def truncated_hash(data: bytes, bits: int) -> int:
+    """Return the top ``bits`` bits of SHA-256(data) as an integer.
+
+    Truncation makes collisions findable, to measure the birthday bound.
+
+    >>> from blockchainkit.crypto import truncated_hash
+    >>> truncated_hash(b"abc", 8) == sha256(b"abc")[0]
+    True
+    """
+    integer(bits, "bits", 1)
+    if bits > 256:
+        raise ValueError("bits cannot exceed 256")
+    return int.from_bytes(sha256(data), "big") >> (256 - bits)
+
+
+def find_collision(bits: int, *, prefix: bytes = b"", max_trials: int = 1 << 22) -> CollisionResult:
+    """Find two inputs whose ``bits``-bit truncated hashes agree.
+
+    Hashes ``prefix + counter`` for counter = 0, 1, 2, ... and remembers every
+    truncated digest. By the birthday paradox a repeat is expected after
+    about ``sqrt(pi/2 * 2**bits)`` trials, far fewer than the ``2**bits``
+    needed to hit one *given* digest (Yuval, 1979).
+
+    Parameters
+    ----------
+    bits : int
+        Output size to attack, between 1 and 48.
+    prefix : bytes
+        Shared prefix of every candidate input.
+    max_trials : int
+        Search bound.
+
+    Raises
+    ------
+    TimeoutError
+        No collision within ``max_trials``.
+
+    Examples
+    --------
+    >>> from blockchainkit.crypto import find_collision
+    >>> result = find_collision(16)
+    >>> result.first != result.second, result.trials < 2**10
+    (True, True)
+    """
+    integer(bits, "bits", 1)
+    if bits > 48:
+        raise ValueError("bits must be at most 48 to keep the search bounded")
+    integer(max_trials, "max_trials", 1)
+    if not isinstance(prefix, bytes):
+        raise TypeError("prefix must be bytes")
+    seen: dict[int, bytes] = {}
+    for counter in range(max_trials):
+        candidate = prefix + counter.to_bytes(8, "big")
+        digest = truncated_hash(candidate, bits)
+        if digest in seen:
+            return CollisionResult(seen[digest], candidate, digest, counter + 1)
+        seen[digest] = candidate
+    raise TimeoutError(f"no {bits}-bit collision in {max_trials} trials")

blockchainkit/crypto/systems/lamport.py

@@ -0,0 +1,65 @@
+"""Lamport one-time signatures (1979): signatures from a hash function alone.
+
+The private key is 256 pairs of random preimages; the public key is their
+hashes. To sign, hash the message and, for each digest bit, reveal the
+preimage for that bit's value. Verification hashes each revealed preimage.
+Each signature reveals half the private key, so a key must sign only once.
+Security rests only on the hash being one-way, so the scheme survives
+quantum computers, and its descendants (XMSS, SPHINCS+) are standardized.
+"""
+
+import hmac
+
+from blockchainkit.constants import LAMPORT_DOMAIN
+from blockchainkit.crypto.core.base import LamportKeyPair
+from blockchainkit.crypto.systems.hashing import sha256
+
+
+def _bits(message: bytes) -> list[int]:
+    digest = int.from_bytes(sha256(message), "big")
+    return [(digest >> (255 - i)) & 1 for i in range(256)]
+
+
+def lamport_keypair(seed: bytes) -> LamportKeyPair:
+    """Derive a one-time key pair deterministically from a secret seed.
+
+    Each private preimage is SHA-256(domain || seed || index || bit). A real
+    seed must be at least 32 random bytes and never reused.
+
+    >>> from blockchainkit.crypto import lamport_keypair
+    >>> len(lamport_keypair(b"seed").public)
+    256
+    """
+    if not isinstance(seed, bytes):
+        raise TypeError("seed must be bytes")
+    pairs = []
+    for i in range(256):
+        prefix = LAMPORT_DOMAIN + seed + i.to_bytes(2, "big")
+        pairs.append((sha256(prefix + b"\x00"), sha256(prefix + b"\x01")))
+    public = tuple((sha256(zero), sha256(one)) for zero, one in pairs)
+    return LamportKeyPair(tuple(pairs), public)
+
+
+def lamport_sign(message: bytes, key: LamportKeyPair) -> tuple[bytes, ...]:
+    """Reveal, for each bit of SHA-256(message), the matching private preimage."""
+    if not isinstance(message, bytes):
+        raise TypeError("message must be bytes")
+    return tuple(pair[bit] for pair, bit in zip(key.private, _bits(message), strict=True))
+
+
+def lamport_verify(
+    message: bytes, signature: tuple[bytes, ...], public: tuple[tuple[bytes, bytes], ...]
+) -> bool:
+    """Check that each revealed preimage hashes to the public value for its bit.
+
+    >>> from blockchainkit.crypto import lamport_keypair, lamport_sign, lamport_verify
+    >>> key = lamport_keypair(b"seed")
+    >>> lamport_verify(b"hello", lamport_sign(b"hello", key), key.public)
+    True
+    """
+    if not isinstance(message, bytes) or len(signature) != 256 or len(public) != 256:
+        return False
+    return all(
+        isinstance(revealed, bytes) and hmac.compare_digest(sha256(revealed), pair[bit])
+        for revealed, pair, bit in zip(signature, public, _bits(message), strict=True)
+    )

blockchainkit/crypto/systems/mac.py

@@ -0,0 +1,34 @@
+"""Message authentication codes: the naive secret-prefix hash, and HMAC (1996)."""
+
+import hashlib
+import hmac
+
+from blockchainkit.crypto.systems.hashing import sha256
+
+
+def naive_mac(key: bytes, message: bytes) -> bytes:
+    """Return SHA-256(key || message): a tempting MAC that is *broken*.
+
+    Anyone holding a tag can forge the tag of ``message || glue || suffix``
+    with :func:`~blockchainkit.crypto.systems.merkle_damgard.length_extension`.
+    Shown for contrast with :func:`hmac_sha256`; never use it.
+    """
+    if not isinstance(key, bytes) or not isinstance(message, bytes):
+        raise TypeError("key and message must be bytes")
+    return sha256(key + message)
+
+
+def hmac_sha256(key: bytes, message: bytes) -> bytes:
+    """Return HMAC-SHA256(key, message) (Bellare, Canetti and Krawczyk, 1996).
+
+    HMAC hashes twice with two derived keys,
+    ``H((k XOR opad) || H((k XOR ipad) || m))``. The outer hash hides the
+    inner chaining state, so length extension no longer works.
+
+    >>> from blockchainkit.crypto import hmac_sha256
+    >>> hmac_sha256(b"key", b"The quick brown fox jumps over the lazy dog").hex()[:16]
+    'f7bc83f430538424'
+    """
+    if not isinstance(key, bytes) or not isinstance(message, bytes):
+        raise TypeError("key and message must be bytes")
+    return hmac.new(key, message, hashlib.sha256).digest()