# latticearc

[![crates.io](https://img.shields.io/crates/v/latticearc.svg)](https://crates.io/crates/latticearc)
[![docs.rs](https://docs.rs/latticearc/badge.svg)](https://docs.rs/latticearc)
[![CI](https://github.com/LatticeArc/latticearc/actions/workflows/ci.yml/badge.svg)](https://github.com/LatticeArc/latticearc/actions/workflows/ci.yml)
[![FIPS 203-206](https://img.shields.io/badge/FIPS_203--206-implemented-blue)](https://docs.rs/latticearc)
[![codecov](https://codecov.io/gh/LatticeArc/latticearc/branch/main/graph/badge.svg)](https://codecov.io/gh/LatticeArc/latticearc)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)

Post-quantum cryptography library for Rust with unified API.

## Why LatticeArc?

| Manual Implementation | LatticeArc |
|----------------------|------------|
| ~50 lines for hybrid signing | 2 lines |
| Manage 4 separate key vectors | Single `SignedData` struct |
| Research NIST parameter sets | `UseCase::*` auto-selects |
| Manual memory zeroization | Automatic via `Zeroize` |

## Overview

LatticeArc provides post-quantum cryptographic primitives implementing NIST FIPS 203-206 standards:

- **ML-KEM** (FIPS 203) - Key encapsulation
- **ML-DSA** (FIPS 204) - Digital signatures
- **SLH-DSA** (FIPS 205) - Hash-based signatures
- **FN-DSA** (FIPS 206) - Lattice signatures
- **Hybrid encryption** - PQC + classical for defense-in-depth
- **TLS 1.3** - Post-quantum TLS integration

## Unified API

LatticeArc uses a **consistent builder pattern** across all APIs:

```rust
// Crypto operations use CryptoConfig
CryptoConfig::new()
    .use_case(UseCase::FileStorage)
    .session(&session)

// TLS configuration uses TlsConfig
TlsConfig::new()
    .use_case(TlsUseCase::WebServer)
    .with_fallback(true)
```

Both APIs share the same intuitive pattern:
- `::new()` creates defaults
- `.use_case()` selects algorithm by scenario
- `.security_level()` selects algorithm by security level

## Quick Start

Add to your `Cargo.toml`:

```toml
[dependencies]
latticearc = "0.4"
```

### Digital Signatures

```rust
use latticearc::{generate_signing_keypair, sign_with_key, verify, CryptoConfig};

// Generate signing keypair (defaults: ML-DSA-65 + Ed25519)
let config = CryptoConfig::new();
let (pk, sk, _scheme) = generate_signing_keypair(config.clone())?;

// Sign
let signed = sign_with_key(b"important document", &sk, &pk, config.clone())?;

// Verify
let is_valid = verify(&signed, config)?;
```

### Encryption

```rust
use latticearc::{encrypt, decrypt, EncryptKey, DecryptKey, CryptoConfig, CryptoScheme};

let key = [0u8; 32];  // 256-bit key
let config = CryptoConfig::new().force_scheme(CryptoScheme::Symmetric);
let encrypted = encrypt(b"secret message", EncryptKey::Symmetric(&key), config)?;
let decrypted = decrypt(&encrypted, DecryptKey::Symmetric(&key), CryptoConfig::new())?;
```

### With Use Case Selection

```rust
use latticearc::{generate_signing_keypair, sign_with_key, CryptoConfig, UseCase};

// Library auto-selects optimal algorithm
let config = CryptoConfig::new().use_case(UseCase::FinancialTransactions);
let (pk, sk, _scheme) = generate_signing_keypair(config.clone())?;
let signed = sign_with_key(b"financial data", &sk, &pk, config)?;
```

### With Security Level

```rust
use latticearc::{generate_signing_keypair, sign_with_key, CryptoConfig, SecurityLevel};

// Maximum security (ML-DSA-87 + Ed25519)
let config = CryptoConfig::new().security_level(SecurityLevel::Maximum);
let (pk, sk, _scheme) = generate_signing_keypair(config.clone())?;
let signed = sign_with_key(b"classified", &sk, &pk, config)?;
```

### Key Generation

```rust
use latticearc::generate_keypair;

// Generate Ed25519 keypair
let (public_key, private_key) = generate_keypair()?;
```

### Hybrid Encryption

```rust
use latticearc::{generate_hybrid_keypair, encrypt, decrypt, EncryptKey, DecryptKey, CryptoConfig};

// Generate hybrid keypair (ML-KEM-768 + X25519)
let (pk, sk) = generate_hybrid_keypair()?;

// Encrypt using hybrid KEM (ML-KEM + X25519 + HKDF + AES-256-GCM)
let encrypted = encrypt(b"sensitive data", EncryptKey::Hybrid(&pk), CryptoConfig::new())?;

// Decrypt
let plaintext = decrypt(&encrypted, DecryptKey::Hybrid(&sk), CryptoConfig::new())?;
```

### Hybrid Signatures

```rust
use latticearc::{generate_hybrid_signing_keypair, sign_hybrid, verify_hybrid_signature, SecurityMode};

// Generate hybrid signing keypair (ML-DSA-65 + Ed25519)
let (pk, sk) = generate_hybrid_signing_keypair(SecurityMode::Unverified)?;

// Sign (both ML-DSA and Ed25519)
let signature = sign_hybrid(b"document", &sk, SecurityMode::Unverified)?;

// Verify (both must pass)
let valid = verify_hybrid_signature(b"document", &signature, &pk, SecurityMode::Unverified)?;
```

### With Zero Trust Session

For high-security environments with session-based verification:

```rust
use latticearc::{generate_signing_keypair, sign_with_key, verify, generate_keypair, CryptoConfig, VerifiedSession};

// Establish verified session
let (public_key, private_key) = generate_keypair()?;
let session = VerifiedSession::establish(&public_key, private_key.as_ref())?;

// Operations with session verification
let config = CryptoConfig::new().session(&session);
let (pk, sk, _scheme) = generate_signing_keypair(config.clone())?;
let signed = sign_with_key(b"authenticated message", &sk, &pk, config.clone())?;
let is_valid = verify(&signed, config)?;
```

### Post-Quantum TLS

Native PQ key exchange via rustls 0.23.37+ (no extra dependencies):

```rust
use latticearc::tls::{TlsConfig, TlsUseCase};
use latticearc::SecurityLevel;

// Default: Hybrid mode (X25519MLKEM768 with X25519 fallback)
let config = TlsConfig::new();

// By use case
let config = TlsConfig::new().use_case(TlsUseCase::WebServer);

// By security level
let config = TlsConfig::new().security_level(SecurityLevel::Maximum);
```

Available key exchange groups: X25519MLKEM768 (hybrid, default), SECP256R1MLKEM768 (hybrid),
MLKEM768 (PQ-only), MLKEM1024 (PQ-only), X25519 (classical fallback).

### Low-Level Primitives

For direct access to NIST algorithms:

```rust
use latticearc::primitives::kem::ml_kem::{MlKem, MlKemSecurityLevel};
use rand::rngs::OsRng;

let mut rng = OsRng;
let (pk, sk) = MlKem::generate_keypair(&mut rng, MlKemSecurityLevel::MlKem768)?;
let (shared_secret, ciphertext) = MlKem::encapsulate(&mut rng, &pk)?;
let recovered = MlKem::decapsulate(&sk, &ciphertext)?;
```

## Included Features

All features are included by default:

- Post-quantum KEM (ML-KEM-512/768/1024)
- Post-quantum signatures (ML-DSA, SLH-DSA, FN-DSA)
- Hybrid encryption (PQC + classical)
- Zero-knowledge proofs (Schnorr, Pedersen)
- TLS 1.3 integration
- Use case-based scheme selection
- Portable key format (JSON + CBOR) with UseCase/SecurityLevel-first design

## Key Serialization

Keys are serialized using the **LatticeArc Portable Key (LPK)** format — dual JSON + CBOR
encoding identified by use case or security level. See [`docs/KEY_FORMAT.md`](../docs/KEY_FORMAT.md).

```rust
use latticearc::{PortableKey, KeyData, KeyType, UseCase};

// Generate → wrap → serialize → deserialize → use
let (pk, sk) = latticearc::generate_hybrid_keypair()?;
let (portable_pk, portable_sk) =
    PortableKey::from_hybrid_kem_keypair(UseCase::FileStorage, &pk, &sk)?;

// JSON for files/REST, CBOR for wire/storage
let json = portable_pk.to_json()?;
let cbor = portable_pk.to_cbor()?;

// Reconstruct for crypto operations
let restored_pk = PortableKey::from_json(&json)?.to_hybrid_public_key()?;
```

## Algorithm Selection

### By Use Case

| Use Case | Encryption | Signatures |
|----------|------------|------------|
| `SecureMessaging` | ML-KEM-768 + AES-256-GCM | ML-DSA-65 + Ed25519 |
| `FileStorage` | ML-KEM-1024 + AES-256-GCM | ML-DSA-87 + Ed25519 |
| `FinancialTransactions` | ML-KEM-768 + AES-256-GCM | ML-DSA-65 + Ed25519 |
| `IoTDevice` | ML-KEM-512 + AES-256-GCM | ML-DSA-44 + Ed25519 |

### By Security Level

| Level | Mode | Encryption | Signatures |
|-------|------|------------|------------|
| `Quantum` | PQ-only | ML-KEM-1024 + AES-256-GCM | ML-DSA-87 |
| `Maximum` | Hybrid | ML-KEM-1024 + AES-256-GCM | ML-DSA-87 + Ed25519 |
| `High` (default) | Hybrid | ML-KEM-768 + AES-256-GCM | ML-DSA-65 + Ed25519 |
| `Standard` | Hybrid | ML-KEM-512 + AES-256-GCM | ML-DSA-44 + Ed25519 |

> For complete security level documentation, see the [API Reference](https://docs.rs/latticearc).

## Runnable Examples

The `latticearc` crate includes comprehensive examples:

- `basic_encryption.rs` - Simple symmetric encryption with AES-256-GCM
- `digital_signatures.rs` - Digital signatures with ML-DSA and hybrid modes
- `hybrid_encryption.rs` - Hybrid encryption (ML-KEM + X25519 + HKDF)
- `post_quantum_signatures.rs` - Post-quantum signature schemes
- `complete_secure_workflow.rs` - End-to-end secure workflow with Zero Trust
- `zero_knowledge_proofs.rs` - Zero-knowledge proof demonstrations

Run an example with:
```bash
cargo run --example basic_encryption
cargo run --example digital_signatures
```

## Security

- No unsafe code
- Constant-time operations
- Automatic secret zeroization
- CAVP test vector validation

## Documentation

- [API Reference](https://docs.rs/latticearc)

## License

Apache-2.0

## Contributing

See CONTRIBUTING.md in the repository root.
