# Quantum Resistant Cryptography (QRC)

### Overview

QRC enhances Keeper's API security by combining traditional elliptic curve cryptography (ECDH-P256) with NIST-standardized post-quantum ML-KEM-1024 (Module-Lattice-based Key Encapsulation Mechanism). This hybrid approach ensures both current security and future quantum resistance.

When QRC is enabled, all API requests from Commander use a dual-layer encryption scheme that protects data even if one cryptographic algorithm is compromised.

### Requirements

| Requirement    | Details                                                                            |
| -------------- | ---------------------------------------------------------------------------------- |
| Python Version | 3.11 or higher                                                                     |
| Package        | [`keeper-mlkem`](https://pypi.org/project/keeper-mlkem/) (installed automatically) |

QRC is automatically enabled when requirements are met. No additional configuration is needed.

### How It Works

When Commander makes an API request with QRC enabled:

1. **ECDH Key Exchange**: Commander generates an ephemeral EC key pair and performs ECDH with the server's public key
2. **ML-KEM Encapsulation**: Commander encapsulates a shared secret using the server's ML-KEM-1024 public key
3. **Key Derivation**: Both secrets are combined using HKDF-SHA256 to derive an AES-256 key
4. **Encryption**: The transmission key is encrypted with AES-GCM using the derived key

### Fallback Behavior

Commander automatically falls back to standard EC encryption when:

* Python version is below 3.11
* The `keeper-mlkem` package is not installed
* Any QRC-related error occurs during encryption

All fallbacks are transparent to the user—connections continue without interruption.

### Verifying QRC Status

To verify QRC is active, enable debug logging:

```
keeper shell --debug
```

When QRC is active, you will see:

```
Using QRC hybrid encryption (ML-KEM key ID: 136, EC key ID: 10)
ECDH completed: 32 byte shared secret
ML-KEM-1024 completed: 32 byte secret, 1568 byte encapsulation
HKDF completed: derived 32 byte AES key
AES-GCM completed: 60 byte ciphertext
```

### Security Benefits

| Property                     | Description                                                                                    |
| ---------------------------- | ---------------------------------------------------------------------------------------------- |
| **Quantum Resistance**       | ML-KEM-1024 protects against attacks from future quantum computers using Shor's algorithm      |
| **Hybrid Defense**           | If either ML-KEM or ECDH is compromised in the future, the other algorithm still protects data |
| **NIST Standardized**        | ML-KEM is NIST FIPS 203 certified, ensuring rigorous security validation                       |
| **Constant-Time Operations** | C extension implementation avoids timing side-channel attacks                                  |
| **AES-256-GCM Encryption**   | Authenticated encryption provides both confidentiality and integrity                           |