# KeibiDrop Security Model

## Overview

KeibiDrop uses a hybrid post-quantum cryptographic protocol for all peer-to-peer communication. The design prioritizes defense in depth: multiple independent security layers ensure that compromise of any single component does not break the system.

## Cryptographic Primitives

| Primitive | Purpose | Standard |
|---|---|---|
| ML-KEM-1024 | Post-quantum key encapsulation | NIST FIPS 203 |
| X25519 | Classical elliptic curve key exchange | RFC 7748 |
| ChaCha20-Poly1305 | Authenticated symmetric encryption | RFC 8439 |
| HKDF-SHA512 | Key derivation | RFC 5869 |
| SHA-512 | Fingerprint hashing | FIPS 180-4 |

All cryptographic operations use Go 1.24 standard library implementations (crypto/mlkem, crypto/ecdh, crypto/sha512) plus golang.org/x/crypto for HKDF and ChaCha20-Poly1305.

## Hybrid Key Exchange

The handshake combines classical and post-quantum algorithms:

1. Both peers generate ephemeral X25519 and ML-KEM-1024 key pairs
2. X25519 ECDH produces a 32-byte classical shared secret
3. ML-KEM encapsulation produces a post-quantum shared secret
4. Both secrets are concatenated and fed into HKDF-SHA512 with label "KeibiDrop-ChaCha20-Poly1305-SEK"
5. The derived 32-byte key initializes ChaCha20-Poly1305 for all session traffic

**Why hybrid:** If ML-KEM is broken (it is new), X25519 still protects you. If X25519 is broken (quantum), ML-KEM still protects you. Both must be broken simultaneously to compromise the session.

## Ephemeral Identity

- No accounts, passwords, or persistent credentials
- Identity is a cryptographic fingerprint: SHA-512 hash of concatenated X25519 and ML-KEM public keys, base64url-encoded
- Keys are generated fresh on every startup
- Keys rotate on every disconnect, producing a new fingerprint
- Previous identities cannot be linked to new ones

## Forward Secrecy

Session keys are rotated automatically during long sessions:

- After 1 GB of data transferred, OR
- After 1 million messages sent

Rekeying uses the same hybrid ML-KEM + X25519 construction as the initial handshake. Each rekey produces independent keys for each direction. Compromise of one key exposes at most 1 GB of data.

## Nonce Management

Counter-based nonces with direction prefixes prevent nonce reuse:

- Outbound prefix: 0x4F555442 ("OUTB")
- Inbound prefix: 0x494E4244 ("INBD")
- Nonce structure: [4-byte prefix | 8-byte atomic counter] = 12 bytes

Even if both peers are at the same counter value, the direction prefix ensures different nonces. Atomic operations make the counter thread-safe.

## Relay Privacy

The relay server facilitates peer discovery but cannot read any data:

1. The fingerprint exchanged out-of-band contains a "room password" (first 32 bytes of the SHA-512 hash)
2. From the room password, two keys are derived via HKDF-SHA512:
   - **Lookup key** (label: "keibidrop-relay-lookup-v1") -- used as Bearer token for API calls
   - **Encryption key** (label: "keibidrop-relay-encrypt-v1") -- used to encrypt registration data
3. The relay stores: { lookupToken -> encryptedBlob }
4. The relay has the lookupToken but not the encryptionKey, so it cannot decrypt the blob
5. The relay cannot correlate lookups because the lookup token is a derived hash, not the fingerprint

**What the relay sees:** An opaque lookup token and an encrypted blob. It cannot determine who is communicating, what files are being shared, or any metadata about the peers.

**What the relay does not see:** Fingerprints, IP addresses (encrypted inside the blob), public keys, file names, file contents.

## Fingerprint Verification

The entire security model depends on correct fingerprint exchange. Fingerprints must be exchanged via a trusted out-of-band channel (Signal, Telegram, in-person). There is no "skip verification" option. The fingerprint IS the trust anchor.

## Threat Model

**Protected against:**
- Passive eavesdropping (all traffic encrypted)
- Quantum harvest-now-decrypt-later attacks (ML-KEM-1024)
- Relay compromise (relay cannot decrypt data)
- Key compromise limited exposure (forward secrecy via automatic rekeying)
- Nonce reuse (counter-based with direction prefixes)

**Not protected against:**
- Compromised endpoint (malware on either peer's device)
- Fingerprint interception during exchange (use a secure channel)
- IPv6 network unavailability (IPv6 required for direct P2P)

## Source Code

- Asymmetric crypto: [pkg/crypto/asymmetric.go](https://github.com/KeibiSoft/KeibiDrop/blob/c705ecc/pkg/crypto/asymmetric.go)
- Symmetric crypto: [pkg/crypto/symmetric.go](https://github.com/KeibiSoft/KeibiDrop/blob/c705ecc/pkg/crypto/symmetric.go)
- Secure connection: [pkg/session/secureconn.go](https://github.com/KeibiSoft/KeibiDrop/blob/c705ecc/pkg/session/secureconn.go)
- Rekey protocol: [pkg/session/rekey.go](https://github.com/KeibiSoft/KeibiDrop/blob/c705ecc/pkg/session/rekey.go)
- Relay integration: [pkg/logic/common/utils.go](https://github.com/KeibiSoft/KeibiDrop/blob/c705ecc/pkg/logic/common/utils.go)

## Related Pages

- [KeibiDrop Overview](keibidrop.md) -- What it is and why
- [Agent CLI Guide](keibidrop-agent-guide.md) -- kd reference for AI agents
- [FUSE vs No-FUSE](keibidrop-fuse-vs-nofuse.md) -- Choosing the right mode
- [WAW Index](index.md) -- All pages