qcicada

Rust and Python SDK for the QCicada quantum random number generator by Crypta Labs.

macOS-first — fixes FTDI serial driver issues that break the official SDK. Works on Linux too.

Install

Python

pip install qcicada

Rust

[dependencies]
qcicada = "0.1"

Quick Start

from qcicada import QCicada

with QCicada() as qrng:
    print(qrng.random(32).hex())

use qcicada::QCicada;

let mut qrng = QCicada::open(None, None)?;
let bytes = qrng.random(32)?;
println!("{:02x?}", bytes);

The device is auto-detected. If you have multiple USB-serial devices, pass the port explicitly:

QCicada(port="/dev/cu.usbserial-DK0HFP4T")      # Python

QCicada::open(Some("/dev/cu.usbserial-DK0HFP4T"), None)?;  // Rust

Device Discovery

from qcicada import (
    find_devices,
    discover_devices,
    open_by_serial,
)

# Fast port scan (no device I/O)
find_devices()
# ['/dev/cu.usbserial-DK0HFP4T']

# Probe and verify each device
for dev in discover_devices():
    print(dev.port, dev.info.serial)

# Open by serial number
qrng = open_by_serial("QC0000000217")

use qcicada::{
    find_devices,
    discover_devices,
    open_by_serial,
};

// Fast port scan (no device I/O)
let ports = find_devices();

// Probe and verify each device
for dev in discover_devices() {
    println!("{} {}", dev.port, dev.info.serial);
}

// Open by serial number
let mut qrng = open_by_serial("QC0000000217")?;

Entropy Modes

The QCicada supports three post-processing modes:

from qcicada import QCicada, PostProcess

with QCicada() as qrng:
    qrng.random(32)  # SHA256 (default)

    qrng.set_postprocess(PostProcess.RAW_NOISE)
    qrng.random(32)

    qrng.set_postprocess(PostProcess.RAW_SAMPLES)
    qrng.random(32)

use qcicada::{QCicada, PostProcess};

let mut qrng = QCicada::open(None, None)?;
qrng.random(32)?;  // SHA256 (default)

qrng.set_postprocess(PostProcess::RawNoise)?;
qrng.random(32)?;

qrng.set_postprocess(PostProcess::RawSamples)?;
qrng.random(32)?;

Signed Reads

Random bytes with a 64-byte cryptographic signature from the device's internal key. Requires firmware 5.13+.

result = qrng.signed_read(32)
result.data       # 32 random bytes
result.signature  # 64-byte signature

let result = qrng.signed_read(32)?;
result.data       // 32 random bytes
result.signature  // 64-byte signature

Certificate Verification

Verify the device's identity using its ECDSA P-256 certificate chain. The device holds an internal keypair; a Certificate Authority (CA) signs the device's public key along with its hardware version and serial number.

# CA public key (64 bytes, from Crypta Labs)
ca_pub_key = bytes.fromhex("...")

# Verify device and get its public key
dev_pub = qrng.get_verified_pub_key(ca_pub_key)

# Signed read with signature verification
result = qrng.signed_read_verified(32, dev_pub)
result.data       # 32 verified random bytes
result.signature  # 64-byte signature

// CA public key (64 bytes, from Crypta Labs)
let ca_pub_key = hex::decode("...").unwrap();

// Verify device and get its public key
let dev_pub = qrng.get_verified_pub_key(&ca_pub_key)?;

// Signed read with signature verification
let result = qrng.signed_read_verified(32, &dev_pub)?;
result.data       // 32 verified random bytes
result.signature  // 64-byte signature

You can also access the raw primitives directly:

pub_key = qrng.get_dev_pub_key()      # 64 bytes
cert = qrng.get_dev_certificate()     # 64 bytes

from qcicada import verify_certificate
valid = verify_certificate(
    ca_pub_key, pub_key, cert,
    hw_major=1, hw_minor=1, serial_int=217,
)

let pub_key = qrng.get_dev_pub_key()?;   // 64 bytes
let cert = qrng.get_dev_certificate()?;  // 64 bytes

use qcicada::crypto::verify_certificate;
let valid = verify_certificate(
    &ca_pub_key, &pub_key, &cert, 1, 1, 217,
)?;

Continuous Mode

High-throughput streaming with no per-request overhead:

qrng.start_continuous()
for _ in range(100):
    chunk = qrng.read_continuous(1024)
qrng.stop()

qrng.start_continuous()?;
for _ in 0..100 {
    let chunk = qrng.read_continuous(1024)?;
}
qrng.stop()?;

Device Info & Status

info = qrng.get_info()
# serial, fw_version, core_version, hw_info

status = qrng.get_status()
# initialized, ready_bytes, health flags...

stats = qrng.get_statistics()
# generated_bytes, speed, failure counts...

config = qrng.get_config()
# postprocess, block_size, auto_calibration...

let info = qrng.get_info()?;
// serial, fw_version, core_version, hw_info

let status = qrng.get_status()?;
// initialized, ready_bytes, health flags...

let stats = qrng.get_statistics()?;
// generated_bytes, speed, failure counts...

let config = qrng.get_config()?;
// postprocess, block_size, auto_calibration...

Configuration

Every device setting is readable and writable:

from dataclasses import replace

config = qrng.get_config()
config = replace(config,
    block_size=256,
    auto_calibration=False,
)
qrng.set_config(config)

let mut config = qrng.get_config()?;
config.block_size = 256;
config.auto_calibration = false;
qrng.set_config(&config)?;

API Reference

Rust also implements std::io::Read, so QCicada works anywhere a reader is expected.

Project Structure

qcicada/
├── src/              # Rust crate
│   ├── lib.rs
│   ├── device.rs     # QCicada high-level API
│   ├── protocol.rs   # Wire protocol (pure, no I/O)
│   ├── crypto.rs     # ECDSA P-256 certificate verification
│   ├── serial.rs     # Serial transport + macOS fixes
│   ├── discovery.rs  # Device discovery
│   └── types.rs      # Shared data types
├── tests/            # Rust integration tests (device required)
├── examples/         # Rust examples
├── python/
│   ├── src/qcicada/  # Python package (mirrors Rust API)
│   ├── tests/        # Python unit + integration tests
│   └── examples/     # Python examples
├── Cargo.toml
└── python/pyproject.toml

Both SDKs implement the same wire protocol and share the same test vectors. Changes to one should be reflected in the other.

Why Not pyqcc?

The official Crypta Labs SDK (pyqcc) has macOS issues:

• Uses /dev/tty.* ports — macOS needs /dev/cu.*
• Sets inter_byte_timeout — causes FTDI read failures on macOS
• Timeouts too short — macOS FTDI driver needs at least 500ms
• No flush delay — FTDI driver drops bytes without a post-write pause
• Device may be left in continuous mode — no drain on connect

This SDK fixes all of these. It also works fine on Linux.

License

MIT