QRNG API User Guide

Complete documentation for integrating quantum-grade cryptographic entropy into your applications. API Version 0.9.0 · Last Updated December 2025

Introduction

The RION AI Quantum Random Number Generation (QRNG) API provides cryptographically secure random numbers and cryptographic keys derived from quantum mechanical entropy sources. This API enables organizations to integrate quantum-grade randomness into their security infrastructure without requiring specialized quantum hardware.

Key Benefits

Use Cases

• Financial Services: Transaction signing, secure key generation, fraud prevention
• Healthcare: Patient data encryption, HIPAA-compliant key management
• Government: Classified communications, identity verification systems
• Blockchain: Wallet generation, smart contract randomness
• Gaming: Provably fair random outcomes with cryptographic proof
• IoT: Device authentication, secure firmware updates
• Telecommunications: Session key generation, secure tunneling

NIST Compliance

RION AI implements a complete Random Bit Generator (RBG) construction in full compliance with NIST Special Publication 800-90 series.

SP 800-90A: DRBG Implementation

RION AI implements Hash_DRBG as specified in SP 800-90A:

• Hash Function: SHA-256
• Security Strength: 256 bits
• Reseed Interval: Automatic reseeding from quantum entropy source
• Prediction Resistance: Enabled via fresh entropy injection

SP 800-90B: Entropy Source Validation

The quantum entropy source has been validated per SP 800-90B:

SP 800-90C: RBG Construction

SP 800-90C defines how to properly construct a complete Random Bit Generator (RBG) by combining multiple components. RION AI implements a full entropy source RBG:

SP 800-90C Construction Components:

1. Entropy Source (SP 800-90B): Quantum mechanical calculations providing raw entropy
2. Conditioning Component: HKDF (RFC 5869) for entropy extraction and expansion
3. DRBG (SP 800-90A): Hash_DRBG for deterministic, reproducible output generation
4. Health Testing: Continuous monitoring of entropy source quality

SP 800-22: Statistical Testing

All output passes NIST SP 800-22 statistical test suite with 99.5% pass rate (exceeds 96% threshold):

• Frequency (Monobit), Block Frequency, Cumulative Sums
• Runs, Longest Run, Rank, FFT
• Non-Overlapping Template, Overlapping Template
• Universal, Approximate Entropy
• Random Excursions, Random Excursions Variant
• Serial, Linear Complexity

Authentication

The API supports two authentication methods. API Keys are recommended for most use cases.

API Key Authentication (Recommended)

API Keys are long-lived credentials suitable for server-to-server integration.

X-API-Key: qrng_k7m2p9x4_a3b8c1d6e9f2g5h0j4k7m1n8p3q6r9s2t5u0v3w6x9y2z5a8b1c4d7e0f3

Characteristics:

• Format: qrng_ prefix + 8-character ID + 64-character secret
• SHA-256 hashed storage (secret never stored in plaintext)
• Role-based permissions (basic, standard, premium, admin)
• Revocable at any time

JWT Authentication (Admin Only)

JWT tokens are short-lived (24 hours) and used primarily for administrative operations.

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Role-Based Access Control

API Endpoints

System Endpoints

Random Generation

{
  "num_bytes": 64,
  "format": "hex",
  "quality": "high"
}

Verification

Key Generation

All keys are generated using the NIST SP 800-90C compliant RBG construction with quantum entropy seeding.

HMAC Keys

AES Keys

RSA Keys

Custom Keys

Post-Quantum Cryptography

Post-Quantum Cryptography (PQC) refers to cryptographic algorithms believed to be secure against attacks by quantum computers. RION AI implements NIST FIPS 204 Dilithium, the standardized lattice-based digital signature algorithm.

Why Post-Quantum Matters

Dilithium Keys

Dilithium Variants

Hybrid Keys

Rate Limiting

Rate limiting uses a sliding window algorithm to enforce request limits per API key based on assigned role.

Rate Limit Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1701691200

Best Practices

1. Monitor X-RateLimit-Remaining before making requests
2. Implement exponential backoff on 429 responses
3. Request larger byte counts instead of many small requests
4. Cache random data if your use case allows

Error Handling

HTTP Status Codes

Code Examples

Python

import requests

API_KEY = "qrng_k7m2p9x4_a3b8c1d6e9f2..."
BASE_URL = "https://api.rionai.com"

headers = {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json"
}

# Generate random bytes
response = requests.post(
    f"{BASE_URL}/v1/random",
    headers=headers,
    json={"num_bytes": 32, "format": "hex"}
)
data = response.json()
print(f"Random: {data['data']}")

# Generate AES key with IV
response = requests.post(
    f"{BASE_URL}/v1/keys/aes",
    headers=headers,
    json={"key_size": 256, "include_iv": True}
)
key_data = response.json()
print(f"AES Key: {key_data['key']}")

# Generate Dilithium PQC key
response = requests.post(
    f"{BASE_URL}/v1/keys/dilithium",
    headers=headers,
    json={"variant": "dilithium3"}
)
pqc_data = response.json()
print(f"Dilithium Public Key: {pqc_data['public_key'][:50]}...")

JavaScript / Node.js

const API_KEY = 'qrng_k7m2p9x4_a3b8c1d6e9f2...';
const BASE_URL = 'https://api.rionai.com';

async function generateRandom(numBytes = 32) {
    const response = await fetch(`${BASE_URL}/v1/random`, {
        method: 'POST',
        headers: {
            'X-API-Key': API_KEY,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            num_bytes: numBytes,
            format: 'hex'
        })
    });
    return response.json();
}

async function generateDilithiumKey() {
    const response = await fetch(`${BASE_URL}/v1/keys/dilithium`, {
        method: 'POST',
        headers: {
            'X-API-Key': API_KEY,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            variant: 'dilithium3',
            use_quantum_seed: true
        })
    });
    return response.json();
}

// Usage
generateRandom(64).then(data => console.log(data));

cURL (Bash / macOS / Linux)

# Generate random bytes
curl -X POST "https://api.rionai.com/v1/random" \
  -H "X-API-Key: qrng_k7m2p9x4_a3b8c1d6e9f2..." \
  -H "Content-Type: application/json" \
  -d '{"num_bytes": 32, "format": "hex"}'

# Generate AES key with IV
curl -X POST "https://api.rionai.com/v1/keys/aes" \
  -H "X-API-Key: qrng_k7m2p9x4_a3b8c1d6e9f2..." \
  -H "Content-Type: application/json" \
  -d '{"key_size": 256, "include_iv": true}'

# Generate Dilithium PQC key
curl -X POST "https://api.rionai.com/v1/keys/dilithium" \
  -H "X-API-Key: qrng_k7m2p9x4_a3b8c1d6e9f2..." \
  -H "Content-Type: application/json" \
  -d '{"variant": "dilithium3"}'

# Generate Hybrid key
curl -X POST "https://api.rionai.com/v1/keys/hybrid" \
  -H "X-API-Key: qrng_k7m2p9x4_a3b8c1d6e9f2..." \
  -H "Content-Type: application/json" \
  -d '{"classical_type": "rsa3072", "pqc_variant": "dilithium3"}'

Windows PowerShell

# Generate random bytes
Invoke-RestMethod -Uri "https://api.rionai.com/v1/random" -Method POST `
  -Headers @{"X-API-Key"="qrng_k7m2p9x4_a3b8c1d6e9f2..."; "Content-Type"="application/json"} `
  -Body '{"num_bytes": 32, "format": "hex"}'

# Generate AES key with IV
Invoke-RestMethod -Uri "https://api.rionai.com/v1/keys/aes" -Method POST `
  -Headers @{"X-API-Key"="qrng_k7m2p9x4_a3b8c1d6e9f2..."; "Content-Type"="application/json"} `
  -Body '{"key_size": 256, "include_iv": true}'

# Generate Dilithium PQC key
Invoke-RestMethod -Uri "https://api.rionai.com/v1/keys/dilithium" -Method POST `
  -Headers @{"X-API-Key"="qrng_k7m2p9x4_a3b8c1d6e9f2..."; "Content-Type"="application/json"} `
  -Body '{"variant": "dilithium3"}'

# Generate Hybrid key
Invoke-RestMethod -Uri "https://api.rionai.com/v1/keys/hybrid" -Method POST `
  -Headers @{"X-API-Key"="qrng_k7m2p9x4_a3b8c1d6e9f2..."; "Content-Type"="application/json"} `
  -Body '{"classical_type": "rsa3072", "pqc_variant": "dilithium3"}'

Security Best Practices

API Key Security

1. Never expose keys in code repositories — Use environment variables or secrets management
2. Rotate keys regularly — Create new keys before revoking old ones
3. Use minimum required permissions — Request appropriate role level
4. Monitor key usage — Review statistics for unusual activity

Transport Security

• Always use HTTPS — Never make API calls over HTTP
• Verify TLS certificates — Don't disable certificate validation
• Use TLS 1.3 when available

Compliance

Glossary

Support

Email: [email protected]

API Status: https://api.rionai.com/v1/health

Interactive Documentation: https://api.rionai.com/docs