CGA Toolkit: Cryptographically Generated Address Generator, Verifier & Simulator

CGA Toolkit is a Python implementation of Cryptographically Generated Addresses (CGA), the IPv6 mechanism that binds an IPv6 address to a public key using hash-based proofs without requiring a PKI.

This repo contains:

• A CGA generator
• A CGA verifier
• A Hash2 security-level brute-force simulator
• A FastAPI demo server
• A Command-line interface (CLI)
• A Pytest test suite
• A Python package (pyproject-based)

What Are CGAs? (Cryptographically Generated Addresses)

A CGA is an IPv6 address where the Interface Identifier (IID) is derived from:

• the user’s public key
• optional "extension fields"
• a 128-bit random "modifier"
• a security parameter Sec

The goal: Bind an IPv6 address to a public key without certificates, using only hashing.

How CGAs Work (Simplified)

1. Inputs

• Public Key (DER)
• Subnet Prefix (/64)
• Modifier (16 bytes, random)
• Collisions Counter (initially 0)
• Extension fields (rarely used)

2. Compute Hash1

Hash1 = SHA1(modifier | coll_count | public_key | ext_fields)

Take the last 64 bits → this becomes the Interface Identifier.

IPv6 Address = prefix (64 bits) | Hash1_last_64_bits

3. Compute Hash2 (for security level check)

Hash2 = SHA1(modifier | prefix | public_key | ext_fields)[:112 bits]

Then enforce:

Hash2 must start with (Sec * 16) zero bits

This acts like a proof-of-work difficulty. Sec = 0 is trivial. Sec = 7 is very hard.

ASCII diagram:

+-------------------------- IPv6 /64 Prefix ---------------------+
| 2001:db8:0:1::/64                                              |
+----------------------------------------------------------------+
| <--- Hash1 (64 bits) ----> | Derived from PK + Modifier        |
+----------------------------------------------------------------+

Repository Structure

cga-toolkit/
│
├── cga_toolkit/
│   ├── api.py           # FastAPI demo server
│   ├── attack.py        # Hash2 brute-force/difficulty simulator
│   ├── cli.py           # Command-line interface
│   ├── core.py          # CGA generator & verifier (Hash1/Hash2 logic)
│   ├── keys.py          # RSA key-generation & PEM/DER helpers
│   ├── utils.py         # Serialization, prefix handling, encoding
│   └── __init__.py      # Exports package symbols
│
├── tests/
│   └── test_utils.py    # Sample pytest tests
│
├── .gitignore
├── pyproject.toml
└── README.md

Installation

Option A: Install locally from source

pip install .

Option B: Developer mode

pip install --editable .

CLI Usage

Generate RSA keypair

python -m cga_toolkit.cli gen-key --out-prefix mykey

Produces:

• mykey.key.pem: private key
• mykey.pub.der: public key (DER)
• mykey.pub.pem: public key (PEM)

Generate CGA

python -m cga_toolkit.cli generate \
    --sec 0 \
    --prefix "2001:db8:0:1::/64" \
    --pub-der mykey.pub.der

Output:

• IPv6 CGA address
• Hash2
• Base64 CGA parameters (store these!)

Verify CGA

python -m cga_toolkit.cli verify \
    --address "<cga_ip>" \
    --params-b64 "<params>"

FastAPI Server

Launch API:

uvicorn cga_toolkit.api:app --reload

Then open:

http://127.0.0.1:8000/docs

Endpoints:

• POST /generate-simple → generate CGA + keypair
• POST /verify → verify CGA

API hides key handling (it generates keys internally). Great for demos or teaching CGA without complexity.

Hash2 Difficulty Simulator

This demonstrates how Sec increases CGA difficulty. Example:

python -m cga_toolkit.attack simulate --sec 0 --trials 10

Expected:

attempts = 1 every time

Try higher levels:

python -m cga_toolkit.attack simulate --sec 1 --trials 3

You’ll see attempts rise. This shows:

• Sec=0 → instant
• Sec>0 → exponential work factor
• Sec=7 → unrealistic in practice

Tests

Run:

pytest

Included tests cover:

• IPv6 prefix normalization
• IID reconstruction
• Round-trip param serialization

Security Notes

• Never commit private keys (*.pem, *.der are ignored)
• Sec=0 is fine for demonstrations
• Higher Sec values intentionally become slow (proof-of-work)
• Hash2 difficulty grows in powers of 2 (each Sec adds 16 zero-bits)
• CGAs offer address-to-key binding without certificates
• This repo is educational, not production-security hardened.