fromscratch-pycrypt 0.2.0__py3-none-any.whl

fromscratch_pycrypt-0.2.0.dist-info/METADATA

@@ -0,0 +1,225 @@
+Metadata-Version: 2.5
+Name: fromscratch-pycrypt
+Version: 0.2.0
+Summary: An educational cryptography library built from scratch in Python
+Project-URL: Homepage, https://github.com/robcox2910/pycrypt
+Project-URL: Repository, https://github.com/robcox2910/pycrypt
+Project-URL: Issues, https://github.com/robcox2910/pycrypt/issues
+Project-URL: Documentation, https://robcox2910.github.io/pycrypt/
+Author: Rob Cox
+License: MIT
+License-File: LICENSE
+Keywords: cryptography,education,encryption,hashing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Education
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Education
+Classifier: Topic :: Security :: Cryptography
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Provides-Extra: dev
+Requires-Dist: commitizen>=4.4.0; extra == 'dev'
+Requires-Dist: hypothesis>=6.170; extra == 'dev'
+Requires-Dist: pip-audit>=2.10.0; extra == 'dev'
+Requires-Dist: pre-commit>=4.0.1; extra == 'dev'
+Requires-Dist: pyright>=1.1.400; extra == 'dev'
+Requires-Dist: pytest-cov>=6.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.4; extra == 'dev'
+Requires-Dist: ruff>=0.9.3; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# PyCrypt
+
+**An educational cryptography library in plain Python.** The classic
+ciphers (Caesar, XOR) are built from scratch; the modern primitives
+(SHA-256, HMAC, PBKDF2) wrap Python's battle-tested `hashlib`/`hmac`
+standard library so you can see how the pieces fit together.
+
+> ⚠️ **For LEARNING, not real security.** The Caesar and XOR ciphers
+> and the homemade-style signatures here are easy to break. Never use
+> PyCrypt to protect real passwords, messages, or secrets -- use a
+> vetted library like `cryptography` for that.
+
+## What Is Cryptography?
+
+Imagine you want to pass a secret note to your friend in class, but you don't
+want anyone else to read it. You could write it in a secret code that only you
+and your friend understand. That's cryptography!
+
+Cryptography is the science of keeping information secret and safe. It's used
+every time you:
+
+- Send a text message
+- Log in to a website
+- Pay for something online
+- Download an app
+
+PyCrypt teaches you how all of this works by building each piece from scratch.
+
+## Examples
+
+### Hashing -- One-Way Fingerprints
+
+A hash turns any text into a fixed-size "fingerprint." You can't reverse it,
+but the same input always gives the same fingerprint.
+
+```python
+from pycrypt.hashing import sha256
+
+# Same input always gives the same hash
+print(sha256("hello"))  # "2cf24dba5fb0a30e..."
+print(sha256("hello"))  # "2cf24dba5fb0a30e..." (identical!)
+
+# Even a tiny change makes a completely different hash
+print(sha256("Hello"))  # "185f8db32271fe25..." (totally different!)
+```
+
+### Caesar Cipher -- The Secret Decoder Ring
+
+Shift every letter by a number. A becomes D (shift 3), B becomes E, and so on.
+It wraps around, so Z becomes C.
+
+```python
+from pycrypt.caesar import encrypt, decrypt, brute_force
+
+secret = encrypt("HELLO WORLD", shift=3)
+print(secret)  # "KHOOR ZRUOG"
+
+original = decrypt(secret, shift=3)
+print(original)  # "HELLO WORLD"
+
+# Try all 26 possible shifts to crack it!
+for shift, text in brute_force(secret):
+    print(f"Shift {shift}: {text}")
+```
+
+### XOR Cipher -- Flipping Switches
+
+XOR is its own inverse -- encrypt and decrypt use the exact same operation.
+Real ciphers like AES use XOR inside, but a short repeating key like ours is
+easy to break -- **for learning only**.
+
+```python
+from pycrypt.xor import xor_encrypt, xor_encrypt_bytes
+
+encrypted = xor_encrypt("secret message", key="mykey")
+print(encrypted)  # looks like random bytes
+
+# Decrypt by XOR-ing again with the same key
+decrypted = xor_encrypt_bytes(encrypted, b"mykey").decode("utf-8")
+print(decrypted)  # "secret message"
+```
+
+### HMAC -- Tamper-Evident Seals
+
+HMAC is like a wax seal on an envelope. If someone changes the message, the
+seal breaks.
+
+```python
+from pycrypt.hmac import hmac_sign, hmac_verify
+
+tag = hmac_sign("transfer $10", key="shared-secret")
+print(hmac_verify("transfer $10", tag, key="shared-secret"))   # True
+print(hmac_verify("transfer $1000", tag, key="shared-secret"))  # False!
+```
+
+### Digital Signatures -- A Shared Wax Seal
+
+A digital signature proves who wrote a message and that it hasn't been
+changed. Our version is like a wax seal that only you and your friend
+know how to make: you both share one secret key, and that same key is
+used to sign *and* to verify. (Real systems like RSA use a separate
+private key to sign and a public key anyone can verify with.)
+
+```python
+import os
+from pycrypt.signatures import sign, verify
+
+# You and your friend share this one secret key.
+key = os.urandom(32)
+
+signature = sign("I wrote this!", key)
+print(verify("I wrote this!", signature, key))       # True
+print(verify("I didn't write this", signature, key))  # False
+```
+
+## Features
+
+- **Hashing** -- SHA-256 and MD5 fingerprints
+- **Caesar Cipher** -- Shift-based encryption with brute-force cracking
+- **XOR Cipher** -- Symmetric encryption using bitwise XOR
+- **Key Derivation** -- Turn passwords into strong keys with PBKDF2
+- **HMAC** -- Tamper-proof message authentication codes
+- **Digital Signatures** -- Sign and verify messages with a shared secret key
+- **CLI Tool** -- A demo that prints hashing, Caesar, XOR, and HMAC examples
+- **100% Typed** -- Full type annotations with strict Pyright checking
+
+## Quick Start
+
+```bash
+# Install with uv
+uv add pycrypt
+
+# Or install from source
+git clone https://github.com/robcox2910/pycrypt.git
+cd pycrypt
+uv sync --all-extras
+
+# Run the CLI demo
+uv run pycrypt
+
+# Run the tests
+uv run pytest
+```
+
+<!-- docs:start -->
+## Documentation
+
+Full docs (with kid-friendly explanations of every idea): https://robcox2910.github.io/pycrypt/
+<!-- docs:end -->
+
+## Releasing
+
+Other projects in the series ([PyStack](https://github.com/robcox2910/pystack)) use a pinned release of this one,
+not whatever is on `main`. To publish a change for them:
+
+1. Merge the change to `main`.
+2. Tag it: `git tag -a vX.Y.Z -m vX.Y.Z && git push origin vX.Y.Z`.
+   A change to the public API bumps the minor version (`v0.1.0` → `v0.2.0`);
+   anything else bumps the patch (`v0.1.0` → `v0.1.1`).
+3. In each project that uses it, edit the tag in `[tool.uv.sources]`, run
+   `uv lock --upgrade-package <name>`, and open a pull request so CI checks
+   the pair together.
+
+<!-- series:start -->
+## Related Projects
+
+This project is one of a series that builds real systems "from scratch in Python" to teach how they work. See the [series home](https://robcox2910.github.io/) for the full story.
+
+| Project | What it teaches | Repository | Docs |
+| --- | --- | --- | --- |
+| PyOS | Operating systems | [py-os](https://github.com/robcox2910/py-os) | [Docs](https://robcox2910.github.io/py-os/) |
+| Pebble | Compilers and programming languages | [pebble-lang](https://github.com/robcox2910/pebble-lang) | [Docs](https://robcox2910.github.io/pebble-lang/) |
+| PyDB | Relational databases | [pydb](https://github.com/robcox2910/pydb) | [Docs](https://robcox2910.github.io/pydb/) |
+| PyKV | Key-value stores | [pykv](https://github.com/robcox2910/pykv) | [Docs](https://robcox2910.github.io/pykv/) |
+| PyDocDB | Document databases | [pydoc-db](https://github.com/robcox2910/pydoc-db) | [Docs](https://robcox2910.github.io/pydoc-db/) |
+| PyGraphDB | Graph databases | [pygraphdb](https://github.com/robcox2910/pygraphdb) | [Docs](https://robcox2910.github.io/pygraphdb/) |
+| PyTSDB | Time-series databases | [pytsdb](https://github.com/robcox2910/pytsdb) | [Docs](https://robcox2910.github.io/pytsdb/) |
+| PyVecDB | Vector databases | [pyvecdb](https://github.com/robcox2910/pyvecdb) | [Docs](https://robcox2910.github.io/pyvecdb/) |
+| PyColDB | Column-family databases | [pycoldb](https://github.com/robcox2910/pycoldb) | [Docs](https://robcox2910.github.io/pycoldb/) |
+| **PyCrypt** | **Cryptography** | [pycrypt](https://github.com/robcox2910/pycrypt) | [Docs](https://robcox2910.github.io/pycrypt/) |
+| PyNet | Computer networking | [pynet](https://github.com/robcox2910/pynet) | [Docs](https://robcox2910.github.io/pynet/) |
+| PyWeb | HTTP web servers | [pyweb](https://github.com/robcox2910/pyweb) | [Docs](https://robcox2910.github.io/pyweb/) |
+| PyGit | Version control | [pygit](https://github.com/robcox2910/pygit) | [Docs](https://robcox2910.github.io/pygit/) |
+| PySearch | Search engines | [pysearch](https://github.com/robcox2910/pysearch) | [Docs](https://robcox2910.github.io/pysearch/) |
+| PyMQ | Message queues | [pymq](https://github.com/robcox2910/pymq) | [Docs](https://robcox2910.github.io/pymq/) |
+| PyLLM | Language models (the brain) | [pyllm](https://github.com/robcox2910/pyllm) | [Docs](https://robcox2910.github.io/pyllm/) |
+| PyScheduler | Job scheduling | [pyscheduler](https://github.com/robcox2910/pyscheduler) | [Docs](https://robcox2910.github.io/pyscheduler/) |
+| PyStack | Full-stack integration | [pystack](https://github.com/robcox2910/pystack) | [Docs](https://robcox2910.github.io/pystack/) |
+<!-- series:end -->
+
+## License
+
+MIT -- see [LICENSE](LICENSE) for details.

fromscratch_pycrypt-0.2.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+pycrypt/__init__.py,sha256=sy4ZKLA3Wz3znIU8nbtORrrkZHrQ4akfCBcKRcElkh8,72
+pycrypt/_version.py,sha256=s9U3X54Pdr-Jlh9GP6LBaa_VRos7qs_wtrVefUHHNIA,520
+pycrypt/caesar.py,sha256=dMf_ZCF3bTnQH2sBg14tlfqRT_y0bUwCm3JXxhdHj28,2216
+pycrypt/cli.py,sha256=yvnfzluEtF6nNBi1yiF0C8oSaZOxVY86TDOdBqMuvdY,2583
+pycrypt/errors.py,sha256=jTbWRG-DLwPvoubN7jEGUkRvYpqdTiQP6DUUizVVnIo,339
+pycrypt/hashing.py,sha256=LL4F-WYQzHtD_tsmT1kP-tXEn5vWfofQNMvz18Q5P7I,1338
+pycrypt/hmac.py,sha256=013VIpxZhdNRiE61JHeSU8QwdOWaunz_WWEECkib7eA,1716
+pycrypt/kdf.py,sha256=_FD_RL3XcvBpuebfEWkeiLGBqFp2Nllg6TaTBD2Ihao,1349
+pycrypt/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pycrypt/signatures.py,sha256=kaxStD6za2fkxZu9NNinlH9FddqCpoeI51uLpOpwWTU,2205
+pycrypt/xor.py,sha256=MUpGxASrtz_8Yoz2JKWZQLWicaI9R7jdG4Rfck1Xwwo,2553
+fromscratch_pycrypt-0.2.0.dist-info/METADATA,sha256=5SEOI3F45-IgIPd2hypXy1bBY2ytH-cqLV4__45B8gY,9220
+fromscratch_pycrypt-0.2.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+fromscratch_pycrypt-0.2.0.dist-info/entry_points.txt,sha256=xYU5q3ieiachWFTRl7RvxcXzkPLeWigpmci-j17knm8,45
+fromscratch_pycrypt-0.2.0.dist-info/licenses/LICENSE,sha256=NtHM2ak--oE71VCcY50kcCoC1cKS0LRUsxq_xA89RNc,1064
+fromscratch_pycrypt-0.2.0.dist-info/RECORD,,

fromscratch_pycrypt-0.2.0.dist-info/WHEEL

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

fromscratch_pycrypt-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pycrypt = pycrypt.cli:main

fromscratch_pycrypt-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rob Cox
+
+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.

pycrypt/__init__.py

@@ -0,0 +1 @@
+"""PyCrypt -- educational cryptography built from scratch in Python."""

pycrypt/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.2.0'
+__version_tuple__ = version_tuple = (0, 2, 0)
+
+__commit_id__ = commit_id = None

pycrypt/caesar.py

@@ -0,0 +1,76 @@
+"""Caesar cipher -- the secret decoder ring.
+
+The simplest cipher: shift every letter by a fixed number. A becomes
+D (shift 3), B becomes E, and so on. It wraps around: X becomes A.
+
+Only the 26 letters of the English alphabet move. Everything else --
+spaces, digits, punctuation, and letters from other alphabets like
+"À" or "Σ" -- is left exactly as it was.
+
+This is easy to break (only 26 possible shifts) but it's the perfect
+starting point for understanding encryption.
+"""
+
+ALPHABET_SIZE = 26
+UPPER_A = ord("A")
+LOWER_A = ord("a")
+
+
+def encrypt(plaintext: str, shift: int) -> str:
+    """Encrypt a message using the Caesar cipher.
+
+    Shift each letter A-Z (or a-z) by the given amount. Everything else
+    (spaces, numbers, punctuation, accented letters) is left unchanged.
+
+    Args:
+        plaintext: The message to encrypt.
+        shift: How many positions to shift. Any whole number works:
+            27 does the same as 1, and -1 the same as 25.
+
+    Returns:
+        The encrypted message.
+
+    """
+    result: list[str] = []
+    for char in plaintext:
+        if "A" <= char <= "Z":
+            shifted = (ord(char) - UPPER_A + shift) % ALPHABET_SIZE
+            result.append(chr(shifted + UPPER_A))
+        elif "a" <= char <= "z":
+            shifted = (ord(char) - LOWER_A + shift) % ALPHABET_SIZE
+            result.append(chr(shifted + LOWER_A))
+        else:
+            result.append(char)
+    return "".join(result)
+
+
+def decrypt(ciphertext: str, shift: int) -> str:
+    """Decrypt a Caesar cipher message.
+
+    Shift each letter backwards by the given amount.
+
+    Args:
+        ciphertext: The encrypted message.
+        shift: The shift that was used to encrypt.
+
+    Returns:
+        The original message.
+
+    """
+    return encrypt(ciphertext, -shift)
+
+
+def brute_force(ciphertext: str) -> list[tuple[int, str]]:
+    """Try all 26 possible shifts and return the results.
+
+    This shows why the Caesar cipher is weak -- you can break it by
+    trying every possible key.
+
+    Args:
+        ciphertext: The encrypted message.
+
+    Returns:
+        A list of (shift, decrypted_text) tuples.
+
+    """
+    return [(shift, decrypt(ciphertext, shift)) for shift in range(ALPHABET_SIZE)]

pycrypt/cli.py

@@ -0,0 +1,71 @@
+"""PyCrypt CLI -- demonstrate cryptography concepts."""
+
+import sys
+
+from pycrypt.caesar import decrypt as caesar_decrypt
+from pycrypt.caesar import encrypt as caesar_encrypt
+from pycrypt.hashing import sha256
+from pycrypt.hmac import hmac_sign, hmac_verify
+from pycrypt.xor import xor_decrypt, xor_encrypt
+
+CAESAR_SHIFT = 3
+SEPARATOR = "-" * 50
+
+
+def _demo_hashing() -> None:
+    """Demonstrate SHA-256 hashing."""
+    sys.stdout.write("1. HASHING (SHA-256)\n")
+    sys.stdout.write(SEPARATOR + "\n")
+    message = "Hello, World!"
+    digest = sha256(message)
+    sys.stdout.write(f'   sha256("{message}") = {digest}\n')
+    sys.stdout.write(f'   sha256("{message}") = {sha256(message)}  (same!)\n')
+    sys.stdout.write(f'   sha256("hello, world!") = {sha256("hello, world!")}  (different!)\n\n')
+
+
+def _demo_caesar() -> None:
+    """Demonstrate Caesar cipher encryption."""
+    sys.stdout.write("2. CAESAR CIPHER\n")
+    sys.stdout.write(SEPARATOR + "\n")
+    plaintext = "HELLO WORLD"
+    encrypted = caesar_encrypt(plaintext, CAESAR_SHIFT)
+    decrypted = caesar_decrypt(encrypted, CAESAR_SHIFT)
+    sys.stdout.write(f"   Plaintext:  {plaintext}\n")
+    sys.stdout.write(f"   Encrypted:  {encrypted}  (shift {CAESAR_SHIFT})\n")
+    sys.stdout.write(f"   Decrypted:  {decrypted}\n\n")
+
+
+def _demo_xor() -> None:
+    """Demonstrate XOR encryption."""
+    sys.stdout.write("3. XOR CIPHER\n")
+    sys.stdout.write(SEPARATOR + "\n")
+    message = "secret"
+    key = "mykey"
+    encrypted = xor_encrypt(message, key)
+    decrypted = xor_decrypt(encrypted, key)
+    sys.stdout.write(f"   Plaintext:  {message}\n")
+    sys.stdout.write(f'   Encrypted:  {encrypted.hex()}  (key "{key}")\n')
+    sys.stdout.write(f"   Decrypted:  {decrypted}  (XOR again with the same key)\n\n")
+
+
+def _demo_hmac() -> None:
+    """Demonstrate HMAC signing and verification."""
+    sys.stdout.write("4. HMAC (Message Authentication)\n")
+    sys.stdout.write(SEPARATOR + "\n")
+    message = "transfer $10"
+    key = "shared-secret"
+    tag = hmac_sign(message, key)
+    sys.stdout.write(f"   Message: {message}\n")
+    sys.stdout.write(f"   HMAC tag: {tag}\n")
+    sys.stdout.write(f"   Verify original:  {hmac_verify(message, tag, key)}\n")
+    sys.stdout.write(f"   Verify tampered:  {hmac_verify('transfer $1000', tag, key)}\n\n")
+
+
+def main() -> None:
+    """Run all cryptography demos."""
+    sys.stdout.write("PyCrypt -- Cryptography from scratch\n\n")
+    _demo_hashing()
+    _demo_caesar()
+    _demo_xor()
+    _demo_hmac()
+    sys.stdout.write("Learn more: https://robcox2910.github.io/pycrypt/\n")

pycrypt/errors.py

@@ -0,0 +1,13 @@
+"""Custom exceptions for PyCrypt.
+
+Clear error messages help you understand what went wrong -- especially
+important when dealing with secret messages!
+"""
+
+
+class PyCryptError(Exception):
+    """Base exception for all PyCrypt errors."""
+
+
+class VerificationError(PyCryptError):
+    """Raise when a signature or HMAC verification fails."""

pycrypt/hashing.py

@@ -0,0 +1,56 @@
+"""Hashing -- one-way fingerprints for data.
+
+A hash function is like a meat grinder: put any data in, get a
+fixed-size fingerprint out. You can't reverse it, but the same input
+always gives the same fingerprint.
+
+We use SHA-256 (used by Bitcoin, TLS, and most of the internet) from
+Python's built-in ``hashlib``. Writing SHA-256 itself from scratch is a
+big project of its own -- here we focus on what hashes are *for*.
+"""
+
+import hashlib
+
+SHA256_HEX_LENGTH = 64
+
+
+def sha256(data: str) -> str:
+    """Calculate the SHA-256 hash of a string.
+
+    Args:
+        data: The text to hash.
+
+    Returns:
+        A 64-character hexadecimal hash string.
+
+    """
+    return hashlib.sha256(data.encode("utf-8")).hexdigest()
+
+
+def sha256_bytes(data: bytes) -> str:
+    """Calculate the SHA-256 hash of raw bytes.
+
+    Args:
+        data: The bytes to hash.
+
+    Returns:
+        A 64-character hexadecimal hash string.
+
+    """
+    return hashlib.sha256(data).hexdigest()
+
+
+def md5(data: str) -> str:
+    """Calculate the MD5 hash of a string.
+
+    MD5 is broken for security but useful for checksums and teaching.
+    Never use MD5 for passwords or security.
+
+    Args:
+        data: The text to hash.
+
+    Returns:
+        A 32-character hexadecimal hash string.
+
+    """
+    return hashlib.md5(data.encode("utf-8")).hexdigest()  # noqa: S324

pycrypt/hmac.py

@@ -0,0 +1,67 @@
+"""HMAC -- tamper-evident seals for messages.
+
+HMAC (Hash-based Message Authentication Code) combines a message with
+a secret key to produce a tag. If the message changes, the tag won't
+match -- like a broken seal on a jar tells you someone opened it.
+
+Both sender and receiver need the same secret key.
+"""
+
+import hashlib
+import hmac as _hmac
+
+from pycrypt.errors import VerificationError
+
+
+def hmac_sign(message: str, key: str) -> str:
+    """Create an HMAC tag for a message.
+
+    Args:
+        message: The message to authenticate.
+        key: The shared secret key.
+
+    Returns:
+        A hex-encoded HMAC tag.
+
+    """
+    tag = _hmac.new(
+        key.encode("utf-8"),
+        message.encode("utf-8"),
+        hashlib.sha256,
+    )
+    return tag.hexdigest()
+
+
+def hmac_verify(message: str, tag: str, key: str) -> bool:
+    """Verify that a message matches its HMAC tag.
+
+    Uses constant-time comparison to prevent timing attacks.
+
+    Args:
+        message: The message to verify.
+        tag: The HMAC tag to check against.
+        key: The shared secret key.
+
+    Returns:
+        True if the message is authentic and unmodified.
+
+    """
+    expected = hmac_sign(message, key)
+    return _hmac.compare_digest(expected, tag)
+
+
+def hmac_verify_or_raise(message: str, tag: str, key: str) -> None:
+    """Verify a message or raise VerificationError.
+
+    Args:
+        message: The message to verify.
+        tag: The HMAC tag to check.
+        key: The shared secret key.
+
+    Raises:
+        VerificationError: If verification fails.
+
+    """
+    if not hmac_verify(message, tag, key):
+        msg = "HMAC verification failed -- message may have been tampered with"
+        raise VerificationError(msg)

pycrypt/kdf.py

@@ -0,0 +1,49 @@
+"""Key derivation -- turning passwords into strong keys.
+
+A password like "pizza123" is too short and predictable for encryption.
+Key derivation mixes it with salt (random data) and many rounds of
+hashing to produce a long, strong, unpredictable key.
+
+We use PBKDF2 (Password-Based Key Derivation Function 2), the same
+algorithm used by Wi-Fi (WPA2), macOS login, and many others.
+"""
+
+import hashlib
+import os
+
+DEFAULT_KEY_LENGTH = 32  # 256 bits
+DEFAULT_ROUNDS = 100_000
+
+
+def derive_key(
+    password: str,
+    salt: bytes | None = None,
+    key_length: int = DEFAULT_KEY_LENGTH,
+    rounds: int = DEFAULT_ROUNDS,
+) -> tuple[bytes, bytes]:
+    """Derive a cryptographic key from a password.
+
+    Uses PBKDF2-HMAC-SHA256 with a random salt.
+
+    Args:
+        password: The password to derive from.
+        salt: Random salt bytes (generated if not provided).
+        key_length: Length of the derived key in bytes.
+        rounds: Number of hash iterations (more = slower + safer).
+
+    Returns:
+        A tuple of (derived_key, salt). Store the salt alongside
+        the key so you can re-derive it later.
+
+    """
+    if salt is None:
+        salt = os.urandom(16)
+
+    key = hashlib.pbkdf2_hmac(
+        "sha256",
+        password.encode("utf-8"),
+        salt,
+        iterations=rounds,
+        dklen=key_length,
+    )
+    return key, salt

pycrypt/signatures.py

@@ -0,0 +1,63 @@
+"""Digital signatures -- a wax seal only you and your friend can make.
+
+FOR LEARNING ONLY -- never use this to protect real secrets.
+
+Imagine a wax seal that only you and your best friend know how to
+press -- because you both share the same secret stamp. When your
+friend gets a letter with that seal, they know it's really from you
+(authenticity) and that no one changed it on the way (integrity).
+
+Our educational version works exactly like that shared stamp: the
+*same* secret key is used to both make (sign) and check (verify) the
+seal. Under the hood we reuse HMAC, so the "seal" really is an HMAC
+tag. Real signature systems like RSA and ECDSA use a *pair* of keys --
+a private one to sign and a public one anyone can verify with -- so
+the whole world can check a signature without knowing your secret.
+That needs advanced math we'll learn later.
+
+The key ideas are the same:
+- Only someone with the shared key can create a valid signature
+- Verification checks that the signature matches the message
+- Changing the message breaks the signature
+"""
+
+import hmac as _hmac
+
+from pycrypt.hmac import hmac_sign
+
+
+def sign(message: str, key: bytes) -> str:
+    """Sign a message -- press the shared wax seal.
+
+    Create a signature that proves the message is authentic and
+    hasn't been changed. Only someone with the key can produce a
+    valid signature. Internally this is an HMAC tag over the message.
+
+    Args:
+        message: The message to sign.
+        key: The secret key (shared between signer and verifier).
+
+    Returns:
+        The signature as a hex string.
+
+    """
+    return hmac_sign(message, key.hex())
+
+
+def verify(message: str, signature: str, key: bytes) -> bool:
+    """Verify a signature -- check the wax seal is genuine.
+
+    Recompute what the signature should be and check if it matches.
+    Uses constant-time comparison to prevent timing attacks.
+
+    Args:
+        message: The message that was supposedly signed.
+        signature: The hex signature to verify.
+        key: The secret key (same key used for signing).
+
+    Returns:
+        True if the signature is valid.
+
+    """
+    expected = sign(message, key)
+    return _hmac.compare_digest(signature, expected)

pycrypt/xor.py

@@ -0,0 +1,80 @@
+"""XOR cipher -- flipping switches to hide data.
+
+FOR LEARNING ONLY -- never use this to protect real secrets.
+
+XOR is its own inverse: encrypt and decrypt use the same operation.
+Each byte of the message is XOR'd with a byte from the key. The key
+repeats if it's shorter than the message.
+
+Why is that unsafe? Because the key *repeats*, the same pattern of
+switch-flips happens again and again, and patterns are a codebreaker's
+best friend. If an attacker can guess even a few letters of the message
+(every letter starts with "Dear..."), XOR-ing those guesses with the
+secret text hands them that part of the key -- and the key repeats.
+
+XOR itself is a genuine building block: real ciphers like AES and
+ChaCha20 use it inside. What makes them safe is how they produce a long,
+never-repeating key stream -- which is the hard part we skip here.
+"""
+
+from pycrypt.errors import PyCryptError
+
+
+def xor_encrypt(data: str, key: str) -> bytes:
+    """Encrypt text using XOR with a repeating key.
+
+    To turn the result back into text, use :func:`xor_decrypt` -- it does
+    the very same XOR again, then reads the bytes back as text.
+
+    Args:
+        data: The text to encrypt.
+        key: The encryption key.
+
+    Returns:
+        The XOR'd result as bytes.
+
+    """
+    data_bytes = data.encode("utf-8")
+    key_bytes = key.encode("utf-8")
+    return _xor_bytes(data_bytes, key_bytes)
+
+
+def xor_decrypt(ciphertext: bytes, key: str) -> str:
+    """Decrypt bytes made by :func:`xor_encrypt`, back into text.
+
+    XOR is its own undo button: flipping the same switches twice puts them
+    all back where they started. So decrypting is just XOR-ing again with
+    the same key.
+
+    Args:
+        ciphertext: The bytes returned by ``xor_encrypt``.
+        key: The same key that was used to encrypt.
+
+    Returns:
+        The original text (unreadable gibberish if the key is wrong).
+
+    """
+    return _xor_bytes(ciphertext, key.encode("utf-8")).decode("utf-8", errors="replace")
+
+
+def xor_encrypt_bytes(data: bytes, key: bytes) -> bytes:
+    """Encrypt (or decrypt) raw bytes using XOR with a repeating key.
+
+    Args:
+        data: The bytes to encrypt.
+        key: The key bytes.
+
+    Returns:
+        The XOR'd result.
+
+    """
+    return _xor_bytes(data, key)
+
+
+def _xor_bytes(data: bytes, key: bytes) -> bytes:
+    """XOR each byte of data with a repeating key."""
+    if len(key) == 0:
+        msg = "Key must not be empty"
+        raise PyCryptError(msg)
+    key_len = len(key)
+    return bytes(b ^ key[i % key_len] for i, b in enumerate(data))