Oracle Examples

Ready-to-copy templates demonstrating the two oracle shapes documented in Oracle interface. Save these under your project’s oracles/ directory, edit the marked constants, and point the MemDiver brute-force / n-sweep runners at them.

generic_aes_gcm.py — stateless AES-GCM

"""Stateless AES-GCM oracle boilerplate.

Copy this file, edit the three module-level constants, point
``memdiver brute-force --oracle generic_aes_gcm.py`` at it.

The verification strategy: AEAD-decrypt a known ciphertext with the
candidate as the key. If the tag verifies, we have the right key.
Wrong-length candidates are rejected in O(1).
"""

from cryptography.hazmat.primitives.ciphers.aead import AESGCM

KEY_LENGTH = 32
NONCE = bytes.fromhex("00" * 12)
CIPHERTEXT_WITH_TAG = bytes.fromhex(
    "aabbccddeeff00112233445566778899"
    "aabbccddeeff0011"
)
ASSOCIATED_DATA: bytes | None = None


def verify(candidate: bytes) -> bool:
    if len(candidate) != KEY_LENGTH:
        return False
    try:
        AESGCM(candidate).decrypt(NONCE, CIPHERTEXT_WITH_TAG, ASSOCIATED_DATA)
        return True
    except Exception:
        return False

gocryptfs.py — stateful factory, HKDF-SHA256 + per-block AEAD

"""Gocryptfs master-key oracle.

A candidate is treated as the 32-byte **unwrapped** master key (already
resident in process memory — scrypt is irrelevant on the hot path).
Verification derives the per-instance content key and AEAD-decrypts the
first block of a real ciphertext file from the vault.

gocryptfs v2 on-disk format (per file):

    file_header = version(2 big-endian) || file_id(16)
    block_0     = nonce(16) || ciphertext(4096) || gcm_tag(16)
    block_1     = nonce(16) || ciphertext(4096) || gcm_tag(16)
    ...

Content key:

    content_key = HKDF-SHA256(master_key,
                              info="AES-GCM file content encryption",
                              length=32)

Per-block AEAD:

    AES-256-GCM( key    = content_key,
                 nonce  = block.nonce,
                 ct+tag = block.ciphertext || block.gcm_tag,
                 aad    = block_num (8 big-endian) || file_id (16) )

A successful tag verify on block 0 ⇒ this candidate is the real master
key. Wrong candidates fail with ``InvalidTag``; the ``except`` below
returns False. ~150 µs per candidate on CPython, no filesystem mount.

Requires ``pip install cryptography``.

Driven by a TOML config passed via ``--oracle-config``:

    # gocryptfs_oracle.toml
    sample_ciphertext = "/path/to/vault/<encrypted_file>"

The ``sample_ciphertext`` path must point at any file encrypted by the
target gocryptfs instance. Its header_id is read directly from the
first 18 bytes.
"""

from pathlib import Path

from cryptography.hazmat.primitives import hashes
from cryptography.hazmat.primitives.ciphers.aead import AESGCM
from cryptography.hazmat.primitives.kdf.hkdf import HKDF

MASTER_KEY_LENGTH = 32
HEADER_VERSION_LENGTH = 2
HEADER_ID_LENGTH = 16
NONCE_LENGTH = 16
GCM_TAG_LENGTH = 16
CONTENT_KEY_INFO = b"AES-GCM file content encryption"


def build_oracle(config: dict) -> "GocryptfsOracle":
    return GocryptfsOracle(config)


class GocryptfsOracle:
    def __init__(self, config: dict):
        sample = Path(config["sample_ciphertext"]).read_bytes()
        min_size = (
            HEADER_VERSION_LENGTH + HEADER_ID_LENGTH
            + NONCE_LENGTH + GCM_TAG_LENGTH
        )
        if len(sample) < min_size:
            raise ValueError(
                f"sample ciphertext too short ({len(sample)} < {min_size})"
            )
        self.header_id = sample[
            HEADER_VERSION_LENGTH : HEADER_VERSION_LENGTH + HEADER_ID_LENGTH
        ]
        body = sample[HEADER_VERSION_LENGTH + HEADER_ID_LENGTH :]
        self.nonce = body[:NONCE_LENGTH]
        self.ct_and_tag = body[NONCE_LENGTH:]
        # Block 0 AAD = block_num(8 BE) || file_header_id(16)
        self.aad = (0).to_bytes(8, "big") + self.header_id

    def verify(self, candidate: bytes) -> bool:
        if len(candidate) != MASTER_KEY_LENGTH:
            return False
        try:
            content_key = HKDF(
                algorithm=hashes.SHA256(),
                length=MASTER_KEY_LENGTH,
                salt=None,
                info=CONTENT_KEY_INFO,
            ).derive(candidate)
            AESGCM(content_key).decrypt(self.nonce, self.ct_and_tag, self.aad)
            return True
        except Exception:
            return False

tls13_stub.py — TLS 1.3 traffic-secret verification scaffold

"""TLS 1.3 traffic-secret oracle — fill in the key schedule.

Treats each candidate as a 32- or 48-byte traffic secret (SHA-256 or
SHA-384 cipher suite), re-derives the record protection keys via
HKDF-Expand-Label, and attempts to AEAD-decrypt one captured TLS
record. Returns True on a successful tag verify.

This is a scaffold — the ``_derive_keys`` body is a TODO. Point it at
RFC 8446 §7.1 once you know the AEAD your target uses.

Driven by TOML:

    # tls13_oracle.toml
    encrypted_record   = "/path/to/record0.bin"   # full TLS record body
    record_nonce_hex   = "001122334455"           # explicit nonce bytes
    aead               = "AES-128-GCM"            # or "AES-256-GCM"
    hash_algo          = "SHA-256"                # or "SHA-384"
"""

from pathlib import Path

from cryptography.hazmat.primitives.ciphers.aead import AESGCM

SHA256_LENGTH = 32
SHA384_LENGTH = 48


def build_oracle(config: dict) -> "Tls13Oracle":
    return Tls13Oracle(config)


class Tls13Oracle:
    def __init__(self, config: dict):
        self.record = Path(config["encrypted_record"]).read_bytes()
        self.nonce = bytes.fromhex(config["record_nonce_hex"])
        self.aead_name = config.get("aead", "AES-128-GCM")
        self.hash_name = config.get("hash_algo", "SHA-256")
        self.expected_length = (
            SHA256_LENGTH if self.hash_name == "SHA-256" else SHA384_LENGTH
        )

    def _derive_keys(self, traffic_secret: bytes) -> bytes:
        """Return the AEAD key derived from a TLS 1.3 traffic secret.

        TODO: implement per RFC 8446 §7.1 using HKDF-Expand-Label with
        the label "tls13 key". Return the AEAD key bytes (16 for
        AES-128-GCM, 32 for AES-256-GCM).
        """
        raise NotImplementedError("fill in TLS 1.3 HKDF-Expand-Label here")

    def verify(self, candidate: bytes) -> bool:
        if len(candidate) != self.expected_length:
            return False
        try:
            key = self._derive_keys(candidate)
            AESGCM(key).decrypt(self.nonce, self.record, None)
            return True
        except Exception:
            return False