AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

vector-forge

Mutation-driven test vector generation. Finds implementations of a cryptographic algorithm or protocol, runs mutation testing to identify escaped mutants, then generates new test vectors that deliberately exercise the uncovered code paths. Compares before/after mutation kill rates to prove vector effectiveness. Use when generating cryptographic test vectors, measuring Wycheproof coverage gaps, finding escaped mutants via mutation testing, creating cross-implementation test suites, or improving test vector coverage for crypto primitives.

Original source
trailofbits
License
CC-BY-SA-4.0
Pinned revision
2be6433b39e009cd2b6fd3be1895f6b1faa5af9a

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read trailofbits--vector-forge at revision 2be6433b39e009cd2b6fd3be1895f6b1faa5af9a, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 6

references/vector-patterns.md

Test Vector Patterns for Cryptographic Primitives

Patterns for designing test vectors that target specific code paths identified through mutation testing escape analysis.

Contents

  • General principles
  • Serialization / deserialization vectors
  • Signature scheme vectors
  • Hash-to-curve vectors
  • Pairing-based cryptography vectors
  • Aggregate / threshold scheme vectors
  • Key encapsulation vectors
  • Symmetric cipher vectors
  • Mapping escaped mutants to vector patterns

General Principles

Every Vector Needs a Purpose

Each test vector should target a specific code path or validation check. Document the purpose in the vector's comment field:

{
  "tcId": 5,
  "comment": "signature with flipped sign bit in G2 y-coordinate",
  "result": "invalid",
  "flags": ["ModifiedSignature"]
}

Cross-Implementation Verification is Mandatory

A test vector is only trustworthy if two independent implementations agree on its result. If they disagree, one has a bug — and that disagreement is itself a valuable finding.

Negative Vectors are More Valuable Than Positive Ones

Valid-case vectors verify basic correctness. Invalid-case vectors exercise error handling, validation, and rejection logic — the code paths where security bugs hide.

Edge Cases Over Random Cases

Random test vectors exercise the "happy path." Edge cases exercise boundary conditions where off-by-one errors, overflow, and validation gaps lurk.


Serialization / Deserialization Vectors

Target: SetBytes, FromCompressed, Decode, Unmarshal, from_bytes, deserialize and similar functions.

Point Encoding Vectors (Elliptic Curves)

| Vector Type | Purpose | Expected Result | |-------------|---------|-----------------| | Valid compressed point | Baseline correctness | valid | | Valid uncompressed point | Baseline for uncompressed path | valid | | Identity / point at infinity | Special case handling | valid or invalid (spec-dependent) | | Wrong length (truncated) | Length validation | invalid | | Wrong length (extra bytes) | Length validation | invalid | | All-zero bytes | Zero-check handling | invalid | | Field element >= modulus | Field validation | invalid | | Point not on curve | Curve check | invalid | | Point on curve but wrong subgroup | Subgroup check | invalid | | Flipped compression flag bit | Flag parsing | invalid | | Flipped sign bit | Sign selection | invalid or different point | | Maximum valid field element | Boundary condition | valid | | Modulus - 1 as field element | Boundary condition | valid | | Mixed compressed/uncompressed flags | Flag consistency | invalid |

Roundtrip Assertions

For every valid deserialization vector, add a roundtrip check: serialize(deserialize(bytes)) == bytes. This catches field arithmetic corruption (carry propagation, modular reduction, square root, negation bugs) that produces a valid-looking but incorrect point — the wrong y-coordinate changes the sort bit in the re-compressed encoding.

This technique killed 15 previously-missed Fp mutations in the BLS12-381 campaign without requiring knowledge of the internal field representation.

Single-Fault Negative Vectors

Each negative vector should isolate ONE validation check by having exactly one defect. For flag parsing mutations:

| Defect | Construction | Validates | |--------|-------------|-----------| | Compression flag cleared | bytes[0] &= 0x7f on valid point | Flag bit 7 check | | Infinity flag set | bytes[0] \|= 0x40 on non-identity | Flag bit 6 check | | Sort flag on identity | bytes = [0xe0, 0, ...] | Identity + flag consistency | | Compression cleared on identity | bytes = [0x40, 0, ...] | Identity encoding check | | Both infinity + sort | bytes[0] \|= 0x60 on valid point | Multi-flag validation | | Wrong length | 192 bytes with compression flag | Length vs flag consistency |

Keep the underlying field element valid so the ONLY reason for rejection is the flag. This is what kills & → | mutations in from_compressed_unchecked.

Scalar Encoding Vectors

| Vector Type | Purpose | Expected Result | |-------------|---------|-----------------| | Zero scalar | Zero handling | valid (context-dependent) | | One scalar | Identity element | valid | | Group order - 1 | Maximum valid | valid | | Group order | Reduction check | invalid or reduced to zero | | Group order + 1 | Overflow handling | invalid or reduced to one | | All-ones bytes | Large value handling | invalid (usually > order) | | Non-canonical encoding | Reduction behavior | depends on spec |


Signature Scheme Vectors

Target: Verify, Sign, verify, core_verify and similar.

Single Signature Vectors

| Vector Type | Purpose | Expected Result | |-------------|---------|-----------------| | Valid signature on empty message | Empty input handling | valid | | Valid signature on single byte | Minimal input | valid | | Valid signature on large message | No length limits | valid | | Wrong message (1 bit flip) | Verification correctness | invalid | | Wrong public key | Key binding | invalid | | Truncated signature | Length check | invalid | | Signature with extra bytes | Strict parsing | invalid | | Identity point as signature | Identity rejection | invalid | | Identity point as public key | Identity rejection | invalid | | Negated signature | Sign check | invalid | | Signature from wrong scheme/DST | Cross-scheme isolation | invalid | | All-zero signature bytes | Degenerate input | invalid | | Signature with field overflow | Field validation | invalid |

Multi-Signature / Aggregate Vectors

| Vector Type | Purpose | Expected Result | |-------------|---------|-----------------| | 1 signer, valid | Minimal aggregate | valid | | N signers, all valid | Standard case | valid | | N signers, one wrong message | Detects per-message binding | invalid | | Mismatched pubkey/message count | Input validation | invalid | | Empty signer list | Empty input handling | invalid | | Duplicate messages (rogue key attack) | See spec requirements | invalid | | Identity key in aggregate | Identity rejection | invalid | | Identity signature in aggregate | Identity rejection | invalid |


Hash-to-Curve Vectors

Target: HashToG1, HashToG2, hash_to_curve, encode_to_curve.

Known Answer Tests (KATs)

| Vector Type | Purpose | Expected Result | |-------------|---------|-----------------| | Empty message | Empty input handling | known point | | Single byte 0x00 | Minimal non-empty | known point | | ASCII string "abc" | Standard test | known point | | Long message (128+ bytes) | No length restrictions | known point | | Very long message (256+ bytes) | Large input handling | known point | | RFC test vectors | Spec compliance | known point |

Hash-to-curve vectors must use a specific DST (domain separation tag) and the expected output must be computed by a reference implementation.


Pairing-Based Cryptography Vectors

Target: PairingCheck, MillerLoop, FinalExponentiation, multi_miller_loop, pairing.

Pairing Check Vectors

| Vector Type | Purpose | Expected Result | |-------------|---------|-----------------| | e(P, Q) == e(P, Q) | Reflexivity | pass | | e(aP, Q) == e(P, aQ) | Bilinearity | pass | | e(P, O) == 1 | Identity handling (O = point at infinity) | pass | | e(O, Q) == 1 | Identity handling | pass | | e(P, Q) with P not in G1 | Subgroup check | fail or undefined | | e(P, Q) with Q not in G2 | Subgroup check | fail or undefined | | Multi-pairing with n=1 | Minimal multi-pairing | matches single pairing | | Multi-pairing with n=0 | Empty input | implementation-defined |


Key Encapsulation Vectors (KEM)

Target: Encapsulate, Decapsulate, encaps, decaps.

| Vector Type | Purpose | Expected Result | |-------------|---------|-----------------| | Valid encaps/decaps roundtrip | Correctness | shared secrets match | | Modified ciphertext (1 bit flip) | Ciphertext integrity | decaps fails or different secret | | Wrong secret key | Key binding | decaps fails or different secret | | Truncated ciphertext | Length validation | error | | All-zero ciphertext | Degenerate input | error | | Known-answer test (deterministic encaps) | Spec compliance | known ciphertext + secret |


Mapping Escaped Mutants to Vector Patterns

When escape analysis (Phase 4) identifies survived mutants, use this mapping to select appropriate vector patterns:

| Mutant Location | Mutant Type | Vector Pattern | |-----------------|-------------|----------------| | Length check (len != N) | CONDITIONALS_BOUNDARY | Truncated / extended inputs | | Field validation (>= modulus) | CONDITIONALS_NEGATION | Field overflow values | | Subgroup check | CONDITIONALS_NEGATION | Wrong-subgroup points | | Identity check (IsInfinity) | CONDITIONALS_NEGATION | Identity point inputs | | Sign bit handling | ARITHMETIC_BASE | Negated / flipped-sign inputs | | Error return path | CONDITIONALS_NEGATION | Input triggering that error | | Serialization flag parsing | ARITHMETIC_BASE | All flag combinations | | Loop bound (i < n) | INCREMENT_DECREMENT | Boundary-length inputs | | Arithmetic operation | INVERT_NEGATIVES | KATs verifying exact output |

Example: Mapping gnark-crypto BLS12-381 Escapes

marshal.go:117-352 (streaming encoder, NOT COVERED)
→ Not reachable via SetBytes/Bytes API
→ Need vectors exercising io.Writer-based Encode/Decode
→ Pattern: Serialization vectors via streaming API

pairing.go:352-394 (Miller loop internals, NOT COVERED)
→ Reachable via PairingCheck but specific arithmetic lines
  don't have distinguishing inputs
→ Pattern: Pairing bilinearity KATs with edge-case points

g1.go:184, g2.go:191 (endomorphism, NOT COVERED)
→ Only used in multi-scalar multiplication optimization
→ Pattern: Large-scalar multiplication with known answers