blockchainkit 0.2.0__py3-none-any.whl

blockchainkit/crypto/systems/merkle_damgard.py

@@ -0,0 +1,139 @@
+"""SHA-256 written out as a Merkle-Damgard iteration, and its length-extension flaw.
+
+Merkle and Damgard (1989) showed how to hash messages of any length with a
+fixed-size compression function: pad the message to whole blocks, ending with
+its length, then chain ``state = compress(state, block)`` from a fixed initial
+value. The digest *is* the final state. So anyone who knows ``H(m)`` and
+``len(m)`` can keep compressing from it and compute ``H(m || pad || suffix)``
+without knowing ``m``: the length-extension attack. HMAC exists to stop it.
+
+This is a readable implementation for study. Use :func:`hashlib.sha256` (or
+:func:`blockchainkit.crypto.systems.hashing.sha256`) for real hashing.
+"""
+
+from blockchainkit._validation import integer
+
+SHA256_IV = (
+    0x6A09E667,
+    0xBB67AE85,
+    0x3C6EF372,
+    0xA54FF53A,
+    0x510E527F,
+    0x9B05688C,
+    0x1F83D9AB,
+    0x5BE0CD19,
+)
+"""tuple of int: The initial chaining value (FIPS 180-4, section 5.3.3)."""
+
+# Round constants: the first 32 bits of the fractional parts of the cube
+# roots of the first 64 primes (FIPS 180-4, section 4.2.2).
+_K = (
+    0x428A2F98, 0x71374491, 0xB5C0FBCF, 0xE9B5DBA5, 0x3956C25B, 0x59F111F1, 0x923F82A4, 0xAB1C5ED5,
+    0xD807AA98, 0x12835B01, 0x243185BE, 0x550C7DC3, 0x72BE5D74, 0x80DEB1FE, 0x9BDC06A7, 0xC19BF174,
+    0xE49B69C1, 0xEFBE4786, 0x0FC19DC6, 0x240CA1CC, 0x2DE92C6F, 0x4A7484AA, 0x5CB0A9DC, 0x76F988DA,
+    0x983E5152, 0xA831C66D, 0xB00327C8, 0xBF597FC7, 0xC6E00BF3, 0xD5A79147, 0x06CA6351, 0x14292967,
+    0x27B70A85, 0x2E1B2138, 0x4D2C6DFC, 0x53380D13, 0x650A7354, 0x766A0ABB, 0x81C2C92E, 0x92722C85,
+    0xA2BFE8A1, 0xA81A664B, 0xC24B8B70, 0xC76C51A3, 0xD192E819, 0xD6990624, 0xF40E3585, 0x106AA070,
+    0x19A4C116, 0x1E376C08, 0x2748774C, 0x34B0BCB5, 0x391C0CB3, 0x4ED8AA4A, 0x5B9CCA4F, 0x682E6FF3,
+    0x748F82EE, 0x78A5636F, 0x84C87814, 0x8CC70208, 0x90BEFFFA, 0xA4506CEB, 0xBEF9A3F7, 0xC67178F2,
+)  # fmt: skip
+_MASK = 0xFFFFFFFF
+
+
+def _rotr(x: int, n: int) -> int:
+    return ((x >> n) | (x << (32 - n))) & _MASK
+
+
+def sha256_compress(state: tuple[int, ...], block: bytes) -> tuple[int, ...]:
+    """Apply SHA-256's compression function to one 64-byte block.
+
+    Parameters
+    ----------
+    state : tuple of int
+        Eight 32-bit words: :data:`SHA256_IV` or the previous output.
+    block : bytes
+        Exactly 64 bytes.
+
+    Returns
+    -------
+    tuple of int
+        The next chaining state.
+    """
+    if not isinstance(block, bytes) or len(block) != 64:
+        raise ValueError("a SHA-256 block is 64 bytes")
+    if len(state) != 8:
+        raise ValueError("a SHA-256 state is eight 32-bit words")
+    w = [int.from_bytes(block[4 * i : 4 * i + 4], "big") for i in range(16)]
+    for i in range(16, 64):
+        s0 = _rotr(w[i - 15], 7) ^ _rotr(w[i - 15], 18) ^ (w[i - 15] >> 3)
+        s1 = _rotr(w[i - 2], 17) ^ _rotr(w[i - 2], 19) ^ (w[i - 2] >> 10)
+        w.append((w[i - 16] + s0 + w[i - 7] + s1) & _MASK)
+    a, b, c, d, e, f, g, h = state
+    for i in range(64):
+        t1 = h + (_rotr(e, 6) ^ _rotr(e, 11) ^ _rotr(e, 25)) + ((e & f) ^ (~e & g)) + _K[i] + w[i]
+        t2 = (_rotr(a, 2) ^ _rotr(a, 13) ^ _rotr(a, 22)) + ((a & b) ^ (a & c) ^ (b & c))
+        a, b, c, d, e, f, g, h = (t1 + t2) & _MASK, a, b, c, (d + t1) & _MASK, e, f, g
+    return tuple((x + y) & _MASK for x, y in zip(state, (a, b, c, d, e, f, g, h), strict=True))
+
+
+def sha256_padding(message_length: int) -> bytes:
+    """Return the Merkle-Damgard strengthening for a message of that many bytes.
+
+    A 0x80 byte, zeros up to 56 bytes modulo 64, then the bit length as a
+    64-bit big-endian integer. Encoding the length is what makes the
+    construction collision-resistant whenever the compression function is.
+    """
+    integer(message_length, "message_length")
+    zeros = (55 - message_length) % 64
+    return b"\x80" + bytes(zeros) + (8 * message_length).to_bytes(8, "big")
+
+
+def _iterate(state: tuple[int, ...], data: bytes) -> tuple[int, ...]:
+    for start in range(0, len(data), 64):
+        state = sha256_compress(state, data[start : start + 64])
+    return state
+
+
+def _digest(state: tuple[int, ...]) -> bytes:
+    return b"".join(word.to_bytes(4, "big") for word in state)
+
+
+def merkle_damgard_sha256(data: bytes) -> bytes:
+    """Hash by padding, then chaining the compression function from the IV.
+
+    >>> import hashlib
+    >>> from blockchainkit.crypto import merkle_damgard_sha256
+    >>> merkle_damgard_sha256(b"abc") == hashlib.sha256(b"abc").digest()
+    True
+    """
+    if not isinstance(data, bytes):
+        raise TypeError("data must be bytes")
+    return _digest(_iterate(SHA256_IV, data + sha256_padding(len(data))))
+
+
+def length_extension(digest: bytes, original_length: int, suffix: bytes) -> tuple[bytes, bytes]:
+    """Extend ``H(original)`` to ``H(original || glue || suffix)`` without knowing ``original``.
+
+    Parameters
+    ----------
+    digest : bytes
+        SHA-256 of the unknown original message.
+    original_length : int
+        Its length in bytes (for a secret-prefix MAC, key plus message).
+    suffix : bytes
+        Data the attacker wants to append.
+
+    Returns
+    -------
+    tuple of bytes
+        ``(glue, forged)``: the original message's padding, which becomes
+        part of the forged message, and ``SHA-256(original || glue || suffix)``.
+    """
+    if not isinstance(digest, bytes) or len(digest) != 32:
+        raise ValueError("a SHA-256 digest is 32 bytes")
+    if not isinstance(suffix, bytes):
+        raise TypeError("suffix must be bytes")
+    glue = sha256_padding(original_length)
+    state = tuple(int.from_bytes(digest[4 * i : 4 * i + 4], "big") for i in range(8))
+    total = original_length + len(glue) + len(suffix)
+    return glue, _digest(_iterate(state, suffix + sha256_padding(total)))

blockchainkit/crypto/systems/multisig.py

@@ -0,0 +1,98 @@
+"""MuSig key aggregation (Maxwell, Poelstra, Seurin and Wuille, 2018).
+
+Schnorr signatures add: if every signer uses nonce k_i and key x_i, the sum
+of their responses is a valid signature for the *sum* of their public keys.
+Summing keys naively is unsafe: an attacker who announces
+``Q_rogue = xG - Q_honest`` makes the sum equal ``xG``, a key they control
+alone. MuSig weights each key by ``a_i = H(L, Q_i)``, a hash of the whole
+key list L, so no participant can choose their key to cancel the others.
+
+Teaching simplification: :func:`musig_sign` plays every signer in one
+process. Real MuSig exchanges nonce commitments first (or uses MuSig2's two
+nonces); without that round, a malicious co-signer can bias the joint nonce.
+"""
+
+from collections.abc import Sequence
+
+from blockchainkit._validation import integer
+from blockchainkit.constants import MUSIG_DOMAIN
+from blockchainkit.crypto.core.base import SchnorrSignature
+from blockchainkit.crypto.systems.curves import (
+    SECP256K1,
+    Curve,
+    add,
+    encode_point,
+    multiply,
+    public_key,
+)
+from blockchainkit.crypto.systems.hashing import sha256
+from blockchainkit.crypto.systems.signatures import challenge
+
+
+def musig_coefficients(
+    publics: Sequence[tuple[int, int]], curve: Curve = SECP256K1
+) -> tuple[int, ...]:
+    """Return ``a_i = H(L || Q_i) mod n`` for each key, with L the encoded key list."""
+    if not publics:
+        raise ValueError("need at least one public key")
+    key_list = b"".join(encode_point(q, curve) for q in publics)
+    return tuple(
+        int.from_bytes(sha256(MUSIG_DOMAIN + key_list + encode_point(q, curve)), "big")
+        % curve.order
+        for q in publics
+    )
+
+
+def aggregate_public_keys(
+    publics: Sequence[tuple[int, int]], curve: Curve = SECP256K1
+) -> tuple[int, int]:
+    """Return the MuSig aggregate key ``sum(a_i * Q_i)``.
+
+    >>> from blockchainkit.crypto import aggregate_public_keys, public_key
+    >>> len(aggregate_public_keys([public_key(3), public_key(5)]))
+    2
+    """
+    total = None
+    for a, q in zip(musig_coefficients(publics, curve), publics, strict=True):
+        total = add(total, multiply(a, q, curve), curve)
+    # A weighted sum of honest keys is the point at infinity only with
+    # negligible probability (a hash would have to cancel the keys exactly).
+    assert total is not None
+    return total
+
+
+def musig_sign(
+    message: bytes,
+    privates: Sequence[int],
+    nonces: Sequence[int],
+    curve: Curve = SECP256K1,
+) -> SchnorrSignature:
+    """Produce one Schnorr signature valid for the aggregate of the signers' keys.
+
+    Each signer i contributes ``R_i = k_i G`` and ``s_i = k_i + c * a_i * x_i``
+    with the shared challenge ``c = H(R, Q_agg, m)``; the signature is
+    ``(sum R_i, sum s_i)`` and verifies with :func:`~blockchainkit.crypto.systems.signatures.verify`
+    against :func:`aggregate_public_keys`.
+
+    Examples
+    --------
+    >>> from blockchainkit.crypto import musig_sign, aggregate_public_keys, public_key, verify
+    >>> signature = musig_sign(b"m", [3, 5], [11, 13])
+    >>> verify(b"m", signature, aggregate_public_keys([public_key(3), public_key(5)]))
+    True
+    """
+    if len(privates) != len(nonces) or not privates:
+        raise ValueError("need one nonce per signer, and at least one signer")
+    for nonce in nonces:
+        integer(nonce, "nonce", 1)
+    publics = [public_key(x, curve) for x in privates]
+    coefficients = musig_coefficients(publics, curve)
+    aggregate = aggregate_public_keys(publics, curve)
+    commitment = None
+    for nonce in nonces:
+        commitment = add(commitment, public_key(nonce, curve), curve)
+    if commitment is None:
+        raise ValueError("the joint nonce is the point at infinity; choose other nonces")
+    c = challenge(message, commitment, aggregate, curve)
+    response = sum(k + c * a * x for k, a, x in zip(nonces, coefficients, privates, strict=True))
+    return SchnorrSignature(commitment, response % curve.order)

blockchainkit/crypto/systems/one_time_pad.py

@@ -0,0 +1,42 @@
+"""The one-time pad (Vernam 1917; Shannon 1949): XOR with a key as long as the message."""
+
+
+def xor_bytes(left: bytes, right: bytes) -> bytes:
+    """Return the bytewise XOR of two equally long byte strings.
+
+    >>> from blockchainkit.crypto import xor_bytes
+    >>> xor_bytes(b"\\x0f", b"\\xff")
+    b'\\xf0'
+    """
+    if not isinstance(left, bytes) or not isinstance(right, bytes):
+        raise TypeError("xor_bytes needs bytes")
+    if len(left) != len(right):
+        raise ValueError("inputs must have equal length")
+    return bytes(a ^ b for a, b in zip(left, right, strict=True))
+
+
+def one_time_pad(message: bytes, key: bytes) -> bytes:
+    """Encrypt or decrypt with a one-time pad: ``message XOR key``.
+
+    The same call decrypts, because XOR is its own inverse. Shannon proved
+    the pad perfectly secret when the key is uniformly random, as long as the
+    message, and never reused: every plaintext of that length is then equally
+    likely given the ciphertext. Reusing a key leaks ``m1 XOR m2``.
+
+    Parameters
+    ----------
+    message : bytes
+        Plaintext (or ciphertext, to decrypt).
+    key : bytes
+        A key exactly as long as the message.
+
+    Examples
+    --------
+    >>> from blockchainkit.crypto import one_time_pad
+    >>> ciphertext = one_time_pad(b"hi", b"\\x01\\x02")
+    >>> one_time_pad(ciphertext, b"\\x01\\x02")
+    b'hi'
+    """
+    if isinstance(message, bytes) and isinstance(key, bytes) and len(key) != len(message):
+        raise ValueError("the key must be exactly as long as the message")
+    return xor_bytes(message, key)

blockchainkit/crypto/systems/puzzles.py

@@ -0,0 +1,96 @@
+"""Merkle's puzzles (1974-1978): key agreement from symmetric primitives alone.
+
+Alice publishes ``count`` puzzles, each a short secret (an identifier and a
+session key) encrypted under a deliberately weak key of ``bits`` bits. Bob
+solves one at random, about ``2**(bits-1)`` trials, and announces only its
+identifier. An eavesdropper does not know which puzzle Bob chose and must
+solve, on average, half of them. With ``count`` near ``2**bits``, honest work
+is linear and the attacker's quadratic: the first public-key idea, with a
+gap that is only polynomial.
+"""
+
+import secrets
+from collections.abc import Callable
+
+from blockchainkit._validation import integer
+from blockchainkit.constants import PUZZLE_DOMAIN, PUZZLE_MAGIC
+from blockchainkit.crypto.core.base import PuzzleSolution
+from blockchainkit.crypto.systems.hashing import sha256
+from blockchainkit.crypto.systems.one_time_pad import xor_bytes
+
+_MAX_BITS = 24
+
+
+def _keystream(weak_key: int) -> bytes:
+    return sha256(PUZZLE_DOMAIN + weak_key.to_bytes(8, "big"))
+
+
+def merkle_puzzles(
+    count: int,
+    bits: int,
+    *,
+    randbits: Callable[[int], int] = secrets.randbits,
+) -> tuple[tuple[bytes, ...], dict[bytes, bytes]]:
+    """Create Alice's puzzles and her private table of identifiers to keys.
+
+    Parameters
+    ----------
+    count : int
+        Number of puzzles to publish.
+    bits : int
+        Size of each weak key, between 1 and 24; solving takes up to
+        ``2**bits`` trials.
+    randbits : callable
+        Randomness source; inject ``random.Random(seed).getrandbits`` only
+        for reproducible experiments.
+
+    Returns
+    -------
+    tuple
+        ``(puzzles, table)``: 32-byte puzzles to publish, and the mapping
+        from each 8-byte identifier to its 16-byte session key.
+    """
+    integer(count, "count", 1)
+    integer(bits, "bits", 1)
+    if bits > _MAX_BITS:
+        raise ValueError(f"bits must be at most {_MAX_BITS} to keep solving bounded")
+    puzzles, table = [], {}
+    for _ in range(count):
+        puzzle_id = randbits(64).to_bytes(8, "big")
+        key = randbits(128).to_bytes(16, "big")
+        weak_key = randbits(bits)
+        puzzles.append(xor_bytes(PUZZLE_MAGIC + puzzle_id + key, _keystream(weak_key)))
+        table[puzzle_id] = key
+    return tuple(puzzles), table
+
+
+def solve_puzzle(puzzle: bytes, bits: int) -> PuzzleSolution:
+    """Open a puzzle by brute force over every weak key.
+
+    A trial succeeds when the decrypted plaintext starts with the known
+    marker, ``PUZZLE_MAGIC``.
+
+    Raises
+    ------
+    ValueError
+        No weak key of that size opens the puzzle.
+
+    Examples
+    --------
+    >>> from random import Random
+    >>> from blockchainkit.crypto import merkle_puzzles, solve_puzzle
+    >>> puzzles, table = merkle_puzzles(3, 6, randbits=Random(1).getrandbits)
+    >>> solution = solve_puzzle(puzzles[0], bits=6)
+    >>> table[solution.puzzle_id] == solution.key
+    True
+    """
+    if not isinstance(puzzle, bytes) or len(puzzle) != 32:
+        raise ValueError("a puzzle is 32 bytes")
+    integer(bits, "bits", 1)
+    if bits > _MAX_BITS:
+        raise ValueError(f"bits must be at most {_MAX_BITS} to keep solving bounded")
+    for weak_key in range(2**bits):
+        plaintext = xor_bytes(puzzle, _keystream(weak_key))
+        if plaintext.startswith(PUZZLE_MAGIC):
+            return PuzzleSolution(plaintext[8:16], plaintext[16:], weak_key + 1)
+    raise ValueError("no weak key of that size opens this puzzle")

blockchainkit/crypto/systems/sharing.py

@@ -0,0 +1,159 @@
+"""Threshold secret sharing: Shamir (1979) and Feldman's verifiable variant (1987)."""
+
+import secrets
+from collections.abc import Callable, Sequence
+
+from blockchainkit._validation import integer
+from blockchainkit.crypto.core.base import FeldmanShares
+from blockchainkit.crypto.systems.asymmetric import TEACHING_GROUP, DHGroup
+from blockchainkit.crypto.utils.primes import is_prime
+
+
+def split_secret(
+    secret: int,
+    threshold: int,
+    shares: int,
+    prime: int = 2089,
+    *,
+    randbelow: Callable[[int], int] = secrets.randbelow,
+) -> tuple[tuple[int, int], ...]:
+    """Sample a polynomial with constant term ``secret`` and return its shares.
+
+    Parameters
+    ----------
+    secret : int
+        Field element in [0, prime).
+    threshold : int
+        Number of shares needed, between 2 and shares.
+    shares : int
+        Number of distinct nonzero evaluation points, below prime.
+    prime : int
+        Prime field modulus below 2**64.
+    randbelow : callable
+        Uniform randomness source. Inject ``random.Random(seed).randrange``
+        only for reproducible teaching experiments.
+
+    Returns
+    -------
+    tuple
+        (x, y) pairs at x = 1, ..., shares.
+    """
+    if not is_prime(prime):
+        raise ValueError("need a prime modulus below 2**64")
+    coefficients = _sample_polynomial(secret, threshold, shares, prime, randbelow)
+    return _evaluate(coefficients, shares, prime)
+
+
+def _sample_polynomial(
+    secret: int, threshold: int, shares: int, prime: int, randbelow: Callable[[int], int]
+) -> list[int]:
+    integer(secret, "secret")
+    integer(threshold, "threshold", 2)
+    integer(shares, "shares", threshold)
+    if secret >= prime or shares >= prime:
+        raise ValueError("need secret < prime and shares < prime")
+    coefficients = [secret]
+    for _ in range(threshold - 1):
+        coefficient = randbelow(prime)
+        integer(coefficient, "random coefficient")
+        if coefficient >= prime:
+            raise ValueError("randbelow returned a value outside the field")
+        coefficients.append(coefficient)
+    # Coefficients, including the leading one, may be zero. Sampling every
+    # polynomial with this constant term uniformly is what makes any
+    # threshold - 1 shares independent of the secret (perfect secrecy).
+    return coefficients
+
+
+def _evaluate(coefficients: list[int], shares: int, prime: int) -> tuple[tuple[int, int], ...]:
+    return tuple(
+        (x, sum(c * pow(x, i, prime) for i, c in enumerate(coefficients)) % prime)
+        for x in range(1, shares + 1)
+    )
+
+
+def feldman_split(
+    secret: int,
+    threshold: int,
+    shares: int,
+    group: DHGroup = TEACHING_GROUP,
+    *,
+    randbelow: Callable[[int], int] = secrets.randbelow,
+) -> FeldmanShares:
+    """Shamir-share a secret modulo the group order, and publish ``g**a_j``.
+
+    Each commitment hides one polynomial coefficient in the exponent. A share
+    holder checks ``g**y == prod(C_j**(x**j))``, which holds exactly when
+    their share lies on the committed polynomial, so a cheating dealer is
+    caught without anyone learning the secret. The commitment ``g**secret``
+    is public, so the secret is only computationally hidden.
+
+    Parameters
+    ----------
+    secret : int
+        Element of the integers modulo the group order q.
+    threshold, shares : int
+        As for :func:`split_secret`.
+    group : DHGroup
+        Prime-order group; shares live modulo its order q.
+    randbelow : callable
+        Uniform randomness source.
+
+    Returns
+    -------
+    FeldmanShares
+        The shares and the public coefficient commitments.
+
+    Examples
+    --------
+    >>> from random import Random
+    >>> from blockchainkit.crypto import feldman_split, feldman_verify, TEACHING_GROUP
+    >>> dealt = feldman_split(42, 2, 3, randbelow=Random(0).randrange)
+    >>> all(feldman_verify(share, dealt.commitments) for share in dealt.shares)
+    True
+    """
+    coefficients = _sample_polynomial(secret, threshold, shares, group.q, randbelow)
+    commitments = tuple(pow(group.g, a, group.p) for a in coefficients)
+    return FeldmanShares(_evaluate(coefficients, shares, group.q), commitments)
+
+
+def feldman_verify(
+    share: tuple[int, int], commitments: Sequence[int], group: DHGroup = TEACHING_GROUP
+) -> bool:
+    """Check one share against the dealer's public commitments."""
+    x, y = share
+    if type(x) is not int or type(y) is not int or not 0 < x < group.q or not 0 <= y < group.q:
+        return False
+    expected = 1
+    for j, commitment in enumerate(commitments):
+        expected = expected * pow(commitment, pow(x, j, group.q), group.p) % group.p
+    return pow(group.g, y, group.p) == expected
+
+
+def recover_secret(shares: Sequence[tuple[int, int]], prime: int = 2089) -> int:
+    """Interpolate at x=0 using Lagrange coefficients.
+
+    The caller must supply enough authentic shares. Without commitments,
+    this function cannot detect too few shares or a malicious participant.
+
+    >>> from blockchainkit.crypto import recover_secret
+    >>> recover_secret([(1, 8), (2, 11)], prime=17)
+    5
+    """
+    if not shares or not is_prime(prime):
+        raise ValueError("need shares and a prime modulus below 2**64")
+    for x, y in shares:
+        integer(x, "x", 1)
+        integer(y, "y")
+        if x >= prime or y >= prime:
+            raise ValueError("share coordinates must be field elements")
+    if len({x for x, _ in shares}) != len(shares):
+        raise ValueError("share x coordinates must be distinct")
+    result = 0
+    for i, (xi, yi) in enumerate(shares):
+        weight = 1
+        for j, (xj, _) in enumerate(shares):
+            if i != j:
+                weight = weight * (-xj) * pow(xi - xj, -1, prime) % prime
+        result = (result + yi * weight) % prime
+    return result