<!-- Copyright (c) 2026 defconxt. All rights reserved. -->
<!-- Licensed under AGPL-3.0 — see LICENSE file for details. -->

# API Reference — Implementing Post-Quantum Cryptography

## liboqs-python

### Key Encapsulation (KEM)

```python
import oqs

# List available KEM algorithms
oqs.get_enabled_KEM_mechanisms()

# ML-KEM operations
kem = oqs.KeyEncapsulation("ML-KEM-768")
public_key = kem.generate_keypair()                     # Returns public key bytes
ciphertext, shared_secret = kem.encap_secret(public_key) # Encapsulate
shared_secret_dec = kem.decap_secret(ciphertext)         # Decapsulate
```

### Digital Signatures

```python
import oqs

# List available signature algorithms
oqs.get_enabled_sig_mechanisms()

# ML-DSA operations
sig = oqs.Signature("ML-DSA-65")
public_key = sig.generate_keypair()           # Returns public key bytes
signature = sig.sign(message)                 # Sign bytes
is_valid = sig.verify(message, signature, public_key)  # Verify
```

### Available Algorithms

| Category | Algorithms |
|---|---|
| KEM | ML-KEM-512, ML-KEM-768, ML-KEM-1024 |
| Signatures | ML-DSA-44, ML-DSA-65, ML-DSA-87 |
| Hash-based Sigs | SLH-DSA-SHA2-128f, SLH-DSA-SHA2-256f |

## oqs-provider (OpenSSL)

### Key Generation

```bash
# PQC-only key
openssl genpkey -provider oqsprovider -algorithm mlkem768 -out pqc-key.pem

# Hybrid key (classical + PQC)
openssl genpkey -provider oqsprovider -algorithm x25519_mlkem768 -out hybrid.pem
```

### Certificate Creation

```bash
openssl req -new -x509 -provider oqsprovider \
  -key hybrid.pem -out cert.pem -subj "/CN=PQC Test"
```

### TLS Testing

```bash
# Server
openssl s_server -provider oqsprovider -cert cert.pem -key key.pem -port 4433

# Client
openssl s_client -provider oqsprovider -connect localhost:4433 \
  -groups x25519_mlkem768
```

## Agent Script

```bash
# List PQC algorithms
node agent.js list

# Test ML-KEM round-trip
node agent.js test-kem --algorithm ML-KEM-768

# Test ML-DSA signatures
node agent.js test-sig --algorithm ML-DSA-65

# Benchmark algorithm
node agent.js benchmark ML-KEM-768 --type kem --iterations 1000

# Check OpenSSL PQC support
node agent.js check-openssl
```
