Usage Examples¶
Detailed SDK Specification and Sample Code¶
In general, the steps required to generate randomness using Quantum Origin are as follows:
Configure Quantum Origin, including logging, cache, Weak Source of Randomness (WSR), License with Quantum Seed and Operation mode.
Initialize Quantum Origin using the chosen parameters and configuration method.
Generate randomness as and when required.
Clean up.
As covered in the Usage section, the Quantum Origin SDK supports two approaches to configuration:
Using the SetOptions approach where the items are specified individually in code via the API prior to instantiation.
Using the ConfigFile approach where a configuration file on disk, the filename of which is passed to Quantum Origin during instantiation.
Both approaches are covered below.
Please see the Quantum Origin API Reference section for a detailed description of the Quantum Origin SDK API.
Some code snippets can be found below. However, sample code that is more complete is provided in the C SDK install package. Instructions to build the sample code can be found on the Sample Code page.
SetOptions Approach¶
As mentioned above, in the SetOptions approach, Quantum Origin is configured directly using the API, as opposed to using a config file on disk. This is the preferred method for most users, as it is more compact and is not dependent on a file system. However, the configuration is hard-coded, which may be more secure, but may not be suitable in situations where any of the config items may change frequently, or where the config items are not known at compile time.
In order to configure Quantum Origin, a tQOSDK_CONFIG object is created using the qosdk_setopt_init() function, and the configuration options are applied to this object using the qosdk_setopt functions in the Quantum Origin API.
There are several qosdk_setopt functions, each corresponding to a primary data type - for example: qosdk_setopt_int(), qosdk_setopt_str() and qosdk_setopt_bytes(). Each of these functions take a pointer to the tQOSDK_CONFIG object, a constant of which option to set, and the value to set it to. For example: QOSDK_OPT_WSR_TYPE and QOSDK_WSRTYPE_QO_JITTER, respectively.
Some of the configuration items are optional. For those that are optional and not specified, a default value is used. This is covered in more detail in the API document.
One of the mandatory items is the license. This field serves as authorization, defines the scope and mode of the product and also defines the Quantum Seed that is used by Quantum Origin. Licenses are supplied by Quantinuum and are unique and exclusive to each customer.
The license data is passed as a pointer to a block of raw data, which is typically supplied to each customer in the form of a C header file of the form:
/**
* Quantum Origin License Code:
* Contract ID: 1234567890123
* License ID: 12345678-9abc-def0-1234-567890abcdef
* Customer Name: Fred Bloggs Inc.
* Created At: 2024-08-15 11:59:30
* Created By: origin-support@quantinuum.com
* Point Of Contact: origin-support@quantinuum.com
* Restrictions:
* - Adaptors: SDK
* - Modes: normal
* Quantum Seed Hash:
* z4PhNX...DJ6faPg==
*/
static const unsigned char licenseContent_base64[] = { // Byte array containing the license data.
"hKllbmN...M+Qv"
};
static const unsigned char licenseContent[] = { // Byte array containing the license data.
0x84,0xa9,0x65,0x6e,0x63,...,0xa4,0x74,0x55,0xd7,0x33,0xe4,0x2f
};
With the tQOSDK_CONFIG object configured, the qosdk_init_from_config_struct() function is called to initialize Quantum Origin with the given configuration. This function returns a Quantum Origin SDK context, namely a pointer to a tQOSDK_CTX object.
At this point, the tQOSDK_CONFIG object is no longer required, and can be cleaned up with a call to the qosdk_setopt_cleanup() function.
The afore-mentioned tQOSDK_CTX context is used to make requests to Quantum Origin, most importantly, to qosdk_get_randomness() which takes a pointer to the tQOSDK_CTX object and the number of bytes of randomness requested.
The qosdk_get_randomness() function can be called as many times as required, re-using the tQOSDK_CTX object over multiple requests.
The tQOSDK_CTX object is cleaned up with a call to qosdk_destroy().
Code Snippet using the SetOptions Approach¶
The following code extract constructs a pQuantumOrigin object using a configuration structure in memory which is populated using various calls to the SetOptions API. The code also demonstrates the implementation of a Logging callback function.
This pQuantumOrigin object is then used to request 64 bytes of randomness using Quantum Origin SDK.
File |
Download |
|---|---|
Source |
ConfigFile Approach¶
In contrast to the SetOptions approach, Quantum Origin can be configured indirectly using a config file on disk. This is particularly useful in situations where any of the config items may need to change from time-to-time, or if they are not known at compile time.
In order to configure Quantum Origin, the various configuration options are specified in a YAML format configuration file, and the name of this file is specified using the Quantum Origin API.
The configuration file has the following form:
logging:
mode: file
level: info
path: /var/log/quantum_origin
cache:
type: synchronous-caching
size: 3973
prefill: 1024
refill_at: 1024
wsr:
type: qo_jitter
license: >
hKllbmNyeXB0ZWTFIOehkgbC[data omitted]Mzcvo2HYDomiXLA=
The license field is a block of base64 data and serves as authorization, defines the scope and mode of the product and also defines the Quantum Seed that is used by Quantum Origin. Licenses are supplied by Quantinuum and are unique and exclusive to each customer.
With the config file defined, the qosdk_init() function is called to initialize Quantum Origin with the given filename. This function returns a Quantum Origin SDK context, namely a pointer to a tQOSDK_CTX object.
This tQOSDK_CTX context is used to make requests to Quantum Origin, most importantly, to qosdk_get_randomness() which takes a pointer to the tQOSDK_CTX object and the number of bytes of randomness requested.
The qosdk_get_randomness() function can be called as many times as required, re-using the tQOSDK_CTX object over multiple requests.
The tQOSDK_CTX object is cleaned up with a call to qosdk_destroy().
Code Snippet using the ConfigFile Approach¶
The following code extract (simple_use_case_configfile_c.c) constructs a pQuantumOrigin object using parameters supplied in a YML ConfigFile. The code also demonstrates the implementation of a Logging callback function.
This pQuantumOrigin object is then used to request 64 bytes of randomness using Quantum Origin SDK.
At runtime, the code takes a config filename as a command line parameter, the values in which are used to configure Quantum Origin. The file config-sample-01.yml is an example of such a config file, which in this case is nested inside a child node.
Code snippet using the ConfigFile Approach¶ File
Download
Source
Config File