QUAC 100 API Reference
Complete C API reference for the QUAC 100 accelerator. All functions are declared in <quac100.h> and exported from libquac100.so (Linux) or quac100.dll (Windows).
Error Codes #
All API functions return quac_result_t. A return value of QUAC_SUCCESS (0) indicates success; negative values indicate errors.
| Code | Value | Description |
|---|---|---|
QUAC_SUCCESS | 0 | Operation completed successfully |
QUAC_ERROR_INVALID_PARAM | -1 | Invalid parameter passed to function |
QUAC_ERROR_NO_DEVICE | -2 | No QUAC 100 device found or device index out of range |
QUAC_ERROR_DEVICE_BUSY | -3 | Device is busy processing another request |
QUAC_ERROR_MEMORY | -4 | Memory allocation failed |
QUAC_ERROR_DRIVER | -5 | Kernel driver communication error |
QUAC_ERROR_HARDWARE | -6 | Hardware malfunction or self-test failure |
QUAC_ERROR_TIMEOUT | -7 | Operation timed out |
QUAC_ERROR_KEY_NOT_FOUND | -8 | Referenced key handle is invalid or destroyed |
QUAC_ERROR_BUFFER_TOO_SMALL | -9 | Output buffer is too small; required size written to length param |
QUAC_ERROR_NOT_INITIALIZED | -10 | Library not initialized — call quac_init() first |
QUAC_ERROR_ALREADY_INITIALIZED | -11 | Library already initialized |
QUAC_ERROR_PERMISSION_DENIED | -12 | Insufficient permissions (check udev rules or run as admin) |
QUAC_ERROR_CRYPTO_FAILURE | -13 | Cryptographic operation failed (e.g., decapsulation with wrong key) |
QUAC_ERROR_INTERNAL | -100 | Internal error — contact Dyber support |
Algorithm Identifiers #
| Constant | Value | Standard | Security Level |
|---|---|---|---|
QUAC_ALG_KYBER_512 | 0x0100 | FIPS 203 ML-KEM-512 | NIST Level 1 |
QUAC_ALG_KYBER_768 | 0x0101 | FIPS 203 ML-KEM-768 | NIST Level 3 |
QUAC_ALG_KYBER_1024 | 0x0102 | FIPS 203 ML-KEM-1024 | NIST Level 5 |
QUAC_ALG_DILITHIUM_2 | 0x0200 | FIPS 204 ML-DSA-44 | NIST Level 2 |
QUAC_ALG_DILITHIUM_3 | 0x0201 | FIPS 204 ML-DSA-65 | NIST Level 3 |
QUAC_ALG_DILITHIUM_5 | 0x0202 | FIPS 204 ML-DSA-87 | NIST Level 5 |
QUAC_ALG_SPHINCS_SHA3_128S | 0x0300 | FIPS 205 SLH-DSA | NIST Level 1 |
QUAC_ALG_SPHINCS_SHA3_128F | 0x0301 | FIPS 205 SLH-DSA | NIST Level 1 |
QUAC_ALG_SPHINCS_SHA3_192S | 0x0302 | FIPS 205 SLH-DSA | NIST Level 3 |
QUAC_ALG_SPHINCS_SHA3_192F | 0x0303 | FIPS 205 SLH-DSA | NIST Level 3 |
QUAC_ALG_SPHINCS_SHA3_256S | 0x0304 | FIPS 205 SLH-DSA | NIST Level 5 |
QUAC_ALG_SPHINCS_SHA3_256F | 0x0305 | FIPS 205 SLH-DSA | NIST Level 5 |
Type Definitions #
typedef void* quac_device_t; /* Opaque device handle */
typedef void* quac_key_t; /* Opaque key handle */
typedef uint64_t quac_job_id_t; /* Async operation identifier */
typedef struct {
char firmware_version[32]; /* e.g. "1.2.0" */
char driver_version[32]; /* e.g. "2.1.0" */
char serial_number[64]; /* Unique device serial */
uint32_t num_engines; /* Number of NTT engines */
uint64_t total_memory; /* Total on-board memory (bytes) */
uint32_t pcie_gen; /* PCIe generation (3, 4, or 5) */
uint32_t pcie_width; /* PCIe lane width (1–16) */
} quac_device_info_t;
typedef struct {
uint64_t ops_completed; /* Total operations since open */
uint64_t ops_failed; /* Total failed operations */
double avg_latency_us; /* Average latency (microseconds)*/
double throughput_ops_sec; /* Current throughput (ops/sec) */
uint64_t uptime_seconds; /* Device uptime */
} quac_stats_t;
typedef struct {
float temperature_celsius; /* Current die temperature */
float power_watts; /* Current power draw */
bool entropy_sufficient; /* QRNG health status */
bool self_test_passed; /* Last self-test result */
uint32_t error_count; /* Accumulated error count */
char last_error[128]; /* Human-readable last error */
} quac_health_t;Library Initialization #
quac_result_t quac_init(void)
Initialize the QuantaCore SDK. Must be called before any other API function. Discovers available QUAC 100 devices and initializes internal state. Thread-safe; only the first call performs initialization.
quac_result_t quac_shutdown(void)
Shut down the SDK and release all resources. All open devices and key handles become invalid. Must be the last SDK call. Blocks until in-flight async operations complete or time out (30s default).
const char* quac_version(void)
Return the SDK version string (e.g. "1.0.0"). Safe to call before quac_init().
bool quac_is_hardware(void)
Return true if operating against real QUAC 100 hardware, false if in simulator mode. Requires prior call to quac_init().
Device Management #
uint32_t quac_device_count(void)
Return the number of QUAC 100 devices detected in the system. Returns 0 if no hardware is present (or in simulator mode before configuration).
quac_result_t quac_open(uint32_t device_index, quac_device_t *device)
Open a handle to device at device_index (0-based). Multiple handles to the same device are permitted; operations are serialized by the driver. The caller must eventually call quac_close().
quac_result_t quac_close(quac_device_t device)
Close a device handle. Keys generated on this handle remain valid until explicitly destroyed. Pending async operations on this handle are cancelled.
quac_result_t quac_get_info(quac_device_t device, quac_device_info_t *info)
Query device information including firmware version, serial number, PCIe link status, and engine count. Populates the quac_device_info_t struct.
quac_result_t quac_get_stats(quac_device_t device, quac_stats_t *stats)
Query runtime statistics: operations completed/failed, average latency, throughput, and uptime. Counters reset on device open.
quac_result_t quac_get_health(quac_device_t device, quac_health_t *health)
Query device health: temperature, power draw, QRNG entropy status, self-test results, and error count. Use for continuous monitoring.
quac_result_t quac_selftest(quac_device_t device)
Execute a full Built-In Self-Test (BIST): memory check, NTT engine KATs, QRNG health test, inter-chip links, and power rail verification. Returns QUAC_SUCCESS if all tests pass. Takes approximately 2–5 seconds.
Key Management #
quac_result_t quac_keygen(quac_device_t device, quac_algorithm_t algorithm, quac_key_t *key)
Generate a key pair for the specified algorithm. The key is stored in on-device secure memory. The returned handle is opaque and references both public and private components. Works for both KEM and signature algorithms.
quac_result_t quac_import_key(quac_device_t device, quac_algorithm_t algorithm, const uint8_t *key_data, size_t key_len, bool is_public, quac_key_t *key)
Import an externally-generated key into device secure memory. Set is_public=true for public-key-only import (enables encaps/verify but not decaps/sign).
quac_result_t quac_export_key(quac_key_t key, bool export_public, uint8_t *buffer, size_t *buffer_len)
Export key material. If export_public=true, exports only the public key. If false, exports the full key pair (requires FIPS operator role). On entry, *buffer_len is the buffer size; on exit, it contains the actual bytes written. Returns QUAC_ERROR_BUFFER_TOO_SMALL if the buffer is insufficient.
quac_result_t quac_destroy_key(quac_key_t key)
Securely destroy a key. The on-device memory is cryptographically zeroized per FIPS 140-3 requirements. The handle becomes invalid.
KEM Operations (ML-KEM / Kyber) #
quac_result_t quac_kem_keygen(quac_device_t device, quac_algorithm_t algorithm, quac_key_t *keypair)
Generate an ML-KEM key pair. Equivalent to quac_keygen() with a KEM algorithm. Entropy sourced from on-board QRNG.
quac_result_t quac_kem_encaps(quac_key_t public_key, uint8_t *ciphertext, size_t *ciphertext_len, uint8_t *shared_secret, size_t *shared_secret_len)
Encapsulate: generate a shared secret and corresponding ciphertext using the recipient's public key. The shared secret is 32 bytes for all ML-KEM parameter sets. Ciphertext sizes: 768 B (ML-KEM-512), 1088 B (ML-KEM-768), 1568 B (ML-KEM-1024).
quac_result_t quac_kem_decaps(quac_key_t secret_key, const uint8_t *ciphertext, size_t ciphertext_len, uint8_t *shared_secret, size_t *shared_secret_len)
Decapsulate: recover the shared secret from a ciphertext using the secret key. Implements implicit rejection per FIPS 203 — on decapsulation failure, a pseudorandom value is returned rather than an error, preventing chosen-ciphertext attacks.
Signature Operations (ML-DSA / SLH-DSA) #
quac_result_t quac_sign(quac_key_t secret_key, const uint8_t *message, size_t message_len, uint8_t *signature, size_t *signature_len)
Sign a message. Works with both ML-DSA (Dilithium) and SLH-DSA (SPHINCS+) keys. Signature sizes: 2420 B (ML-DSA-44), 3293 B (ML-DSA-65), 4595 B (ML-DSA-87), 7856–49856 B (SLH-DSA variants). The message is hashed internally.
quac_result_t quac_verify(quac_key_t public_key, const uint8_t *message, size_t message_len, const uint8_t *signature, size_t signature_len)
Verify a signature. Returns QUAC_SUCCESS if the signature is valid, QUAC_ERROR_CRYPTO_FAILURE if invalid. Constant-time comparison is used internally to prevent timing side-channels.
Random Number Generation (QRNG) #
quac_result_t quac_random_bytes(quac_device_t device, uint8_t *buffer, size_t length)
Fill buffer with length bytes of quantum-random data from the on-board QRNG. Output is conditioned per NIST SP 800-90B and suitable for direct use as key material. Maximum single request: 16 MB. Throughput: ~112 MB/s.
quac_result_t quac_random_seed(quac_device_t device, const uint8_t *additional_input, size_t additional_len)
Mix additional entropy into the QRNG conditioning pipeline. The additional input is XORed with the raw entropy stream before post-processing. This does not replace the quantum entropy source — it adds to it.
Asynchronous Operations #
typedef struct {
void (*completion_callback)(quac_job_id_t job_id,
quac_result_t result,
void *user_data);
void *user_data;
uint32_t timeout_ms; /* 0 = no timeout */
uint32_t priority; /* 0 = normal, 1 = high */
} quac_async_params_t;quac_result_t quac_submit_async(quac_key_t key, const quac_async_params_t *params, quac_job_id_t *job_id)
Submit an asynchronous operation. Returns immediately with a job_id. The callback is invoked from a worker thread when the operation completes.
quac_result_t quac_wait(quac_device_t device, quac_job_id_t job_id, uint32_t timeout_ms)
Block until the specified async job completes or the timeout (ms) expires. Pass 0 for infinite wait.
quac_result_t quac_poll(quac_device_t device, quac_job_id_t job_id, bool *completed)
Non-blocking poll. Sets *completed = true if the job has finished.
quac_result_t quac_cancel(quac_device_t device, quac_job_id_t job_id)
Cancel a pending async operation. If the operation has already completed, this is a no-op.
Batch Operations #
typedef struct {
quac_algorithm_t algorithm;
void *input_data;
size_t input_len;
void *output_data;
size_t output_len;
quac_result_t result; /* Set by hardware on completion */
} quac_batch_item_t;quac_result_t quac_batch_submit(quac_device_t device, quac_batch_item_t *items, size_t count)
Submit a batch of up to 4096 operations in a single PCIe round-trip. Each item's result field is populated individually on completion. Optimal batch sizes are 64–256 for maximum throughput.
quac_result_t quac_batch_wait(quac_device_t device, uint32_t timeout_ms)
Block until all batch operations complete or timeout expires.
Simulator Control #
quac_result_t quac_set_simulator_mode(bool use_simulator)
Enable software simulator mode for development without hardware. Must be called before quac_init(). The simulator uses NIST reference implementations and produces correct cryptographic output, but at software speeds.
quac_result_t quac_simulator_config(uint32_t latency_us, uint32_t throughput_ops)
Configure simulated performance characteristics. Useful for testing application behavior under hardware-like latency and throughput constraints.