quicproquo/docs/src/cryptography/identity-keys.md

# Ed25519 Identity Keys

The Ed25519 identity keypair is the long-term cryptographic identity of a
quicprochat client. It is generated once, persisted across sessions, and used
for MLS credential signing, Authentication Service registration, and delivery
queue addressing.

**Source:** `crates/quicprochat-core/src/identity.rs`

## Structure

The `IdentityKeypair` struct holds two fields:

```rust
pub struct IdentityKeypair {
    /// Raw 32-byte private seed -- zeroized on drop.
    seed: Zeroizing<[u8; 32]>,
    /// Corresponding 32-byte public verifying key.
    verifying: VerifyingKey,
}
```

| Field | Type | Size | Secret? |
|-------|------|------|---------|
| `seed` | `Zeroizing<[u8; 32]>` | 32 bytes | Yes -- zeroized on drop |
| `verifying` | `ed25519_dalek::VerifyingKey` | 32 bytes | No -- public |

The private seed is stored as raw bytes wrapped in `Zeroizing<[u8; 32]>` rather
than directly as a `SigningKey`. This design choice avoids a conflict with
`ed25519-dalek`'s own `Zeroize` implementation: the `Zeroizing<T>` wrapper
requires `T: DefaultIsZeroes`, which `[u8; 32]` satisfies (being `Copy +
Default`) but `SigningKey` does not.

## Key Generation

A fresh identity keypair is generated from the OS CSPRNG (`OsRng`) via
`ed25519-dalek`:

```rust
use quicprochat_core::identity::IdentityKeypair;

let identity = IdentityKeypair::generate();
// The signing key seed is generated from OsRng (getrandom on Linux).
// The verifying key is derived from the seed automatically.
```

Internally, `generate()` calls `SigningKey::generate(&mut OsRng)`, extracts the
32-byte seed with `to_bytes()`, wraps it in `Zeroizing`, and derives the
`VerifyingKey`:

```rust
pub fn generate() -> Self {
    use rand::rngs::OsRng;
    let signing = SigningKey::generate(&mut OsRng);
    let verifying = signing.verifying_key();
    let seed = Zeroizing::new(signing.to_bytes());
    Self { seed, verifying }
}
```

## Fingerprint Computation

The fingerprint is a SHA-256 digest of the raw 32-byte Ed25519 public key. It
serves as a compact, collision-resistant identifier for logging and protocol
indexing:

```rust
pub fn fingerprint(&self) -> [u8; 32] {
    let mut hasher = Sha256::new();
    hasher.update(self.verifying.to_bytes());
    hasher.finalize().into()
}
```

The `Debug` implementation uses the first 4 bytes of the fingerprint as a
human-readable prefix:

```rust
// Output example:
// IdentityKeypair { fingerprint: "a1b2c3d4...", .. }
```

This ensures the private seed is never accidentally printed to logs.

## Zeroization

The 32-byte private seed is wrapped in `Zeroizing<[u8; 32]>` from the `zeroize`
crate. When the `IdentityKeypair` struct is dropped, the `Zeroizing` wrapper
overwrites the seed bytes with zeros before deallocation. This mitigates the
risk of key material lingering in memory after the struct is no longer needed.

Key points about the zeroization strategy:

- **On drop:** The seed is overwritten with zeros automatically.
- **Serialization:** `seed_bytes()` returns a plain `[u8; 32]` copy for
  persistence. The caller is responsible for securely handling this copy.
- **Reconstruction:** `from_seed(seed)` wraps the provided bytes in a fresh
  `Zeroizing` immediately.
- **No `Clone`/`Copy`:** `IdentityKeypair` does not implement `Clone` or
  `Copy`, preventing accidental duplication of secret material.

See [Key Lifecycle and Zeroization](key-lifecycle.md) for the full lifecycle of
this key type.

## Role in MLS

The `IdentityKeypair` implements the `openmls_traits::signatures::Signer` trait,
allowing it to be passed directly to `KeyPackage::builder().build(...)`:

```rust
impl Signer for IdentityKeypair {
    fn sign(&self, payload: &[u8]) -> Result<Vec<u8>, MlsError> {
        let sk = self.signing_key();
        let sig: ed25519_dalek::Signature = sk.sign(payload);
        Ok(sig.to_bytes().to_vec())
    }

    fn signature_scheme(&self) -> SignatureScheme {
        SignatureScheme::ED25519
    }
}
```

This integration means `IdentityKeypair`:

1. Signs MLS Commits, Proposals, and KeyPackages with Ed25519.
2. Is embedded in `BasicCredential` as the raw 32-byte public key bytes.
3. Provides the `signature_key` field in `CredentialWithKey` used throughout
   the `GroupMember` lifecycle.

The MLS ciphersuite (`MLS_128_DHKEMX25519_AES128GCM_SHA256_Ed25519`) mandates
Ed25519 for signing, making the `IdentityKeypair` the natural fit.

## Role in the Authentication Service

The Ed25519 public key bytes (`public_key_bytes()`) are used as the
`identityKey` in `auth.capnp` RPC calls. The Authentication Service stores
KeyPackages indexed by this key, and the Delivery Service routes messages to
queues indexed by the same key.

## Serialization

`IdentityKeypair` implements `Serialize` and `Deserialize` (serde) by
serializing only the 32-byte seed. On deserialization, `from_seed()` is called
to reconstruct the verifying key:

```rust
impl Serialize for IdentityKeypair {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where S: serde::Serializer,
    {
        serializer.serialize_bytes(&self.seed[..])
    }
}

impl<'de> Deserialize<'de> for IdentityKeypair {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where D: serde::Deserializer<'de>,
    {
        let bytes: Vec<u8> = serde::Deserialize::deserialize(deserializer)?;
        let seed: [u8; 32] = bytes
            .as_slice()
            .try_into()
            .map_err(|_| serde::de::Error::custom("identity seed must be 32 bytes"))?;
        Ok(IdentityKeypair::from_seed(seed))
    }
}
```

This means the state file contains only the 32-byte seed, and the verifying key
is deterministically re-derived on load.

## Related Pages

- [Cryptography Overview](overview.md) -- algorithm inventory
- [Key Lifecycle and Zeroization](key-lifecycle.md) -- full lifecycle diagram
- [Post-Compromise Security](post-compromise-security.md) -- how MLS credentials interact with PCS
- [Threat Model](threat-model.md) -- what identity keys protect and do not protect