crypto-gu 0.1.0__tar.gz

crypto_gu-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TSVMV
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

crypto_gu-0.1.0/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: crypto-gu
+Version: 0.1.0
+Summary: Pure standard-library cryptography toolkit: RFC/NIST-verified primitives plus deterministic attack implementations for research and teaching.
+Author: TSVMV
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/TSVMV/crypto-gu
+Keywords: cryptography,teaching,research,aes,chacha20,poly1305,gcm,blake2,scrypt,rsa,oaep,pss
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: oracle
+Requires-Dist: cryptography>=41; extra == "oracle"
+Requires-Dist: pycryptodome>=3.19; extra == "oracle"
+Dynamic: license-file
+
+# crypto-gu
+
+面向密码学研究者与教学的纯标准库工具箱。生产形态的原语（哈希、KDF、分组与流密码、AEAD、RSA 填充方案）与确定性攻击实现放在同一个内核里，每个原语均以 RFC / NIST 权威测试向量验证。
+
+## 设计原则
+
+- 仅依赖 Python 标准库，零第三方依赖，Python >= 3.11。
+- 每个原语都有权威向量背书；向量取自 RFC / NIST 原文，或由 `hashlib`、OpenSSL、`cryptography`、`pycryptodome` 实测生成，逐条嵌入测试。
+- 攻击层只做确定性恢复（利用结构弱点），不含密钥空间暴力枚举。
+- `constant_time` 模块消除明显的数据依赖分支与提前退出；CPython 无法提供严格的常量时间保证，此处保持诚实定位。
+
+## 模块总览
+
+| 模块 | 内容 |
+| --- | --- |
+| `crypto_gu.hashes` | SHA-1 / SHA-256 / SHA-512、MD5、BLAKE2b / BLAKE2s、HMAC、长度扩展攻击 |
+| `crypto_gu.kdf` | PBKDF2、HKDF（extract / expand）、scrypt |
+| `crypto_gu.symmetric.aes` | AES-128/192/256 分组原语与 ECB / CBC / CFB / OFB / CTR 模式 |
+| `crypto_gu.symmetric.chacha20` | ChaCha20 流密码 |
+| `crypto_gu.symmetric.poly1305` | Poly1305 一次性 MAC |
+| `crypto_gu.symmetric.chacha20poly1305` | ChaCha20-Poly1305 AEAD |
+| `crypto_gu.symmetric.aes_gcm` | AES-GCM AEAD，tag 可截断至 4..16 字节 |
+| `crypto_gu.asymmetric.rsa` | RSA 密钥生成与教科书式原语（配合攻击层做因子恢复） |
+| `crypto_gu.asymmetric.pkcs1` | MGF1、RSAES-OAEP、RSASSA-PSS（RFC 8017） |
+| `crypto_gu.number_theory` | 素性检验、模逆、CRT、Tonelli-Shanks、Pollard rho / p-1、Fermat、BSGS |
+| `crypto_gu.rng.mt19937` | MT19937 生成器与从输出反推内部状态 |
+| `crypto_gu.encoding` / `crypto_gu.padding` | hex / base32/58/64/85、XOR、Morse、BCD；PKCS#7 等填充方案 |
+| `crypto_gu.constant_time` | 无提前退出的比较、无分支 select |
+| `crypto_gu.attacks.aes` | ECB byte-at-a-time、CBC padding oracle |
+| `crypto_gu.attacks.rsa` | Wiener、Fermat、Pollard p-1、共模攻击、Hastad broadcast |
+
+## 快速上手
+
+```python
+# 哈希与 HMAC
+from crypto_gu.hashes import sha256, blake2b
+from crypto_gu.hashes.hmac import hmac_sha256
+
+sha256(b"message").hex()
+blake2b(b"message").hex()
+hmac_sha256(b"key", b"message")
+
+# KDF
+from crypto_gu.kdf import pbkdf2, hkdf, scrypt
+
+pbkdf2(b"password", b"salt", 100000, 32)
+hkdf(b"input key material", 32, salt=b"salt", info=b"ctx")
+scrypt(b"password", b"NaCl", 16384, 8, 1, 64)
+
+# AEAD：密文与认证 tag 拼接返回，认证失败抛 InvalidTagError
+from crypto_gu.symmetric import aes_gcm, chacha20poly1305
+
+key = bytes(range(32))
+nonce = b"\x00" * 12
+sealed = aes_gcm.encrypt(key, nonce, b"payload", b"header")
+aes_gcm.decrypt(key, nonce, sealed, b"header")
+
+one_shot = chacha20poly1305.encrypt(key, nonce, b"payload", b"header")
+chacha20poly1305.decrypt(key, nonce, one_shot, b"header")
+
+# RSA-OAEP / RSA-PSS
+from crypto_gu.asymmetric.rsa import RSAKey
+from crypto_gu.asymmetric import pkcs1
+
+key = RSAKey.generate(2048)
+ciphertext = pkcs1.oaep_encrypt(key, b"secret", "sha256")
+pkcs1.oaep_decrypt(key, ciphertext, "sha256")
+
+signature = pkcs1.pss_sign(key, b"document", "sha256", 32)
+pkcs1.pss_verify_signature(key, b"document", signature, "sha256", 32)
+
+# 攻击研究层（确定性恢复，仅供授权环境实验）
+from crypto_gu.attacks.rsa import wiener, common_modulus
+
+wiener(n, e)  # d 过小时由 (n, e) 恢复私钥
+```
+
+## 验证背书
+
+| 原语 | 权威向量 | 交叉 oracle |
+| --- | --- | --- |
+| AES 分组与 ECB/CBC/CFB/OFB/CTR | FIPS-197、NIST SP 800-38A | OpenSSL CLI |
+| ChaCha20 / Poly1305 / ChaCha20-Poly1305 | RFC 8439 §2.4.2、§2.5.2、§2.8.2 | `cryptography`、`pycryptodome` |
+| AES-GCM（含 96 位外 IV、AAD、截断 tag） | NIST GCM 规范测试用例 1-5 | `cryptography`、`pycryptodome` |
+| SHA-1 / SHA-256 / SHA-512 | FIPS 180-4、RFC 6234 | `hashlib` 全量比对 |
+| MD5 | RFC 1321 | `hashlib` 全量比对 |
+| BLAKE2b / BLAKE2s | RFC 7693 附录 A/B/E | `hashlib`（27 组参数矩阵） |
+| HMAC | RFC 2202、RFC 4231 | `hashlib` / `hmac` 模块 |
+| PBKDF2 | RFC 7914 §11 | `hashlib.pbkdf2_hmac` |
+| HKDF | RFC 5869 A.1-A.3 | RFC 向量逐条嵌入 |
+| scrypt | RFC 7914 §12 全 4 组 | `hashlib.scrypt`（OpenSSL `kdf` 已另行交叉验证） |
+| RSAES-OAEP / RSASSA-PSS | RFC 8017（嵌入固定密钥与密文/签名向量） | `cryptography`、`pycryptodome` 双向 |
+| MT19937 | 参考实现输出序列 | 状态恢复回环 |
+
+## 测试
+
+```bash
+python3 -m unittest discover -s tests -q
+```
+
+当前 214 个测试约 2 分钟跑完；耗时集中在 scrypt（RFC 7914 §12 大参数组）与 CBC padding oracle 攻击测试。测试自带全部向量，不需要任何第三方库；`[oracle]` extra 仅用于自行做交叉验证。
+
+## 局限声明
+
+- 纯 Python 实现面向研究与教学，吞吐量与侧信道防护弱于原生密码库。
+- 生产业务若需绝对性能或形式化侧信道保证，建议叠加成熟原生实现。
+- 攻击层仅限在明确授权的环境中复现教科书级结构弱点，请遵守所在司法辖区的法律法规。

crypto_gu-0.1.0/README.md

@@ -0,0 +1,107 @@
+# crypto-gu
+
+面向密码学研究者与教学的纯标准库工具箱。生产形态的原语（哈希、KDF、分组与流密码、AEAD、RSA 填充方案）与确定性攻击实现放在同一个内核里，每个原语均以 RFC / NIST 权威测试向量验证。
+
+## 设计原则
+
+- 仅依赖 Python 标准库，零第三方依赖，Python >= 3.11。
+- 每个原语都有权威向量背书；向量取自 RFC / NIST 原文，或由 `hashlib`、OpenSSL、`cryptography`、`pycryptodome` 实测生成，逐条嵌入测试。
+- 攻击层只做确定性恢复（利用结构弱点），不含密钥空间暴力枚举。
+- `constant_time` 模块消除明显的数据依赖分支与提前退出；CPython 无法提供严格的常量时间保证，此处保持诚实定位。
+
+## 模块总览
+
+| 模块 | 内容 |
+| --- | --- |
+| `crypto_gu.hashes` | SHA-1 / SHA-256 / SHA-512、MD5、BLAKE2b / BLAKE2s、HMAC、长度扩展攻击 |
+| `crypto_gu.kdf` | PBKDF2、HKDF（extract / expand）、scrypt |
+| `crypto_gu.symmetric.aes` | AES-128/192/256 分组原语与 ECB / CBC / CFB / OFB / CTR 模式 |
+| `crypto_gu.symmetric.chacha20` | ChaCha20 流密码 |
+| `crypto_gu.symmetric.poly1305` | Poly1305 一次性 MAC |
+| `crypto_gu.symmetric.chacha20poly1305` | ChaCha20-Poly1305 AEAD |
+| `crypto_gu.symmetric.aes_gcm` | AES-GCM AEAD，tag 可截断至 4..16 字节 |
+| `crypto_gu.asymmetric.rsa` | RSA 密钥生成与教科书式原语（配合攻击层做因子恢复） |
+| `crypto_gu.asymmetric.pkcs1` | MGF1、RSAES-OAEP、RSASSA-PSS（RFC 8017） |
+| `crypto_gu.number_theory` | 素性检验、模逆、CRT、Tonelli-Shanks、Pollard rho / p-1、Fermat、BSGS |
+| `crypto_gu.rng.mt19937` | MT19937 生成器与从输出反推内部状态 |
+| `crypto_gu.encoding` / `crypto_gu.padding` | hex / base32/58/64/85、XOR、Morse、BCD；PKCS#7 等填充方案 |
+| `crypto_gu.constant_time` | 无提前退出的比较、无分支 select |
+| `crypto_gu.attacks.aes` | ECB byte-at-a-time、CBC padding oracle |
+| `crypto_gu.attacks.rsa` | Wiener、Fermat、Pollard p-1、共模攻击、Hastad broadcast |
+
+## 快速上手
+
+```python
+# 哈希与 HMAC
+from crypto_gu.hashes import sha256, blake2b
+from crypto_gu.hashes.hmac import hmac_sha256
+
+sha256(b"message").hex()
+blake2b(b"message").hex()
+hmac_sha256(b"key", b"message")
+
+# KDF
+from crypto_gu.kdf import pbkdf2, hkdf, scrypt
+
+pbkdf2(b"password", b"salt", 100000, 32)
+hkdf(b"input key material", 32, salt=b"salt", info=b"ctx")
+scrypt(b"password", b"NaCl", 16384, 8, 1, 64)
+
+# AEAD：密文与认证 tag 拼接返回，认证失败抛 InvalidTagError
+from crypto_gu.symmetric import aes_gcm, chacha20poly1305
+
+key = bytes(range(32))
+nonce = b"\x00" * 12
+sealed = aes_gcm.encrypt(key, nonce, b"payload", b"header")
+aes_gcm.decrypt(key, nonce, sealed, b"header")
+
+one_shot = chacha20poly1305.encrypt(key, nonce, b"payload", b"header")
+chacha20poly1305.decrypt(key, nonce, one_shot, b"header")
+
+# RSA-OAEP / RSA-PSS
+from crypto_gu.asymmetric.rsa import RSAKey
+from crypto_gu.asymmetric import pkcs1
+
+key = RSAKey.generate(2048)
+ciphertext = pkcs1.oaep_encrypt(key, b"secret", "sha256")
+pkcs1.oaep_decrypt(key, ciphertext, "sha256")
+
+signature = pkcs1.pss_sign(key, b"document", "sha256", 32)
+pkcs1.pss_verify_signature(key, b"document", signature, "sha256", 32)
+
+# 攻击研究层（确定性恢复，仅供授权环境实验）
+from crypto_gu.attacks.rsa import wiener, common_modulus
+
+wiener(n, e)  # d 过小时由 (n, e) 恢复私钥
+```
+
+## 验证背书
+
+| 原语 | 权威向量 | 交叉 oracle |
+| --- | --- | --- |
+| AES 分组与 ECB/CBC/CFB/OFB/CTR | FIPS-197、NIST SP 800-38A | OpenSSL CLI |
+| ChaCha20 / Poly1305 / ChaCha20-Poly1305 | RFC 8439 §2.4.2、§2.5.2、§2.8.2 | `cryptography`、`pycryptodome` |
+| AES-GCM（含 96 位外 IV、AAD、截断 tag） | NIST GCM 规范测试用例 1-5 | `cryptography`、`pycryptodome` |
+| SHA-1 / SHA-256 / SHA-512 | FIPS 180-4、RFC 6234 | `hashlib` 全量比对 |
+| MD5 | RFC 1321 | `hashlib` 全量比对 |
+| BLAKE2b / BLAKE2s | RFC 7693 附录 A/B/E | `hashlib`（27 组参数矩阵） |
+| HMAC | RFC 2202、RFC 4231 | `hashlib` / `hmac` 模块 |
+| PBKDF2 | RFC 7914 §11 | `hashlib.pbkdf2_hmac` |
+| HKDF | RFC 5869 A.1-A.3 | RFC 向量逐条嵌入 |
+| scrypt | RFC 7914 §12 全 4 组 | `hashlib.scrypt`（OpenSSL `kdf` 已另行交叉验证） |
+| RSAES-OAEP / RSASSA-PSS | RFC 8017（嵌入固定密钥与密文/签名向量） | `cryptography`、`pycryptodome` 双向 |
+| MT19937 | 参考实现输出序列 | 状态恢复回环 |
+
+## 测试
+
+```bash
+python3 -m unittest discover -s tests -q
+```
+
+当前 214 个测试约 2 分钟跑完；耗时集中在 scrypt（RFC 7914 §12 大参数组）与 CBC padding oracle 攻击测试。测试自带全部向量，不需要任何第三方库；`[oracle]` extra 仅用于自行做交叉验证。
+
+## 局限声明
+
+- 纯 Python 实现面向研究与教学，吞吐量与侧信道防护弱于原生密码库。
+- 生产业务若需绝对性能或形式化侧信道保证，建议叠加成熟原生实现。
+- 攻击层仅限在明确授权的环境中复现教科书级结构弱点，请遵守所在司法辖区的法律法规。

crypto_gu-0.1.0/crypto_gu/__init__.py

@@ -0,0 +1,12 @@
+"""crypto_gu: a pure standard-library cryptography toolkit.
+
+Research- and teaching-oriented primitives (hashes, KDFs, ciphers, AEAD,
+RSA padding schemes) alongside deterministic attack implementations
+(padding oracles, small-exponent and factorisation helpers). No third
+party dependencies; every primitive is validated against RFC/NIST test
+vectors.
+"""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

crypto_gu-0.1.0/crypto_gu/asymmetric/pkcs1.py

@@ -0,0 +1,212 @@
+"""RSA encryption and signature schemes from PKCS #1 v2.2 (RFC 8017).
+
+Provides MGF1, RSAES-OAEP (section 7.1) and RSASSA-PSS (section 8.1). The
+underlying trapdoor is the textbook :class:`~crypto_gu.asymmetric.rsa.RSAKey`
+already in this package; these helpers add the randomised, provably related
+padding that turns it into a real-world scheme.
+
+Pure Python, standard library only (``os.urandom`` supplies the randomness).
+"""
+
+from __future__ import annotations
+
+import os
+
+from crypto_gu.errors import DecryptionError, InvalidSignatureError
+from crypto_gu.hashes import HASH_TABLE
+
+
+def _hash_length(hash_name: str) -> int:
+    key = hash_name.lower()
+    if key not in HASH_TABLE:
+        raise ValueError("unknown hash algorithm: %r" % hash_name)
+    return len(HASH_TABLE[key](b""))
+
+
+def _digest(hash_name: str, data: bytes) -> bytes:
+    return HASH_TABLE[hash_name.lower()](data)
+
+
+def _i2osp(value: int, length: int) -> bytes:
+    if value < 0 or value >> (8 * length):
+        raise ValueError("integer too large")
+    return value.to_bytes(length, "big")
+
+
+def _os2ip(data: bytes) -> int:
+    return int.from_bytes(data, "big")
+
+
+def mgf1(seed: bytes, length: int, hash_name: str = "sha256") -> bytes:
+    """Mask generation function MGF1 (RFC 8017 appendix B.2.1)."""
+    if length < 0:
+        raise ValueError("mask length must be non-negative")
+    hlen = _hash_length(hash_name)
+    if length > (1 << 32) * hlen:
+        raise ValueError("mask too long")
+    output = b""
+    counter = 0
+    while len(output) < length:
+        output += _digest(hash_name, seed + counter.to_bytes(4, "big"))
+        counter += 1
+    return output[:length]
+
+
+def _xor(left: bytes, right: bytes) -> bytes:
+    return bytes(a ^ b for a, b in zip(left, right))
+
+
+def _modulus_size(n: int) -> int:
+    return (n.bit_length() + 7) // 8
+
+
+# --------------------------------------------------------------------------- #
+# RSAES-OAEP
+# --------------------------------------------------------------------------- #
+
+
+def oaep_encode(message: bytes, k: int, hash_name: str = "sha256", label: bytes = b"") -> bytes:
+    """EME-OAEP encoding (RFC 8017 section 7.1.1)."""
+    hlen = _hash_length(hash_name)
+    if len(message) > k - 2 * hlen - 2:
+        raise ValueError("message too long for OAEP")
+    lhash = _digest(hash_name, label)
+    ps = b"\x00" * (k - len(message) - 2 * hlen - 2)
+    db = lhash + ps + b"\x01" + message
+    seed = os.urandom(hlen)
+    db_mask = mgf1(seed, k - hlen - 1, hash_name)
+    masked_db = _xor(db, db_mask)
+    seed_mask = mgf1(masked_db, hlen, hash_name)
+    masked_seed = _xor(seed, seed_mask)
+    return b"\x00" + masked_seed + masked_db
+
+
+def oaep_decode(encoded: bytes, k: int, hash_name: str = "sha256", label: bytes = b"") -> bytes:
+    """EME-OAEP decoding; raises :class:`DecryptionError` on malformed input."""
+    hlen = _hash_length(hash_name)
+    if len(encoded) != k or k < 2 * hlen + 2:
+        raise DecryptionError("decryption error")
+    if encoded[0] != 0:
+        raise DecryptionError("decryption error")
+    masked_seed = encoded[1 : 1 + hlen]
+    masked_db = encoded[1 + hlen :]
+    seed = _xor(masked_seed, mgf1(masked_db, hlen, hash_name))
+    db = _xor(masked_db, mgf1(seed, k - hlen - 1, hash_name))
+    if db[:hlen] != _digest(hash_name, label):
+        raise DecryptionError("decryption error")
+    index = hlen
+    while index < len(db) and db[index] == 0:
+        index += 1
+    if index >= len(db) or db[index] != 1:
+        raise DecryptionError("decryption error")
+    return db[index + 1 :]
+
+
+def oaep_encrypt(key, message: bytes, hash_name: str = "sha256", label: bytes = b"") -> bytes:
+    """RSAES-OAEP encrypt with a public (or full) :class:`RSAKey`."""
+    k = _modulus_size(key.n)
+    encoded = oaep_encode(message, k, hash_name, label)
+    m = _os2ip(encoded)
+    if m >= key.n:
+        raise ValueError("encoded message representative out of range")
+    return _i2osp(pow(m, key.e, key.n), k)
+
+
+def oaep_decrypt(key, ciphertext: bytes, hash_name: str = "sha256", label: bytes = b"") -> bytes:
+    """RSAES-OAEP decrypt; requires the private exponent."""
+    if key.d is None:
+        raise DecryptionError("decryption error")
+    k = _modulus_size(key.n)
+    if len(ciphertext) != k:
+        raise DecryptionError("decryption error")
+    c = _os2ip(ciphertext)
+    if c >= key.n:
+        raise DecryptionError("decryption error")
+    m = pow(c, key.d, key.n)
+    return oaep_decode(_i2osp(m, k), k, hash_name, label)
+
+
+# --------------------------------------------------------------------------- #
+# RSASSA-PSS
+# --------------------------------------------------------------------------- #
+
+
+def pss_encode(message: bytes, em_bits: int, hash_name: str = "sha256", salt_length: int = 32) -> bytes:
+    """EMSA-PSS encoding (RFC 8017 section 9.1.1)."""
+    hlen = _hash_length(hash_name)
+    em_len = (em_bits + 7) // 8
+    if em_len < hlen + salt_length + 2:
+        raise ValueError("encoding error")
+    m_hash = _digest(hash_name, message)
+    salt = os.urandom(salt_length)
+    h = _digest(hash_name, b"\x00" * 8 + m_hash + salt)
+    ps = b"\x00" * (em_len - salt_length - hlen - 2)
+    db = ps + b"\x01" + salt
+    db_mask = mgf1(h, em_len - hlen - 1, hash_name)
+    masked_db = bytearray(_xor(db, db_mask))
+    masked_db[0] &= 0xFF >> (8 * em_len - em_bits)
+    return bytes(masked_db) + h + b"\xbc"
+
+
+def pss_verify(message: bytes, encoded: bytes, em_bits: int, hash_name: str = "sha256",
+               salt_length: int = 32) -> bool:
+    """EMSA-PSS verification (RFC 8017 section 9.1.2). Returns a bool."""
+    hlen = _hash_length(hash_name)
+    em_len = (em_bits + 7) // 8
+    if len(encoded) != em_len or em_len < hlen + salt_length + 2:
+        return False
+    if encoded[-1] != 0xBC:
+        return False
+    masked_db = bytearray(encoded[: em_len - hlen - 1])
+    h = encoded[em_len - hlen - 1 : em_len - 1]
+    if masked_db[0] & ~(0xFF >> (8 * em_len - em_bits)):
+        return False
+    masked_db[0] &= 0xFF >> (8 * em_len - em_bits)
+    db = bytearray(_xor(bytes(masked_db), mgf1(h, em_len - hlen - 1, hash_name)))
+    db[0] &= 0xFF >> (8 * em_len - em_bits)
+    ps_len = em_len - hlen - salt_length - 2
+    if db[:ps_len] != b"\x00" * ps_len or db[ps_len] != 0x01:
+        return False
+    salt = bytes(db[-salt_length:]) if salt_length else b""
+    m_hash = _digest(hash_name, message)
+    return h == _digest(hash_name, b"\x00" * 8 + m_hash + salt)
+
+
+def pss_sign(key, message: bytes, hash_name: str = "sha256", salt_length: int = 32) -> bytes:
+    """RSASSA-PSS sign; requires the private exponent."""
+    if key.d is None:
+        raise InvalidSignatureError("signing requires a private key")
+    k = _modulus_size(key.n)
+    em_bits = key.n.bit_length() - 1
+    encoded = pss_encode(message, em_bits, hash_name, salt_length)
+    m = _os2ip(encoded)
+    if m >= key.n:
+        raise ValueError("encoded message representative out of range")
+    return _i2osp(pow(m, key.d, key.n), k)
+
+
+def pss_verify_signature(key, message: bytes, signature: bytes, hash_name: str = "sha256",
+                         salt_length: int = 32) -> bool:
+    """RSASSA-PSS verify with a public (or full) :class:`RSAKey`."""
+    k = _modulus_size(key.n)
+    if len(signature) != k:
+        return False
+    s = _os2ip(signature)
+    if s >= key.n:
+        return False
+    m = pow(s, key.e, key.n)
+    em_bits = key.n.bit_length() - 1
+    return pss_verify(message, _i2osp(m, k), em_bits, hash_name, salt_length)
+
+
+__all__ = [
+    "mgf1",
+    "oaep_encode",
+    "oaep_decode",
+    "oaep_encrypt",
+    "oaep_decrypt",
+    "pss_encode",
+    "pss_verify",
+    "pss_sign",
+    "pss_verify_signature",
+]

crypto_gu-0.1.0/crypto_gu/asymmetric/rsa.py

@@ -0,0 +1,108 @@
+"""RSA public-key primitives.
+
+Pure Python, standard library only. Key generation uses the Miller-Rabin
+based :mod:`crypto_gu.number_theory` primes. Textbook RSA helpers are
+provided, plus :func:`construct_private` to build a private key from an
+explicit factorisation (the output of the attacks in
+:mod:`crypto_gu.attacks.rsa`).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from crypto_gu import number_theory as nt
+
+
+def _i2b(value: int, size: int) -> bytes:
+    return value.to_bytes(size, "big")
+
+
+def _b2i(data: bytes) -> int:
+    return int.from_bytes(data, "big")
+
+
+@dataclass
+class RSAKey:
+    """A minimal RSA public/private key pair. ``d`` may be ``None``."""
+
+    n: int
+    e: int = 65537
+    d: int | None = None
+    p: int | None = None
+    q: int | None = None
+
+    @classmethod
+    def generate(cls, bits: int = 1024, e: int = 65537) -> "RSAKey":
+        half = bits // 2
+        p = nt.rand_prime(half)
+        q = nt.rand_prime(bits - half)
+        while q == p:
+            q = nt.rand_prime(bits - half)
+        return cls._from_pq(p, q, e)
+
+    @classmethod
+    def _from_pq(cls, p: int, q: int, e: int) -> "RSAKey":
+        n = p * q
+        phi = (p - 1) * (q - 1)
+        d = nt.modinv(e, phi)
+        return cls(n=n, e=e, d=d, p=p, q=q)
+
+    @classmethod
+    def from_pq(cls, p: int, q: int, e: int = 65537) -> "RSAKey":
+        return cls._from_pq(p, q, e)
+
+    @classmethod
+    def from_ned(cls, n: int, e: int, d: int) -> "RSAKey":
+        return cls(n=n, e=e, d=d)
+
+    def public(self) -> "RSAKey":
+        return RSAKey(n=self.n, e=self.e)
+
+    def _size(self) -> int:
+        return (self.n.bit_length() + 7) // 8
+
+    def encrypt(self, message: bytes) -> bytes:
+        m = _b2i(message)
+        if m >= self.n:
+            raise ValueError("message too long for this RSA modulus")
+        return _i2b(pow(m, self.e, self.n), self._size())
+
+    def decrypt(self, ciphertext: bytes) -> bytes:
+        if self.d is None:
+            raise ValueError("cannot decrypt with a public-only key")
+        c = _b2i(ciphertext)
+        m = _i2b(pow(c, self.d, self.n), self._size()).lstrip(b"\x00")
+        return m or b"\x00"
+
+    def sign(self, message: bytes) -> bytes:
+        return self.decrypt(message)
+
+    def verify(self, message: bytes, signature: bytes) -> bool:
+        return _b2i(self.encrypt(signature)) == _b2i(message)
+
+    def max_bytes(self) -> int:
+        return (self.n.bit_length() - 1) // 8
+
+
+def generate_keypair(bits: int = 1024, e: int = 65537) -> RSAKey:
+    return RSAKey.generate(bits, e)
+
+
+def public_encrypt(n: int, e: int, message: bytes) -> bytes:
+    return RSAKey(n=n, e=e).encrypt(message)
+
+
+def private_decrypt(n: int, e: int, d: int, ciphertext: bytes) -> bytes:
+    return RSAKey(n=n, e=e, d=d).decrypt(ciphertext)
+
+
+def construct_private(n: int, p: int, q: int, e: int = 65537) -> RSAKey:
+    """Build the private key from a recovered factorisation."""
+    if p * q != n:
+        raise ValueError("p * q does not equal n")
+    return RSAKey._from_pq(p, q, e)
+
+
+__all__ = ["RSAKey", "generate_keypair", "public_encrypt", "private_decrypt",
+           "construct_private"]