gRPC Migration Reference

Migrate your gRPC services to quantum-safe cryptography. Use this playground to try PQC signing, key exchange, and JWT auth over gRPC, then apply the Qudo provider to your own gRPC services — your .proto files stay the same.

1. How It Works

Three layers of PQC protection for your gRPC services, all powered by the Qudo provider:

2. Architecture

gRPC Client                    Your Reverse Proxy (NGINX)       Your gRPC Server
  |                                |                                |
  |-- TLS 1.3 (X25519MLKEM768) -->|                                |
  |                                |                                |
  |-- gRPC SignData ------------->|-- HTTP/2 ------------------->  |
  |   metadata: authorization      |                                |
  |   = Bearer <ML-DSA-65 JWT>   |  provider.sign(data, privKey,  |
  |   payload: {data, algorithm}   |    "ML-DSA-65") -> signature   |
  |                                |                                |
  |<- {signature, publicKey} -----|<- HTTP/2 --------------------  |
  |   (encrypted AES-256-GCM)     |                                |
  |                                |                                |
  |-- gRPC ExchangeKeys --------->|-- HTTP/2 ------------------->  |
  |   payload: {algorithm}         |  provider.kemEncapsulate(      |
  |                                |    pubKey, "ML-KEM-768")       |
  |<- {encapsulatedKey, secret} --|<- HTTP/2 --------------------  |

Your .proto stays the same. PQC changes are in the implementation layer only.

3. Migrate Your System

Four changes to make your existing gRPC service quantum-safe. Your .proto files, client stubs, and service interfaces stay the same.

# NGINX gRPC proxy
grpc_pass grpc://backend:9090;
ssl_ecdh_curve auto;

# NGINX gRPC proxy — PQC hybrid
grpc_pass grpc://backend:9090;
ssl_protocols TLSv1.3;
ssl_ecdh_curve X25519MLKEM768:X25519:P-384;

Signature signer = Signature.getInstance(
    "SHA256withECDSA");
signer.initSign(ecPrivateKey);
signer.update(data);
byte[] sig = signer.sign();

// Generate keypair once at startup
QudoKeyPair keys = provider.generateKeyPair(
    "ML-DSA-65");
// Sign in your RPC handler
byte[] sig = provider.sign(data,
    keys.getPrivateKeyPem(), "ML-DSA-65");
// Verify
boolean ok = provider.verify(data, sig,
    keys.getPublicKeyPem(), "ML-DSA-65");

KeyAgreement ka = KeyAgreement.getInstance(
    "ECDH");
ka.init(myPrivateKey);
ka.doPhase(peerPublicKey, true);
byte[] secret = ka.generateSecret();

// Encapsulate (sender side)
QudoKemResult encap = provider.kemEncapsulate(
    recipientPubKey, "ML-KEM-768");
byte[] sharedSecret = encap.getSharedSecret();
byte[] ciphertext = encap.getCiphertext();

// Decapsulate (recipient side)
byte[] secret = provider.kemDecapsulate(
    ciphertext, privKey, "ML-KEM-768");
// same 32-byte shared secret

// gRPC metadata
headers.put("authorization",
  "Bearer " + hmacJwt);
// JWT alg: HS256

// Sign JWT with Qudo provider
byte[] sig = provider.sign(headerPayload,
    privKey, "ML-DSA-65");
String jwt = headerPayload + "." +
    Base64.encode(sig);
// gRPC metadata (same key)
headers.put("authorization",
  "Bearer " + jwt);
// JWT alg: ML-DSA-65

Summary: What Changes vs What Stays

4. Testing

# Sign
SIGN=$(curl -sk -X POST https://localhost:8443/api/grpc/sign \
  -H "Content-Type: application/json" \
  -d '{"data":"SGVsbG8gUFFD","algorithm":"ML-DSA-65"}')
echo "$SIGN" | python3 -c "import sys,json; d=json.load(sys.stdin); print('status:', d['status'], '| algo:', d['algorithm'])"

# Extract and verify
SIG=$(echo "$SIGN" | python3 -c "import sys,json; print(json.load(sys.stdin)['signature'])")
PUB=$(echo "$SIGN" | python3 -c "import sys,json; print(json.load(sys.stdin)['publicKey'])")
curl -sk -X POST https://localhost:8443/api/grpc/verify \
  -H "Content-Type: application/json" \
  -d "{\"data\":\"SGVsbG8gUFFD\",\"signature\":\"$SIG\",\"publicKey\":\"$PUB\",\"algorithm\":\"ML-DSA-65\"}"
# Expected: {"status":"success","valid":true}

curl -sk -X POST https://localhost:8443/api/grpc/key-exchange \
  -H "Content-Type: application/json" \
  -d '{"algorithm":"ML-KEM-768"}'
# Expected: {"status":"success","algorithm":"ML-KEM-768","sharedSecretLength":32}

# Get ML-DSA-65 JWT
TOKEN=$(curl -sk -X POST https://localhost:8443/api/grpc/auth/token \
  -H "Content-Type: application/json" \
  -d '{"username":"test"}' | python3 -c "import sys,json; print(json.load(sys.stdin)['token'])")

# Decode JWT header to confirm ML-DSA-65
echo "$TOKEN" | cut -d. -f1 | base64 -d 2>/dev/null
# Expected: {"alg":"ML-DSA-65","typ":"JWT","use":"grpc"}

# Install: brew install grpcurl
grpcurl -plaintext localhost:9090 list
# Expected: pqc.PqcService

grpcurl -plaintext -d '{"category":"ALL"}' \
  localhost:9090 pqc.PqcService/GetAlgorithmInfo

5. Performance

Measured on Apple M-series, OpenSSL 3.6.1, Qudo FIPS v1.0.0. All operations include keypair generation + crypto operation.

Optimization Tips

• Cache keypairs: Generate ML-DSA keypair once at startup, not per-request (reduces sign latency to ~10ms)
• Cache JWTs: Token is valid for 1 hour — don't generate a new one per gRPC call
• Use ML-DSA-44 for high-throughput, lower-security workloads (smaller signatures, faster)
• TLS session reuse: After the first handshake, subsequent requests reuse the session key (no PQC overhead)
• Async signing: Offload PQC signing to a thread pool to avoid blocking gRPC request threads

6. Compatibility

7. Common Pitfalls

8. FAQ

Crypto Inventory

Migration Checklist

Raw TLS Handshake Output