Configuring Quantum Origin¶

As covered in the Usage section, the Quantum Origin SDK supports two approaches to configuration:

The SetOptions approach where the required configuration items, including the product license, are supplied programmatically using the Quantum Origin C API.
The ConfigFile approach where the configuration items are supplied in a YAML format configuration file on disk. The path to this file is passed to the library during instantiation.

The configuration options that are available to the two approaches are mostly the same, but there are differences in the way that they are specified. However, the SetOptions approach does offer some features which are not available in the ConfigFile approach: most notably the Logging callback and the WSR callback features, both of which require user-defined C functions. Details of both approaches are covered below.

The common set of configuration options for Quantum Origin are explained in this section.

Each of the available options can be grouped into one of four configuration categories:

Logging
Local source of randomness (LSR/WSR)
Inter-request caching
License code providing both customer authorization and the quantum seed

The details of these approaches, and the associated configuration items are covered below.

A few notes regarding the ConfigFile approach:

The specification gives a guide as to how a YAML configuration should look
Examples are available at the end of this section.
The configuration is case-insensitive to specified keywords below.
The options may be placed at the top-level of the YAML file, or may be placed in a child subsection, or node. This node path is specified at the time of instantiation. This allows other apps, modules or components to share the same config file, or alternatively allows a single config file to hold multiple configuration sets, selectable by their respective node-paths.

Configuration Specification¶

Logging¶

This functionality is defined within the configuration file under the logging field.

Quantum Origin offers a variety of logging methods outlined in the table below. Quantum Origin provides robust logging to ensure comprehensive tracking and monitoring of system activities. Quantum Origin supports multiple log levels, allowing users to customize the verbosity of the logs according to their needs. These features are designed to facilitate troubleshooting, track operations, and monitor system performance.

Logging Mode¶

Function: qosdk_setopt_int()

Option: QOSDK_OPT_LOGGING_MODE

SetOpt Option	Description	Uses `path`
`QOSDK_LOGMODE_STDOUT`	Logs to standard out on the terminal.	No
`QOSDK_LOGMODE_STDERR`	Logs to standard error on the terminal.	No
`QOSDK_LOGMODE_SYSLOG`	Logs to the local system log (where supported).	No
`QOSDK_LOGMODE_DAILYFILE`	Logs to a new file on a daily basis (according to local system time).	Yes
`QOSDK_LOGMODE_FILE`	Logs to a specified file.	Yes
`QOSDK_LOGMODE_INHERIT`	Inherit logging settings from parent application (will use whichever logger is configured as spdlog default).	No

Example:

erc = qosdk_setopt_int(pQuantumOriginConfig, QOSDK_OPT_LOGGING_MODE, QOSDK_LOGMODE_DAILYFILE);
...
erc = qosdk_setopt_str(pQuantumOriginConfig, QOSDK_OPT_LOGGING_FILENAME, "quantum_origin_sdk_log.log");
...
erc = qosdk_setopt_int(pQuantumOriginConfig, QOSDK_OPT_LOGGING_LEVEL, QOSDK_LOGLEVEL_WARNING);
...

Note that the QOSDK_LOGMODE_SYSLOG option is not supported on the Windows implementation.

ConfigFile Option	Description	Uses `path`
`stdout`	Logs to standard out on the terminal.	No
`stderr`	Logs to standard error on the terminal.	No
`syslog`	Logs to the local system log (where supported).	No
`daily_file`	Logs to a new file on a daily basis (according to local system time).	Yes
`file`	Logs to a specified file.	Yes

Example:

logging:
  mode: file
  path: /var/log/quantum_origin_sdk_log
  level: info

Note that the syslog option is not supported on the Windows implementation.

Logging Path¶

Some of the logging modes require the path to an output log file to be specified. In general, if a path is required but not specified, an error is raised.

Function: qosdk_setopt_str()

Option: QOSDK_OPT_LOGGING_FILENAME

Level	Description
`QOSDK_OPT_LOGGING_FILENAME`	Path to the output logfile. Typically, this will be a fully-qualified filename.

Example:

erc = qosdk_setopt_int(pQuantumOriginConfig, QOSDK_OPT_LOGGING_MODE, QOSDK_LOGMODE_DAILYFILE);
...
erc = qosdk_setopt_str(pQuantumOriginConfig, QOSDK_OPT_LOGGING_FILENAME, "quantum_origin_sdk_log.log");
...
erc = qosdk_setopt_int(pQuantumOriginConfig, QOSDK_OPT_LOGGING_LEVEL, QOSDK_LOGLEVEL_WARNING);
...

Level	Description
`path`	Path to the output logfile. Typically, this will be a fully-qualified filename.

Example:

logging:
  mode: file
  path: /var/log/quantum_origin_sdk_log
  level: info

Logging Level¶

Furthermore, the verbosity can also be specified as the following levels, in descending order of verbosity:

Function: qosdk_setopt_int()

Option: QOSDK_OPT_LOGGING_LEVEL

Level	Description
`QOSDK_LOGLEVEL_TRACE`	Trace level logging. Used for debugging. Not recommended for production use.
`QOSDK_LOGLEVEL_DEBUG`	Debugging information.
`QOSDK_LOGLEVEL_INFO`	Informational messages.
`QOSDK_LOGLEVEL_WARNING`	Warning messages.
`QOSDK_LOGLEVEL_ERROR`	Error messages.
`QOSDK_LOGLEVEL_CRITICAL`	Critical error messages.
`QOSDK_LOGLEVEL_NONE`	Turn off logging.

Example:

erc = qosdk_setopt_int(pQuantumOriginConfig, QOSDK_OPT_LOGGING_MODE, QOSDK_LOGMODE_DAILYFILE);
...
erc = qosdk_setopt_str(pQuantumOriginConfig, QOSDK_OPT_LOGGING_FILENAME, "quantum_origin_sdk_log.log");
...
erc = qosdk_setopt_int(pQuantumOriginConfig, QOSDK_OPT_LOGGING_LEVEL, QOSDK_LOGLEVEL_WARNING);
...

Level	Description
`trace`	Trace level logging. Used for debugging. Not recommended for production use.
`debug`	Debugging information.
`info`	Informational messages.
`warn`	Warning messages.
`err`	Error messages.
`critical`	Critical error messages.
`off`	Turn off logging.

Example:

logging:
  mode: file
  path: /var/log/quantum_origin_sdk_log
  level: info

It is strongly recommended to have the level set to info or warn.

Logging Callback¶

Quantum Origin SDK offers the ability to install a custom log handler. This is done by installing a Logging Callback function prior to instantiation of the Quantum Origin object. Once configured, this custom function will be called by Quantum Origin any time that a log entry is to be written.

The user-supplied function must conform to an exact set of parameters, calling convention, and return value. To assist with the correctness of the function definition and declaration, the quantum_origin/quantum_origin_sdk_c.h header includes a tQOSDK_LOGGER_CALLBACK_FN typedef. It is recommended that a function forward declaration of the form static tQOSDK_LOGGER_CALLBACK_FN my_logger_callback; is added to the top of the module in which the callback is implemented so as to ensure that the interface function is correctly defined.

The callback function may be called from multiple threads, so it should be thread safe.

The functions to register and de-register a callback function are qosdk_set_logging_callback() and qosdk_clear_logging_callback() respectively.

For example:

// Forward declaration to ensure that the interface function is correctly defined.
static tQOSDK_LOGGER_CALLBACK_FN my_logger_callback;

// Implementation
static void my_logger_callback(const tQOSDK_LOGLEVEL loglevel, const char *szMsg, size_t msgLen)
{
    // Store or present the inbound message somewhere.
    // ...
}
...

int main(int argc, char *argv[])
{
    ...
    // Initialize Quantum Origin Logging
    erc = qosdk_initialise_logging(QOSDK_LOGMODE_STDERR, QOSDK_LOGLEVEL_WARNING, NULL);
    if (erc)
    {
        const char *szQuantumOriginError = qosdk_get_error_description();
        fprintf(stderr, "ERROR: Failed to initialize logging (QuantumOriginError=%d: \"%s\")\n", erc, szQuantumOriginError?szQuantumOriginError:"Unspecified");
        return EXIT_FAILURE;
    }
    // Register a Quantum Origin Logging callback
    erc = qosdk_set_logging_callback(my_qo_logger_callback);
    if (erc)
    {
        const char *szQuantumOriginError = qosdk_get_error_description();
        fprintf(stderr, "ERROR: Failed to set logging callback (QuantumOriginError=%d: \"%s\")\n", erc, szQuantumOriginError?szQuantumOriginError:"Unspecified");
        return EXIT_FAILURE;
    }
    ...
}

Once configured and registered, Quantum Origin SDK will call this function at runtime for various errors, situations and events, with the logLevel parameter indicating the severity/priority of the event.

Examples include:

logger_callback(QOSDK_LOGLEVEL_ERR, ERC_QOSDK_UNSUPPORTED_OPTION, "Unsupported option for setopt_int", strlen("Unsupported option for setopt_int");
logger_callback(QOSDK_LOGLEVEL_ERR, ERC_QOSDK_EPARAM_CONFIG_PTR_NOT_SUPPLIED, "Null pointer received for config parameter");
logger_callback(QOSDK_LOGLEVEL_ERR, ERC_QOSDK_STD_EXCEPTION, "Generate randomness failed: Failed to retrieve WSR material");

The registering of a logging callback function is optional. If omitted, then the application must rely totally on the returned error codes from each function, and log entries are not persisted anywhere, although the log entries emitted from the underlying generator threads, will continue unaffected.

Logging callback functions cannot be configured using a configfile. It must be configured programmatically using the Quantum Origin API.

Local Source of Randomness (LSR/WSR)¶

This functionality is defined within the configuration file under the wsr field. WSR stands for “Weak Source of Randomness”, but is also commonly referred to as “Local Source of Randomness” or LSR. These two terms are functionally equivalent, but wsr is the keyword used in the configuration file.

The local source of randomness is the second critical input to generate Quantum Origin entropy.

Quantum Origin supports multiple sources of imperfect randomness that will be refined into quantum-hardened randomness. For systems running on either an Intel or an AMD CPU, the use of rdseed is recommended. For systems running under compliance regulations, the qo_jitter option is recommended. This option makes use of a version of jitter entropy enhanced with Quantum Origin, which is compliant with NIST SP 800-90b. Additional sources of randomness are available for use, but care must be taken to ensure that the local source of randomness contains a baseline level of randomness that Quantum Origin can process.

Function: qosdk_setopt_int()

Option: QOSDK_OPT_WSR_TYPE

SetOpt Option	Description	Requires `path`
`QOSDK_WSRTYPE_RDSEED`	Uses the Intel or AMD-provided RDSEED mechanism which is commonly available on many modern machines.	No
`QOSDK_WSRTYPE_QO_JITTER`	Uses a modified version of jitter entropy that includes Quantum Origin and is approved by various reputable bodies.	No
`QOSDK_WSRTYPE_JITTER`	Uses an external/user-supplied entropy source by specifying the path to a local shared library. Only available in Linux. Such a library can be built from the sources at: https://github.com/smuellerDD/jitterentropy-library	Yes
`QOSDK_WSRTYPE_FILE`	Uses a file-based source of randomness, such as `/dev/hw_random` or `/dev/hwrng`.	Yes
`QOSDK_WSRTYPE_CALLBACK_FUNCTION`	Uses a user-provided C function which can provide entropy on demand. The function should meet the requirements as specified in the Library page.	No

Example:

erc = qosdk_setopt_int  (pQuantumOriginConfig, QOSDK_OPT_WSR_TYPE, QOSDK_WSRTYPE_QO_JITTER    );

Or:

erc = qosdk_setopt_int  (pQuantumOriginConfig, QOSDK_OPT_WSR_TYPE, QOSDK_WSRTYPE_FILE         );
erc = qosdk_setopt_str  (pQuantumOriginConfig, QOSDK_OPT_WSR_PATH, "WsrRandomness_100kB.bin"  );

ConfigFile Option	Description	Requires `path`
`rdseed`	Uses the Intel or AMD-provided RDSEED mechanism which is commonly available on many modern machines.	No
`qo_jitter`	Uses a modified version of jitter entropy that includes Quantum Origin and is approved by various reputable bodies.	No
`jitter`	Uses an external/user-supplied entropy source by specifying the path to a local shared library. Only available in Linux. Such a library can be built from the sources at: https://github.com/smuellerDD/jitterentropy-library	Yes
`file`	Uses a file-based source of randomness, such as `/dev/hw_random` or `/dev/hwrng`.	Yes
`callback`	Uses a user-provided C function which can provide entropy on demand. The function should meet the requirements as specified in the Library page.	No

Example:

wsr:
   type: qo_jitter

See here for further details on the callback function.

User-defined local randomness sources must supply raw entropy as their output. These sources must not use pseudo-randomness as an input to the Quantum Origin process.

These functions use “stretching” algorithms, such as pseudo-random number generators (PRNGs), that take an initial set of entropy and use an algorithm to stretch it onto a longer set of outputs. An example of a PRNG is Intel/AMD’s RDRAND, which takes a raw set of randomness provided by the TRNG and uses a deterministic algorithm to generate additional data that mimics randomness.

For more information on qualifying your local randomness source, please contact Quantinuum support.

Warning

Do not use /dev/random or /dev/urandom as the PATH. These sources provide pseudo-randomness which should not be used as an input to Quantum Origin.

1. RDSEED (Recommended)¶

Entropy is obtained from the x86-64 CPU using the RDSEED instruction. CPUs that support the RDSEED instruction include:

AMD CPUs: Zen architecture (and later)
Intel CPUs: Broadwell architecture (and later)

WSR Parameter	Value
`TYPE`	`QOSDK_WSRTYPE_RDSEED`

WSR Parameter	Value
`TYPE`	`rdseed`

2. NIST Compliant CPU Jitter Entropy Containing Quantum Origin¶

NIST SP 800-90b compliant entropy is obtained by using this embedded Quantum Origin version of jitter entropy. This version first measures the small variations in the timing that the CPU takes to process instructions and then enhance this randomness with Quantum Origin. This is not a standard jitter file.

With all CPU jitter approaches, the timing is influenced by factors such as power, temperature, and on which other processes are being executed on the CPU. This approach is recommended for systems that require NIST validation and/or building into products looking to achieve FIPS, NIAP, or Common Criteria validation.

WSR Parameter	Value
`TYPE`	`QOSDK_WSRTYPE_QO_JITTER`

WSR Parameter	Value
`TYPE`	`qo_jitter`

3. CPU Jitter Entropy (Linux Only)¶

Entropy is obtained by measuring the small variations in the timing that the CPU takes to process instructions. This timing is influenced by factors such as power, temperature, and on which other processes are being executed on the CPU.

This approach is recommend for non-x86-64 CPUs or for CPUs that do not have access to a built in TRNG, including AMD or Intel CPUs that don’t support the RDSEED instruction.

WSR Parameter	Value
`TYPE`	`QOSDK_WSRTYPE_JITTER`
`PATH`	`/path/to/jitter/shared/library`

WSR Parameter	Value
`TYPE`	`jitter`
`PATH`	`/path/to/jitter/shared/library`

Note

Quantum Origin can use third-party shared object implementations of Jitterentropy as long as they are interface-compliant with v3.4.1. The end-user must generate a platform-appropriate shared object compliant with this interface (whether from their own code, verbatim from https://github.com/smuellerDD/jitterentropy-library or otherwise derived) and place it in a location accessible to the Quantum Origin SDK at runtime (with read permissions).

The path to this shared object (.so) file must be specified as the path parameter within the WSR section of the configuration file.

The steps required to build a local copy of the jitter entropy shared library are as shown below: (Prerequisites include: git, make, and a C/C++ tool chain)

git clone https://github.com/smuellerDD/jitterentropy-library.git
cd jitterentropy-library
make
sudo cp libjitterentropy.so.3.6.0 /usr/lib
sudo ln -fs /usr/lib/libjitterentropy.so.3.6.0 /usr/lib/libjitterentropy.so

4. Custom Hardware TRNG¶

Quantum Origin may be used with a custom TRNG provided by a third party such as through /dev/hwrng, from a TRM, legacy QRNG, or other available source of hardware randomness.

This custom hardware TRNG is not required, but may be used when a third party TRNG is already available on the system.

WSR Parameter	Value
`TYPE`	`QOSDK_WSRTYPE_FILE`
`PATH`	`/dev/<PATH_TO_TRNG>`

WSR Parameter	Value
`TYPE`	`file`
`PATH`	`/dev/<PATH_TO_TRNG>`

Note

Care must be taken to ensure that the third party TRNG provides raw entropy and is not using an expansion function such as a pseudo-random number generator (PRNG).

Please contact Quantinuum support for guidance when determining whether to use a custom TRNG and to qualify the device.

WSR Path¶

Some of the wsr types require the path to an input file (or device) to be specified. In general, if a path is required but not specified, an error is raised.

Function: qosdk_setopt_str()

Option: QOSDK_OPT_WSR_PATH

Level	Description
`QOSDK_OPT_WSR_PATH`	Path to the input file or device. Typically, this will be a fully-qualified filename.

Example:

...
erc = qosdk_setopt_int  (pQuantumOriginConfig, QOSDK_OPT_WSR_TYPE, QOSDK_WSRTYPE_FILE         );
...
erc = qosdk_setopt_str  (pQuantumOriginConfig, QOSDK_OPT_WSR_PATH, "/dev/<PATH_TO_TRNG>"      );
...

Level	Description
`path`	Path to the input file or device. Typically, this will be a fully-qualified filename.

Example:

wsr:
  type: FILE
  path: /dev/<PATH_TO_TRNG>

WSR Callback¶

Quantum Origin SDK offers the ability to install a custom function to supply the local source of randomness. This is done by installing a WSR Callback function prior to instantiation of the Quantum Origin object.

The user-supplied function must conform to an exact set of parameters, calling convention, and return value.

Once configured, this custom function will be called by Quantum Origin at any time that local randomness is required. A function prototype tQOSDK_RNG_GET_WSR_DATA_FN is supplied in the header file to make this easier.

Note that calling qosdk_setopt_wsr_callback() to set a callback function will also override any previous WSR-Type setting and force it to callback/QOSDK_WSRTYPE_CALLBACK_FUNCTION/WSRCALLBACK_FUNCTION.

The callback function may be called from multiple threads, so should be thread safe.

It is strongly recommended that a function forward declaration is added to the top of the module in which the callback is implemented so as to ensure that the interface function is correctly defined.

For example:

// Forward declaration
static tQOSDK_RNG_GET_WSR_DATA_FN my_qosdk_wsr_callback;

// Implementation
static int my_qosdk_wsr_callback(void *pUserData, unsigned char *pOutput, size_t outputLen)
{
    const size_t bytesRequested = outputLen;
    size_t bytesSupplied = 0;

    if (bytesRequested && pOutput)
    {
        for (size_t ii = 0; ii < bytesRequested; ii++)
        {
            // The call to rand() below is for illustration purposes only.
            // Typically the randomness is retrieved from a suitably good source or device.
            *pOutput = rand() & 0xFF;  // For illustration only.

            bytesSupplied++;
            pOutput++;
        }
    }

    if (pUserData)
    {
        tWSR_CALLBACK_USERDATA *pCallbackUserData = (tWSR_CALLBACK_USERDATA *)pUserData;
        pCallbackUserData->numberOfWsrRequests++;
        pCallbackUserData->numberOfBytesSupplied += (unsigned long)bytesSupplied;
        pCallbackUserData->lastError = ERC_QOSDK_OK;
        return ERC_QOSDK_OK;
    }
    return ERC_QOSDK_OK;
}
...

int main(int argc, char *argv[])
{
    ...
    erc = qosdk_setopt_int  (pQuantumOriginConfig, QOSDK_OPT_WSR_TYPE, QOSDK_WSRTYPE_CALLBACK_FUNCTION ); if (erc) { goto CleanupAndExit; }

    callbackUserData.numberOfWsrRequests = 0;
    callbackUserData.numberOfBytesSupplied = 0;
    callbackUserData.lastError = ERC_QOSDK_OK;

    erc = qosdk_setopt_wsr_callback(pQuantumOriginConfig, my_qosdk_wsr_callback, (void *)&callbackUserData); // Set the value of the WSR callback config option
    if (erc)
    {
        const char *szQuantumOriginError = qosdk_get_error_description();
        fprintf(stderr, "ERROR: Failed to install WSR callback (QuantumOriginError=%d: \"%s\")\n", erc, szQuantumOriginError?szQuantumOriginError:"Unspecified");
        goto CleanupAndExit;
    }
    ...
}

WSR callback functions cannot be configured using a configfile. It must be configured programmatically using the Quantum Origin API.

Notes: 1. The callback itself is implemented internally as a lambda function that calls the client function. If, at runtime, that client function returns a non-zero return value, an error string is thrown (“Failed to fetch {size} bytes from randomness source”). 2. The 1st param of qosdk_setopt_wsr_callback is an instance of tQOSDK_CONFIG * rather than of tQOSDK_CTX *. Due to the masked void * nature tQOSDK_CTX *, the compiler won’t complain this difference.

Inter-request Caching¶

This functionality is defined within the configuration file under the cache field.

Each Quantum Origin entropy generation cycle generates a fixed block-size of entropy depending on use-case and circumstance. In some situations, many small entropy requests - far smaller than a single block size - are required.

To avoid wasted cycles generating unused entropy, Quantum Origin can cache entropy between each request. This is called synchronous caching. Any excess entropy from a previous generation call will be used in the next call.

In other situations, immediate responsiveness is critical. For this, background/multithreaded caching can be used, this starts a new thread or threads that can independently generate entropy outside of direct requests. This generates a cache pool that can be immediately accessed on demand without further generation. The standard cache mechanisms can be significantly extended for almost any use case, if you require certain behavior, please contact Support.

Function: qosdk_setopt_int()

Option: QOSDK_OPT_CACHE_TYPE

Value	Description
`QOSDK_CACHETYPE_NONE`	Do not cache between each request.
`QOSDK_CACHETYPE_SYNCCACHING`	Cache excess entropy between requests, no new thread is used.
`QOSDK_CACHETYPE_CACHING`	Start a new thread to generate cached entropy in the background. Cache excess entropy. A new thread is used.
`QOSDK_CACHETYPE_MULTITHREAD`	Start multiple new threads to generate cached entropy in the background. Cache excess entropy.

Example:

erc = qosdk_setopt_int(pQuantumOriginConfig, QOSDK_OPT_CACHE_TYPE        , QOSDK_CACHETYPE_NONE);

Or:

...
erc = qosdk_setopt_int  (pQuantumOriginConfig, QOSDK_OPT_CACHE_TYPE      , QOSDK_CACHETYPE_CACHING );
...
erc = qosdk_setopt_int  (pQuantumOriginConfig, QOSDK_OPT_CACHE_SIZE      , 10240                   );
...
erc = qosdk_setopt_int  (pQuantumOriginConfig, QOSDK_OPT_CACHE_PREFILL   , 10240                   );
...
erc = qosdk_setopt_int  (pQuantumOriginConfig, QOSDK_OPT_CACHE_REFILL_AT , 2048                    );
...

Value	Description
`NONE`	Do not cache between each request.
`SYNCHRONOUS-CACHING`	Cache excess entropy between requests, no new thread is used.
`CACHING`	Start a new thread to generate cached entropy in the background. Cache excess entropy. A new thread is used.
`MULTITHREAD-CACHING`	Start multiple new threads to generate cached entropy in the background. Cache excess entropy.

Example:

cache:
  type: none

Or:

cache:
  type: caching
  prefill: 2048
  size: 2048
  refill_at: 1024

If caching is enabled, the size of the cache must be provided. A particularly useful cache size for synchronous caching is 3973 bytes, the size of a large block - this ensures no entropy is discarded.

Function: qosdk_setopt_int()

Option: QOSDK_OPT_CACHE_TYPE

SetOpt Option	Description
`QOSDK_OPT_CACHE_SIZE`	Total capacity of the cache in bytes.
`QOSDK_OPT_CACHE_PREFILL`	The amount of bytes to generate at startup prior to any randomness call being accepted. The cache will be filled to this level synchronously on initialisation even when using a background/multithreaded cache.
`QOSDK_OPT_CACHE_REFILL_AT`	The level below which refilling of the cache will be automatically triggered. Only used for synchronous caching. It does not apply to background/multithreaded cache which will always attempt to keep the cache filled to capacity.

Example:

...
erc = qosdk_setopt_int  (pQuantumOriginConfig, QOSDK_OPT_CACHE_TYPE      , QOSDK_CACHETYPE_CACHING );
...
erc = qosdk_setopt_int  (pQuantumOriginConfig, QOSDK_OPT_CACHE_SIZE      , 10240                   );
...
erc = qosdk_setopt_int  (pQuantumOriginConfig, QOSDK_OPT_CACHE_PREFILL   , 10240                   );
...
erc = qosdk_setopt_int  (pQuantumOriginConfig, QOSDK_OPT_CACHE_REFILL_AT , 2048                    );
...

ConfigFile Option	Description
`size`	Total capacity of the cache in bytes.
`prefill`	The amount of bytes to generate at startup prior to any randomness call being accepted. The cache will be filled to this level synchronously on initialisation even when using a background/multithreaded cache.
`refill_at`	The level below which refilling of the cache will be automatically triggered. Only used for synchronous caching. It does not apply to background/multithreaded cache which will always attempt to keep the cache filled to capacity.

Example:

cache:
  type: caching
  prefill: 2048
  size: 2048
  refill_at: 1024

Licensing and the Quantum Seed¶

This functionality is defined within the configuration file under the license field.

A license is required to authorize the use of Quantum Origin. This license is encrypted and digitally signed by Quantinuum and contains parameters such as the end-user organization, the dates during which the license is valid, the version of Quantum Origin, and the quantum seed.

The license code is provided as a base64 encoded string that must be supplied within the license section of the configuration file. The Quantum Origin software will read the configuration file, verify its signature with a public key, and decrypt the license code. Quantum Origin will log the details of the license to the configured log location. This will include debug information from the license code as well as the hash of the quantum seed for verification.

The quantum seed will never be output in logs.

Function: qosdk_setopt_bytes

Option: QOSDK_OPT_LICENSE_DATA

Parameter	Description
`QOSDK_OPT_LICENSE_DATA`	Pointer to an unsigned char array of raw license content (typically an array of bytes in hex format), and the size of the array.

Example:

#include "quantum_origin_license.h"
...

int main(int argc, char *argv[])
{
    ...
    printf("INFO: Size of License Content = %zu\n", sizeof(licenseContent)); // e.g. 8164
    erc = qosdk_setopt_bytes(pQuantumOriginConfig, QOSDK_OPT_LICENSE_DATA    , (uint8_t *)licenseContent, sizeof(licenseContent) );
    ...
}

License file e.g. “quantum_origin_license.h”:

static const unsigned char licenseContent[] = { // Byte array containing the license data.
                                                /* <Insert license data here> */
                                                /* e.g.
                                                0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0A, 0x0B, 0x0C, 0x0D, 0x0E, 0x0F,
                                                0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17, 0x18, 0x19, 0x1A, 0x1B, 0x1C, 0x1D, 0x1E, 0x1F,
                                                ...
                                                */
                                              };

Parameter	Description
`License`	The base64-encoded license content.

Example:

license: >
   hKllbmN...ZXEw+6KcA

The license is provided by Quantinuum alongside the C SDK. If you have questions about your license, please contact Quantinuum support for assistance.

Example Configuration¶

Sample config¶

logging:
  mode: file
  level: info
  path: /var/log/quantumorigin

cache:
  type: synchronous-caching
  size: 3973
  prefill: 1024
  refill_at: 1024

# The wsr section defines the second source of randomness that will
# be used by Quantum Origin.
wsr:
  type: RDSEED

# The license serves as authorisation, and also defines the
# Quantum Seed that is used by Quantum Origin.
# Evaluation licenses are also available.
# Please contact Quantinuum for a production/evaluation license(s).
license: >
  hK [omitted ...]