QRNG Appliance V2 User Manual

1. Important notices, warranty & intellectual property

1.1 Copyright

© Crypta Labs Limited. All rights reserved. This document and the software, firmware, configuration, and design of the QRNG Appliance Gen 2 (SKU QRNG-APPLIANCE-2) are the intellectual property of Crypta Labs Limited (“Crypta Labs”).

1.2 Intellectual property & reverse engineering

The appliance software, configuration scripts, factory tooling, and related materials are licensed for use solely as delivered on the Crypta Labs QRNG Appliance Gen 2. Any attempt to:

• duplicate, copy, reverse engineer, decompile, or redistribute the appliance software or configuration;
• open, modify, or tamper with the chassis or internal assemblies except under explicit written instruction from Crypta Labs;
• extract and reuse Crypta Labs software with third-party or substitute hardware without a valid Crypta Labs licence;

is strictly prohibited and voids the product warranty. Unauthorised use may also constitute infringement of Crypta Labs’ intellectual property rights.

1.3 Warranty disclaimer

Except as expressly stated in a separate written warranty agreement between you and Crypta Labs, the appliance and software are provided “as is”. To the maximum extent permitted by applicable law, Crypta Labs disclaims all warranties, express or implied, including merchantability, fitness for a particular purpose, and non-infringement.

1.4 Limitation of liability

Crypta Labs shall not be liable for any indirect, incidental, special, consequential, or punitive damages, or for any loss of profits, revenue, data, goodwill, or business opportunity, arising from use of (or inability to use) the appliance, even if advised of the possibility of such damages. Crypta Labs’ total liability shall not exceed the amount paid for the specific unit giving rise to the claim, except where liability cannot be limited by law.

1.5 Safety

• Install only in a suitable 19-inch rack with adequate ventilation.
• Use the supplied power cable (or an equivalent rated cable for your region).
• Do not open the chassis unless instructed in writing by Crypta Labs support.
• Disconnect power before attaching or removing rack ears if the unit is already powered.

2. Package contents

Your shipment should include:

• Crypta Labs QRNG Appliance Gen 2 (1U chassis)
• EU power cable
• Rack mount ears (pair)
• Screws to attach the ears to the chassis

If any item is missing or damaged, contact [email protected] before installation.

3. Physical description & specifications

Figure 1 — Crypta Labs QRNG Appliance Gen 2

4. Rack mounting & cabling

4.1 Attach the rack ears

1. Place the appliance on a clean, stable surface.
2. Align each rack ear with the front side mounting holes on the chassis.
3. Secure using the supplied ear-mounting screws. Do not overtighten.

4.2 Install in the rack

1. Select a 1U location with free airflow front-to-back.
2. Support the unit while aligning the ears with your rack posts.
3. Fasten the ears to the rack with your own rack screws (not supplied).
4. Ensure the chassis is level and fully seated.

4.3 Cabling

1. Power — connect the supplied EU power cable to the IEC inlet and a suitable mains outlet or PDU.
2. Network — connect a network cable to the primary management port you will configure as eth0 (or the interface name shown by the OS).
3. Console — attach a display and USB keyboard (or use the platform’s console/IPMI/iKVM if present) for first-time configuration.

5. First power-on & console login

1. Power on the appliance.
2. Wait for the OS to complete boot (typically under a minute).
3. Log in at the physical console as:

5.1 Privileged commands

All privileged operations are performed with doas (not sudo). When prompted for a password, enter the admin user password.

doas qrng-config

5.2 Access model after factory lockdown

• Configuration — physical console only (SSH is not available on production-sealed units).
• Entropy API and status web UI — HTTPS on port 443 only.

6. Initial configuration (required)

Network addressing is not pre-set. Until you configure an interface, the appliance may be unreachable from the LAN. Use the interactive tool:

doas qrng-config

6.1 Menu overview

6.2 Recommended first-run sequence

1. Set hostname (option 2) to your site naming convention.
2. Configure network (option 3):
   • Select the interface (commonly eth0).
   • Enter the IP address with CIDR, e.g. 192.168.10.50/24.
   • The tool updates addressing safely and aims to preserve routing where possible.
3. Set DNS (option 4) if you require name resolution (e.g. 1.1.1.1 and 8.8.8.8).
4. Apply & restart (option 6) after changes that affect the service.
5. Optionally Set pool size (option 5) if you need a non-default base pool (default is 32 MiB = 33554432 bytes).

6.3 Multi-NIC appliances

Units with multiple Ethernet ports may list several interfaces. Configure only the port you have cabled for management/API access first. Additional interfaces can be configured later using the same tool.

6.4 Reboot after first config

doas reboot

After reboot, confirm the unit returns on the configured address and services start automatically.

7. Verify the appliance

7.1 From the console

# Service status
doas rc-service caddy status
doas rc-service qrng-server status

# Local HTTPS health (self-signed — use -k with curl)
curl -k https://127.0.0.1/health
curl -k https://127.0.0.1/status
curl -k "https://127.0.0.1/api/v1/random?bytes=64" | xxd | head

7.2 From a client on the network

Replace APPLIANCE-IP with the address you configured:

curl -k https://APPLIANCE-IP/health
curl -k https://APPLIANCE-IP/status
curl -k "https://APPLIANCE-IP/api/v1/random?bytes=1024" --output sample.bin
ls -l sample.bin

7.3 Status dashboard

Open https://APPLIANCE-IP/status in a browser (accept the certificate warning if self-signed). Confirm Dragonfly PCIe status shows Connected, FPGA version, pool fill, and uptime.

8. Using quantum entropy (use cases)

The appliance continuously fills an in-memory entropy pool from the Dragonfly PCIe QRNG. Clients request bytes over HTTPS; there is no rate limiting on the entropy endpoint.

8.1 Typical use cases

• Key generation — seed HSMs, TLS key generation, or application-level keys with high-quality entropy.
• Cryptographic libraries — feed OS or application CSPRNG seed material.
• Simulations & Monte Carlo — large random batches for scientific or financial workloads.
• Security appliances — central entropy source for clusters (via your network controls).

8.2 Entropy pool behaviour

• Base size: 32 MiB by default (minimum retained).
• Dynamic growth: under load the pool may grow up to 64 MiB to reduce latency.
• Freshness: new quantum data is continuously appended; oldest data is discarded when over size.
• Fast start: a short high-speed burst refills the pool after service restart.

8.3 Network security note

The entropy API does not require application-level authentication. Protect access with network controls (VLAN, firewall, private management network). Only port 443 is intended for remote access on production-sealed units.

9. Sample client scripts

The following examples are provided with the product documentation and test suite. Run them from a client workstation (not necessarily from the appliance).

9.1 Simple Python client

Fetch quantum random bytes and optionally save to a file:

#!/usr/bin/env python3
import argparse
import requests
from urllib3.exceptions import InsecureRequestWarning
requests.packages.urllib3.disable_warnings(InsecureRequestWarning)

# IMPORTANT: Use the real appliance IP or a hostname that resolves.
# Unresolvable names (e.g. some .local names) can add multi-second delays per request.

def get_random(server, bytes=4096, output=None):
    url = f"https://{server}/api/v1/random"
    r = requests.get(url, params={"bytes": bytes}, timeout=30, verify=False)
    r.raise_for_status()
    data = r.content
    print(f"Received {len(data)} quantum random bytes")
    if output:
        with open(output, "wb") as f:
            f.write(data)
        print(f"Saved to {output}")
    else:
        print("First 32 bytes:", data[:32].hex())
    return data

if __name__ == "__main__":
    p = argparse.ArgumentParser()
    p.add_argument("--server", required=True, help="Appliance IP or hostname")
    p.add_argument("--bytes", type=int, default=4096)
    p.add_argument("-o", "--output")
    args = p.parse_args()
    get_random(args.server, args.bytes, args.output)

Example:

python3 qrng-client.py --server 192.168.10.50 --bytes 65536 -o entropy.bin

9.2 Curl one-liners

# 8 KiB to a file
curl -k -s "https://APPLIANCE-IP/api/v1/random?bytes=8192" -o random.bin

# 1 MiB
curl -k -s "https://APPLIANCE-IP/api/v1/random?bytes=1048576" -o entropy-1m.bin

# Health check (JSON)
curl -k -s https://APPLIANCE-IP/health

9.3 Soak / repeatability tester

For validation, latency statistics, and CSV logging across multiple sizes and repeats, use the advanced tester (qrng-test.py):

python3 qrng-test.py --server APPLIANCE-IP --repeats 50 --csv soak.csv

# Custom sizes (bytes)
python3 qrng-test.py --server APPLIANCE-IP --repeats 20 \
  --sizes 64,1024,4096,1048576 --csv soak.csv

• --server is required (no hard-coded IP).
• Self-signed TLS is accepted by default for testing.
• Summary output includes overall and per-size latency statistics (including high percentiles where enabled).

10. API reference

10.1 GET /api/v1/random

10.2 Operational endpoints (root path)

11. TLS certificates

Production units terminate HTTPS on port 443 (Caddy) and reverse-proxy to the local entropy service. Factory default is a self-signed ECDSA P-256 certificate.

• Air-gapped / high-security sites often keep the self-signed certificate and pin the fingerprint in clients.
• Public or enterprise PKI deployments may replace certificates under Crypta Labs guidance (or using documented customer tooling where provided).

Where supported, hybrid post-quantum TLS key exchange (X25519MLKEM768 with classical fallback) may be enabled on the appliance TLS stack for modern clients.

12. Day-to-day operations

12.1 Configuration changes

doas qrng-config

Use this for hostname, interfaces, DNS, and pool size. Configuration changes are audited.

12.2 Service control

doas rc-service caddy status
doas rc-service qrng-server status
doas rc-service caddy restart
doas rc-service qrng-server restart
doas reboot

12.3 Logs

12.4 Access summary

13. Troubleshooting

14. Support

For production support contact:

Please include:

• SKU / product: QRNG-APPLIANCE-2 (Gen 2)
• Appliance hostname and software version from /status
• Description of the issue and approximate time of occurrence
• Relevant log excerpts (redact sensitive network details if required)