|
| 1 | +# Adding New Curves |
| 2 | + |
| 3 | +Auths is designed so that adding a new elliptic curve (or a post-quantum algorithm) is a matter of adding enum variants and letting the compiler tell you what's missing. No grep. No guessing. The curve type is carried explicitly through every layer — from key generation to Sigstore submission. |
| 4 | + |
| 5 | +This document explains the current architecture, what's already supported, and the exact steps to add a new curve. |
| 6 | + |
| 7 | +## Currently supported |
| 8 | + |
| 9 | +| Curve | Key size | Signature size | Default | Crate | |
| 10 | +|-------|----------|----------------|---------|-------| |
| 11 | +| Ed25519 | 32 bytes | 64 bytes | No | `ring` | |
| 12 | +| P-256 (secp256r1) | 33 bytes (compressed) | 64 bytes (r‖s) | **Yes** | `p256` | |
| 13 | + |
| 14 | +P-256 is the default for all operations: identity keys, ephemeral CI keys, SSH commit signing, and Sigstore submission. Ed25519 is available for compatibility. We default to P-256 as it is the same default Sigstore uses, so is useful for bootstrapping. |
| 15 | + |
| 16 | +## Architecture: how curves flow through the system |
| 17 | + |
| 18 | +The core design principle: **the curve is an explicit field, never inferred from key length.** This means adding a new curve that shares a byte length with an existing one (e.g., secp256k1 is also 33 bytes compressed, same as P-256) won't break anything. |
| 19 | + |
| 20 | +### Layer 0: `auths-crypto` |
| 21 | + |
| 22 | +This is where a new curve starts. Three types carry the curve: |
| 23 | + |
| 24 | +**`CurveType` enum** (`crates/auths-crypto/src/provider.rs`): |
| 25 | +```rust |
| 26 | +pub enum CurveType { |
| 27 | + Ed25519, |
| 28 | + #[default] |
| 29 | + P256, |
| 30 | + // Add new variant here → compiler errors everywhere it's not handled |
| 31 | +} |
| 32 | +``` |
| 33 | + |
| 34 | +**`TypedSeed` enum** (`crates/auths-crypto/src/key_ops.rs`): |
| 35 | +```rust |
| 36 | +pub enum TypedSeed { |
| 37 | + Ed25519([u8; 32]), |
| 38 | + P256([u8; 32]), |
| 39 | + // Add new variant here |
| 40 | +} |
| 41 | +``` |
| 42 | + |
| 43 | +**`DecodedDidKey` enum** (`crates/auths-crypto/src/did_key.rs`): |
| 44 | +```rust |
| 45 | +pub enum DecodedDidKey { |
| 46 | + Ed25519([u8; 32]), |
| 47 | + P256(Vec<u8>), |
| 48 | + // Add new variant here |
| 49 | +} |
| 50 | +``` |
| 51 | + |
| 52 | +All three are exhaustive `match` targets. Adding a variant to any of them produces compiler errors at every dispatch site that doesn't handle the new curve. This is the core mechanism — the compiler is the migration tool. |
| 53 | + |
| 54 | +### Layer 0.5: `auths-keri` |
| 55 | + |
| 56 | +**`KeriPublicKey` enum** (`crates/auths-keri/src/keys.rs`): |
| 57 | +```rust |
| 58 | +pub enum KeriPublicKey { |
| 59 | + Ed25519([u8; 32]), |
| 60 | + P256([u8; 33]), |
| 61 | + // Add new variant with CESR derivation code |
| 62 | +} |
| 63 | +``` |
| 64 | + |
| 65 | +Each variant has a CESR derivation code prefix (`D` for Ed25519, `1AAJ` for P-256). The new curve needs a CESR code — either from the CESR spec or a private-use code. |
| 66 | + |
| 67 | +### Layer 1: `auths-verifier` |
| 68 | + |
| 69 | +**`DevicePublicKey`** (`crates/auths-verifier/src/core.rs`): |
| 70 | +```rust |
| 71 | +pub struct DevicePublicKey { |
| 72 | + curve: CurveType, // ← carried explicitly |
| 73 | + bytes: Vec<u8>, |
| 74 | +} |
| 75 | +``` |
| 76 | + |
| 77 | +Validation is per-curve in `try_new()`: |
| 78 | +```rust |
| 79 | +let valid = match curve { |
| 80 | + CurveType::Ed25519 => bytes.len() == 32, |
| 81 | + CurveType::P256 => bytes.len() == 33 || bytes.len() == 65, |
| 82 | + // Add new curve's valid lengths here |
| 83 | +}; |
| 84 | +``` |
| 85 | + |
| 86 | +### Layer 2+: SSH, Sigstore, CLI |
| 87 | + |
| 88 | +Each layer dispatches on `CurveType` or `TypedSeed`. The compiler forces you to handle the new variant at every site. |
| 89 | + |
| 90 | +## Steps to add a new curve |
| 91 | + |
| 92 | +This is a concrete checklist. The order matters — each step unblocks the next. |
| 93 | + |
| 94 | +### Step 1: Add the crypto primitives |
| 95 | + |
| 96 | +**File: `crates/auths-crypto/src/provider.rs`** |
| 97 | + |
| 98 | +1. Add a variant to `CurveType`: |
| 99 | + ```rust |
| 100 | + pub enum CurveType { |
| 101 | + Ed25519, |
| 102 | + #[default] |
| 103 | + P256, |
| 104 | + NewCurve, // e.g., MlDsa44 for post-quantum |
| 105 | + } |
| 106 | + ``` |
| 107 | +2. Add constants: `NEW_CURVE_PUBLIC_KEY_LEN`, `NEW_CURVE_SIGNATURE_LEN` |
| 108 | +3. Update `CurveType::public_key_len()` and `CurveType::signature_len()` |
| 109 | +4. Update `Display` impl |
| 110 | + |
| 111 | +**File: `crates/auths-crypto/src/key_ops.rs`** |
| 112 | + |
| 113 | +1. Add a variant to `TypedSeed`: |
| 114 | + ```rust |
| 115 | + pub enum TypedSeed { |
| 116 | + Ed25519([u8; 32]), |
| 117 | + P256([u8; 32]), |
| 118 | + NewCurve([u8; N]), // whatever the seed size is |
| 119 | + } |
| 120 | + ``` |
| 121 | +2. Update `TypedSeed::curve()`, `TypedSeed::as_bytes()` |
| 122 | +3. Add a parsing branch in `parse_key_material()` — detect the new PKCS8 OID or key format |
| 123 | +4. Add signing logic in `sign()` — dispatch to the new crate |
| 124 | +5. Add public key derivation in `public_key()` |
| 125 | + |
| 126 | +**File: `crates/auths-crypto/src/ring_provider.rs`** (or a new provider file) |
| 127 | + |
| 128 | +Add standalone `new_curve_sign()`, `new_curve_verify()`, `new_curve_public_key_from_seed()` functions. |
| 129 | + |
| 130 | +### Step 2: Add DID encoding |
| 131 | + |
| 132 | +**File: `crates/auths-crypto/src/did_key.rs`** |
| 133 | + |
| 134 | +1. Define the multicodec prefix bytes for the new curve (from the [multicodec table](https://github.com/multiformats/multicodec/blob/master/table.csv)) |
| 135 | +2. Add `new_curve_pubkey_to_did_key()` function |
| 136 | +3. Add variant to `DecodedDidKey` |
| 137 | +4. Update `did_key_decode()` to handle the new multicodec prefix |
| 138 | + |
| 139 | +### Step 3: Add KERI support |
| 140 | + |
| 141 | +**File: `crates/auths-keri/src/keys.rs`** |
| 142 | + |
| 143 | +1. Add variant to `KeriPublicKey` |
| 144 | +2. Assign a CESR derivation code (check the [CESR spec](https://weboftrust.github.io/ietf-cesr/draft-ssmith-cesr.html) for registered codes) |
| 145 | +3. Update `KeriPublicKey::parse()` to detect the new prefix |
| 146 | +4. Update `KeriPublicKey::verify_signature()` to dispatch verification |
| 147 | + |
| 148 | +**File: `crates/auths-keri/src/codec.rs`** |
| 149 | + |
| 150 | +1. Add `KeyType::NewCurve` with the CESR code |
| 151 | +2. Add `SigType::NewCurve` if the signature format differs |
| 152 | + |
| 153 | +### Step 4: Add KERI inception support |
| 154 | + |
| 155 | +**File: `crates/auths-id/src/keri/inception.rs`** |
| 156 | + |
| 157 | +1. Update `generate_keypair()` to handle the new `CurveType` |
| 158 | +2. Update `sign_with_pkcs8()` to handle the new curve's signing |
| 159 | + |
| 160 | +### Step 5: Update DevicePublicKey validation |
| 161 | + |
| 162 | +**File: `crates/auths-verifier/src/core.rs`** |
| 163 | + |
| 164 | +Update `DevicePublicKey::try_new()` to accept the new curve's key lengths. |
| 165 | + |
| 166 | +### Step 6: Add SSH wire format support |
| 167 | + |
| 168 | +**File: `crates/auths-core/src/crypto/ssh/encoding.rs`** |
| 169 | + |
| 170 | +1. Add encoding branch in `encode_ssh_pubkey()` for the new curve's SSH key type string |
| 171 | +2. Add encoding branch in `encode_ssh_signature()` for the new curve's SSH signature format |
| 172 | +3. Check if SSH has a registered key type for the new curve — post-quantum algorithms may not have one yet |
| 173 | + |
| 174 | +**File: `crates/auths-verifier/src/ssh_sig.rs`** |
| 175 | + |
| 176 | +1. Add parsing branch in `parse_pubkey_blob()` for the new SSH key type string |
| 177 | +2. Add parsing branch in `parse_sig_blob()` for the new signature format |
| 178 | + |
| 179 | +### Step 7: Add Sigstore/Rekor support |
| 180 | + |
| 181 | +**File: `crates/auths-infra-rekor/src/client.rs`** |
| 182 | + |
| 183 | +Update `pubkey_to_pem()` to produce the correct SPKI PEM for the new curve. For post-quantum algorithms, check if Rekor's DSSE entry type accepts the key format. |
| 184 | + |
| 185 | +### Step 8: Update Python/Node bindings |
| 186 | + |
| 187 | +**Files: `packages/auths-python/src/sign.rs`, `packages/auths-node/src/sign.rs`** |
| 188 | + |
| 189 | +Update the `curve` parameter parsing to accept the new curve name. |
| 190 | + |
| 191 | +### Step 9: Compile and follow the errors |
| 192 | + |
| 193 | +```bash |
| 194 | +cargo check --workspace 2>&1 | grep "non-exhaustive" |
| 195 | +``` |
| 196 | + |
| 197 | +Every `match` on `CurveType`, `TypedSeed`, `KeriPublicKey`, or `DecodedDidKey` that doesn't handle the new variant will error. Fix each one. This is the compiler doing the migration for you. |
| 198 | + |
| 199 | +### Step 10: Add tests |
| 200 | + |
| 201 | +Each crate uses `tests/cases/` for integration tests. Add test cases for: |
| 202 | +- Key generation round-trip (generate → derive pubkey → verify signature) |
| 203 | +- KERI inception with the new curve (key prefix starts with the right CESR code) |
| 204 | +- DID encoding/decoding round-trip |
| 205 | +- SSH signature creation and parsing |
| 206 | +- `DevicePublicKey` construction with valid/invalid lengths |
| 207 | + |
| 208 | +## Post-quantum considerations |
| 209 | + |
| 210 | +Post-quantum algorithms (ML-DSA/Dilithium, ML-KEM/Kyber, SLH-DSA/SPHINCS+) have different characteristics: |
| 211 | + |
| 212 | +| Property | Ed25519/P-256 | ML-DSA-44 (Dilithium2) | |
| 213 | +|----------|---------------|----------------------| |
| 214 | +| Public key | 32-33 bytes | 1,312 bytes | |
| 215 | +| Signature | 64 bytes | 2,420 bytes | |
| 216 | +| Seed | 32 bytes | 32 bytes | |
| 217 | + |
| 218 | +**Impact on auths:** |
| 219 | + |
| 220 | +- `DevicePublicKey.bytes` is `Vec<u8>` — handles any size |
| 221 | +- `TypedSeed` seed size may differ (add a new fixed-size array or use `Vec<u8>`) |
| 222 | +- SSH wire format may not have registered key types — may need a custom namespace |
| 223 | +- CESR derivation codes for PQ algorithms are not yet standardized |
| 224 | +- Attestation JSON size grows significantly — 2KB signatures instead of 64 bytes |
| 225 | +- Rekor DSSE entries grow but should still be accepted (well under the 100KB limit) |
| 226 | + |
| 227 | +The architecture handles this. The main work is in the crypto primitives (Step 1) and the wire format registrations (Steps 3, 6). The type-driven dispatch through `CurveType`/`TypedSeed` is curve-agnostic by design. |
| 228 | + |
| 229 | +## What NOT to do |
| 230 | + |
| 231 | +- **Don't infer curve from key length.** That's brittle and breaks when curves share key length. Use `CurveType` everywhere. |
| 232 | +- **Don't add a new signing function per curve.** Use `TypedSeed` and dispatch in `key_ops::sign()`. |
| 233 | +- **Don't add curve-specific public key types.** Use `DevicePublicKey` with its `curve` field. |
| 234 | +- **Don't hardcode key lengths in validation.** Put them in `CurveType::public_key_len()`. |
0 commit comments