/** * @file quantum_origin_sdk_c.h * * Quantum Origin SDK C-Style API * * Quantum Origin is an entropy-enhancement engine, combining a Quantinuum-generated quantum seed with an end user's weak source of randomness to create * near-perfect randomness. Quantum Origin SDK forms the core of multiple Quantinuum and Quantum Origin products, as well as being available as a standalone, offline * library with a C++ or C interface. * * This header file defines the API of this C-Interface. */ #pragma once #include #ifndef ERC_QOSDK_OK #define ERC_QOSDK_OK 0 //!< Operation completed successfully #endif #ifndef ERC_QOSDK_UNSPECIFIED_ERROR #define ERC_QOSDK_UNSPECIFIED_ERROR 19999 //!< An unspecified error occurred #endif #define ERC_QOSDK_FLOOR 13800 //!< Base value for error codes used by the Quantum Origin SDK C-Style API #define ERC_QOSDK_EPARAM_CONFIG_FILENAME_NOT_SUPPLIED 13801 //!< A required configuration filename parameter was not supplied #define ERC_QOSDK_EPARAM_NODE_PATH_NOT_SUPPLIED 13802 //!< The required node-path parameter was not supplied #define ERC_QOSDK_EPARAM_CONFIG_PTR_NOT_SUPPLIED 13803 //!< The required configuration pointer parameter was not supplied #define ERC_QOSDK_EPARAM_QOSDK_CONTEXT_NOT_SUPPLIED 13804 //!< The required context pointer parameter was not supplied #define ERC_QOSDK_EPARAM_DEST_BUFFER_NOT_SUPPLIED 13805 //!< The required destination buffer output parameter was not supplied #define ERC_QOSDK_EPARAM_BYTES_RETURNED_PTR_NOT_SUPPLIED 13806 //!< The required byte-count output parameter was not supplied #define ERC_QOSDK_EPARAM_VALUE_PTR_NOT_SUPPLIED 13807 //!< The required config value parameter was not supplied #define ERC_QOSDK_FAILED_TO_ASSIGN_SEED_SIGNATURE 13808 //!< Setting the seed signature failed #define ERC_QOSDK_FAILED_TO_ASSIGN_SEED_CONTENT 13809 //!< Setting the seed content failed #define ERC_QOSDK_UNSUPPORTED_OPTION 13810 //!< The attempted action is not supported #define ERC_QOSDK_STD_EXCEPTION 13811 //!< A standard exception occurred, see error string for more details #define ERC_QOSDK_UNKNOWN_EXCEPTION 13812 //!< An unknown exception occurred #define ERC_QOSDK_EPARAM_CALLBACK_PTR_NOT_SUPPLIED 13813 //!< The required callback function parameter was not supplied #define ERC_QOSDK_EPARAM_VSNPRINTF 13814 //!< An error occurred whilst using vsnprintf #define ERC_QOSDK_EPARAM_MSG_BUFFER_NOT_SUPPLIED 13815 //!< The required message buffer was not supplied #define ERC_QOSDK_FAILED_TO_ASSIGN_LICENSE_CONTENT 13816 //!< Setting the license content failed #define ERC_QOSDK_EPARAM_INVALID_SIZE 13817 //!< Size parameter is not valid #define ERC_QOSDK_EPARAM_INVALID_CACHETYPE 13818 //!< Invalid or unsupported Cache Type #define ERC_QOSDK_EPARAM_HEALTH_TESTS_NOT_SUPPORTED 13819 //!< Health tests are not supported in this version #define ERC_QOSDK_EPARAM_INVALID_LOGLEVEL 13820 //!< Invalid or unsupported Log Level #define ERC_QOSDK_EPARAM_INVALID_LOGMODE 13821 //!< Invalid or unsupported Log Mode #define ERC_QOSDK_EPARAM_INVALID_WSRTYPE 13822 //!< Invalid or unsupported WSR Type #define ERC_QOSDK_EPARAM_INVALID_OPERATIONMODE 13823 //!< Invalid or unsupported Operational Mode #define ERC_QOSDK_FAILED_TO_INITIALISE_LOGGING 13824 //!< Failed to initialise logging subsystem #define ERC_QOSDK_PLATFORM_NOT_SUPPORTED 13825 //!< Platform not supported #define ERC_QOSDK_FAILED_TO_SET_LOGGING_CALLBACK 13826 //!< Failed to initialise logging subsystem #define ERC_QOSDK_ADAPTIVE_PROPORTION_HEALTH_TEST_FAILURE 13827 //!< Adaptive proportion health test on WSR randomness failed #define ERC_QOSDK_REPETITION_COUNT_HEALTH_TEST_FAILURE 13828 //!< Repetition count health test on WSR randomness failed #define ERC_QOSDK_OUTPUT_ADAPTIVE_PROPORTION_HEALTH_TEST_FAILURE 13829 //!< Adaptive proportion health test on output randomness failed #define ERC_QOSDK_OUTPUT_REPETITION_COUNT_HEALTH_TEST_FAILURE 13830 //!< Repetition count health test on output randomness failed #define ERC_QOSDK_TIMEOUT_WAITING_FOR_RANDOMNESS 13831 //!< Timed out waiting for background threads to generate randomness #ifdef __cplusplus extern "C" { #endif /////////////////////////////////////////////////////////////////////////////// // Note that all enum entries here are given explicit values so that, even if // one gets deprecated or removed, then the external, customer-facing API // remains unchanged. /////////////////////////////////////////////////////////////////////////////// /** * @enum tQOSDK_WSRTYPE * @brief Enum of the supported WSR types as passed to qosdk_setopt_int(pQuantumOriginConfig, QOSDK_OPT_WSR_TYPE, QOSDK_WSRTYPE_RDSEED ); * * Quantum Origin works by combining two sources of randomness in a very particular way - sometimes called amplification. * The primary source of randomness being fed into the Quantum Origin extractor is a Quantum seed. A WSR (Weak Source of Randomness) is the name given to the * secondary source of randomness. The term "weak", as used here, is relative - specifically relative to the near-perfect randomness produced from a Quantum process. * * The desired second source of randomness can be set using a call to qosdk_setopt_int(), specifying * the QOSDK_OPT_WSR_TYPE option and the appropriate type selected from this enum. * Some types may require additional parameters as mentioned below. * * For example: * @code * ... * tQOSDK_CONFIG *pQuantumOriginConfig = NULL; * tQOSDK_RESULT erc = ERC_QOSDK_UNSPECIFIED_ERROR; * * pQuantumOriginConfig = qosdk_setopt_init(); * ASSERT_NE(pQuantumOriginConfig, NULL) * ... * erc = qosdk_setopt_int(pQuantumOriginConfig, QOSDK_OPT_WSR_TYPE, QOSDK_WSRTYPE_RDSEED); * if (erc != ERC_QOSDK_OK) { Report and process error as needed } * ... * pQuantumOrigin = qosdk_init_from_config_struct(pQuantumOriginConfig); * if (pQuantumOrigin == NULL) { Report and process error as needed } * * // The config structure is no longer needed, and can be destroyed. * qosdk_setopt_cleanup(pQuantumOriginConfig); * pQuantumOriginConfig = NULL; * ... * @endcode */ typedef enum tQOSDK_WSRTYPE { QOSDK_WSRTYPE_RDSEED = 0, //!< Use weak randomness obtained from Intel's RDSEED instruction QOSDK_WSRTYPE_FILE = 1, //!< Read weak randomness from a file (which can be a device such as /dev/urandom). The filename itself needs to be supplied using a //!< call to qosdk_setopt_str() with parameter QOSDK_OPT_LOGGING_FILENAME. QOSDK_WSRTYPE_CALLBACK_FUNCTION = 2, //!< Obtain weak randomness by calling a callback function. A pointer to a callback function of type //!< tQOSDK_RNG_GET_WSR_DATA_FN needs to be supplied using the qosdk_setopt_wsr_callback() function. QOSDK_WSRTYPE_JITTER = 3, //!< Obtain weak randomness by calling a dynamically loaded jitterentropy library. //!< The library filename needs to be provided via QOSDK_OPT_WSR_PATH QOSDK_WSRTYPE_QO_JITTER = 4, //!< Obtain weak randomness from the internal QO Jitter module. } tQOSDK_WSRTYPE; /** * @typedef QuantumOriginWSRType * @see tQOSDK_WSRTYPE */ typedef tQOSDK_WSRTYPE QuantumOriginWSRType; /** * @typedef tQOSDK_OPMODE * @brief Enum of the available runtime operation modes of Quantum Origin * * Quantum Origin SDK can be provided in evaluation mode whereby Quantum Origin runs and generates entropy containing only NULLS. * If a customer license is for evaluation mode only, then qosdk_setopt_int() must be called in the configuration setup, specifying * the QOSDK_OPT_OPERATION_MODE option with the QOSDK_OPMODE_ALLZEROS value. * * Otherwise specifying the operational mode is optional and the mode defaults to normal run time operation i.e. Quantum Origin generates provably random * quantum-derived entropy */ typedef enum tQOSDK_OPMODE { QOSDK_OPMODE_NORMAL = 0, //!< Quantum Origin operates in normal mode QOSDK_OPMODE_ALLZEROS = 1, //!< Quantum Origin operates in evaluation mode. In this mode no genuine entropy is generated. All generated entropy will contain only NULLs. } tQOSDK_OPMODE; /** * @typedef QuantumOriginOPMode * @see tQOSDK_OPMODE */ typedef tQOSDK_OPMODE QuantumOriginOPMode; /** * @enum tQOSDK_CACHETYPE * @brief Enum of the available mechanisms available for the internal caching of randomness. * * Enabling the internal caching of randomness can have a significant positive effect on performance, but may have some * security implications in some situations. * The Quantum Origin randomness extractor produces, on demand, randomness in blocks. It is common that, after providing the * amount of randomness requested, there are some bytes remaining. These could be discarded (No caching) or held in memory * and be available for, or towards, a subsequent request. * The potential down-side of this is that the randomness supplied in a second or subsequent call could potentially have * been in memory since a previous request. * * The desired caching mechanism can be set using a call to qosdk_setopt_int(), specifying * the QOSDK_OPT_CACHE_TYPE option and the appropriate type selected from this enum. * * For example: * @code * ... * tQOSDK_CONFIG *pQuantumOriginConfig = NULL; * tQOSDK_RESULT erc = ERC_QOSDK_UNSPECIFIED_ERROR; * * pQuantumOriginConfig = qosdk_setopt_init(); * ASSERT_NE(pQuantumOriginConfig, NULL) * ... * erc = qosdk_setopt_int(pQuantumOriginConfig, QOSDK_OPT_CACHE_TYPE, QOSDK_CACHETYPE_NONE); * if (erc != ERC_QOSDK_OK) { Report and process error as needed } * ... * pQuantumOrigin = qosdk_init_from_config_struct(pQuantumOriginConfig); * if (pQuantumOrigin == NULL) { Report and process error as needed } * * // The config structure is no longer needed, and can be destroyed. * qosdk_setopt_cleanup(pQuantumOriginConfig); * pQuantumOriginConfig = NULL; * ... * @endcode */ typedef enum tQOSDK_CACHETYPE { QOSDK_CACHETYPE_NONE = 0, //!< Disable caching of randomness QOSDK_CACHETYPE_CACHING = 1, //!< Cache randomness using a cache filled asynchronously by a background thread QOSDK_CACHETYPE_SYNCCACHING = 2, //!< Cache randomness uses a cache that is filled synchronously when a randomness request is made QOSDK_CACHETYPE_MULTITHREAD = 3, //!< Cache randomness using a cache filled asynchronously by multiple background threads } tQOSDK_CACHETYPE; /** * @typedef QuantumOriginCacheType * @see tQOSDK_CACHETYPE */ typedef tQOSDK_CACHETYPE QuantumOriginCacheType; /** * @enum tQOSDK_LOGMODE * @brief Enum of the supported logging modes i.e. the location or subsystem to where log entries are written. * * The system outputs various log entries as determined by the configured log level. * These log entries are written to a logging "destination". * The supported destinations include the console (stdout or stderr), the operating * system's internal logging subsystem (syslog), a file (file or dailyfile) or to simply * inherit the setting from a parent's instance of spdlog settings. * * The desired mode of logging can be set using a call to qosdk_setopt_int(), specifying * the QOSDK_OPT_LOGGING_MODE option and the appropriate mode selected from this enum. * Some modes may require additional parameters as mentioned below. * @see tQOSDK_LOGLEVEL * * For example: * @code * ... * tQOSDK_CONFIG *pQuantumOriginConfig = NULL; * tQOSDK_RESULT erc = ERC_QOSDK_UNSPECIFIED_ERROR; * * pQuantumOriginConfig = qosdk_setopt_init(); * ASSERT_NE(pQuantumOriginConfig, NULL) * ... * erc = qosdk_setopt_int(pQuantumOriginConfig, QOSDK_OPT_LOGGING_MODE, QOSDK_LOGMODE_DAILYFILE); * if (erc != ERC_QOSDK_OK) { Report and process error as needed } * erc = qosdk_setopt_int(pQuantumOriginConfig, QOSDK_OPT_LOGGING_FILENAME, "mylogfile.log"); * if (erc != ERC_QOSDK_OK) { Report and process error as needed } * ... * pQuantumOrigin = qosdk_init_from_config_struct(pQuantumOriginConfig); * if (pQuantumOrigin == NULL) { Report and process error as needed } * * // The config structure is no longer needed, and can be destroyed. * qosdk_setopt_cleanup(pQuantumOriginConfig); * pQuantumOriginConfig = NULL; * ... * @endcode */ typedef enum tQOSDK_LOGMODE { QOSDK_LOGMODE_STDOUT = 0, //!< Send logging to the console via stdout. QOSDK_LOGMODE_STDERR = 1, //!< Send logging to the console via stderr. QOSDK_LOGMODE_SYSLOG = 2, //!< Send logging to syslog. QOSDK_LOGMODE_DAILYFILE = 3, //!< Send logging to a file, rotating the file each day. The name of the file is set using QOSDK_OPT_LOGGING_FILENAME QOSDK_LOGMODE_FILE = 4, //!< Send logging to a file. The name of the logfile needs to be supplied using QOSDK_OPT_LOGGING_FILENAME. QOSDK_LOGMODE_INHERIT = 5, //!< Inherit logging settings from parent application (will use whichever logger is configured as spdlog default) #ifdef _WIN32 QOSDK_LOGMODE_WINEVTLOG = 6, //!< Send logging to the Windows EventLog #endif } tQOSDK_LOGMODE; /** * @typedef QuantumOriginLoggingMode * @see tQOSDK_LOGMODE */ typedef tQOSDK_LOGMODE QuantumOriginLoggingMode; /** * @enum tQOSDK_LOGLEVEL * @brief Enum of the supported logging levels, which are used to control the amount of logging detail that is output. * * The system outputs various log entries which are categorised into "levels". * These levels range from Critical, through Error, Warning, Informative and debugging. * The desired level of output can be set using a call to qosdk_setopt_int(), specifying * the QOSDK_OPT_LOGGING_LEVEL option and the appropriate level selected from this enum. * * @see tQOSDK_LOGMODE * * For example: * @code * ... * tQOSDK_CONFIG *pQuantumOriginConfig = NULL; * tQOSDK_RESULT erc = ERC_QOSDK_UNSPECIFIED_ERROR; * * pQuantumOriginConfig = qosdk_setopt_init(); * ASSERT_NE(pQuantumOriginConfig, NULL) * ... * erc = qosdk_setopt_int(pQuantumOriginConfig, QOSDK_OPT_LOGGING_LEVEL, QOSDK_LOGLEVEL_WARNING); * if (erc != ERC_QOSDK_OK) { Report and process error as needed } * ... * pQuantumOrigin = qosdk_init_from_config_struct(pQuantumOriginConfig); * if (pQuantumOrigin == NULL) { Report and process error as needed } * * // The config structure is no longer needed, and can be destroyed. * qosdk_setopt_cleanup(pQuantumOriginConfig); * pQuantumOriginConfig = NULL; * ... * @endcode */ typedef enum tQOSDK_LOGLEVEL { QOSDK_LOGLEVEL_NONE = 0, //!< No logging QOSDK_LOGLEVEL_OFF = 0, //!< No logging (same as QOSDK_LOGLEVEL_NONE) QOSDK_LOGLEVEL_CRITICAL = 1, //!< Log only critical errors QOSDK_LOGLEVEL_CRIT = 1, //!< Log only critical errors (same as QOSDK_LOGLEVEL_CRITICAL) QOSDK_LOGLEVEL_ERROR = 2, //!< Log all errors, including critical errors QOSDK_LOGLEVEL_ERR = 2, //!< Log all errors (same as QOSDK_LOGLEVEL_ERROR) QOSDK_LOGLEVEL_WARNING = 3, //!< Log warnings, errors and critical errors QOSDK_LOGLEVEL_WARN = 3, //!< Log warnings (same as QOSDK_LOGLEVEL_WARNING) QOSDK_LOGLEVEL_INFO = 4, //!< Log informative messages, warnings, errors and critical errors QOSDK_LOGLEVEL_DEBUG = 5, //!< Log debug messages, as well as all info, warning and error messages QOSDK_LOGLEVEL_TRACE = 6, //!< Log detailed trace messages, as well as all debug messages, warnings and errors } tQOSDK_LOGLEVEL; /** * @typedef QuantumOriginLoggingVerbosity * @see tQOSDK_LOGLEVEL */ typedef tQOSDK_LOGLEVEL QuantumOriginLoggingVerbosity; /** * @enum tQOSDK_OPTID * @brief Enum of supported Option IDs which are used to programmatically configure Quantum Origin SDK. * * Quantum Origin SDK can be configured in various ways, including via a config file on disk, and via options * specified programmatically by an application using the qosdk_setopt_xxx set of functions. * The values in this enum are used to specify which of the various settings to change programmatically. * Typically, an application will initialise a Quantum Origin context with a call to qosdk_setopt_init(), and then * call one or more of the qosdk_setopt_[string|int|bytes]() functions with the appropriate Option ID to * configure each particular setting. * * For example: * @code * ... * tQOSDK_CONFIG *pQuantumOriginConfig = NULL; * tQOSDK_RESULT erc = ERC_QOSDK_UNSPECIFIED_ERROR; * * pQuantumOriginConfig = qosdk_setopt_init(); * ASSERT_NE(pQuantumOriginConfig, NULL) * ... * erc = qosdk_setopt_str(pQuantumOriginConfig, QOSDK_OPT_LOGGING_FILENAME, "mylogfile.log"); * if (erc != ERC_QOSDK_OK) { Report and process error as needed } * erc = qosdk_setopt_int(pQuantumOriginConfig, QOSDK_OPT_CACHE_SIZE, 2048); * if (erc != ERC_QOSDK_OK) { Report and process error as needed } * erc = qosdk_setopt_bytes(pQuantumOriginConfig, QOSDK_OPT_SEED_SIGNATURE, seedSignature.data(), seedSignature.size()); * if (erc != ERC_QOSDK_OK) { Report and process error as needed } * ... * pQuantumOrigin = qosdk_init_from_config_struct(pQuantumOriginConfig); * if (pQuantumOrigin == NULL) { Report and process error as needed } * * // The config structure is no longer needed, and can be destroyed. * qosdk_setopt_cleanup(pQuantumOriginConfig); * pQuantumOriginConfig = NULL; * ... * @endcode */ typedef enum tQOSDK_OPTID { QOSDK_OPT_LOGGING_FILENAME = 0, //!< String. The fully qualified logging filename. QOSDK_OPT_LOGGING_LEVEL = 1, //!< Numeric. One of the values in the tQOSDK_LOGLEVEL enum. QOSDK_OPT_LOGGING_MODE = 2, //!< Numeric. One of the values in the tQOSDK_LOGMODE enum. QOSDK_OPT_CACHE_TYPE = 3, //!< Numeric. One of the values in the tQOSDK_CACHETYPE enum. QOSDK_OPT_CACHE_SIZE = 4, //!< Numeric. The size of the cache in bytes. QOSDK_OPT_CACHE_PREFILL = 5, //!< Numeric. The "high water mark" of the cache. Filling stops when the level exceeds this value. QOSDK_OPT_CACHE_REFILL_AT = 6, //!< Numeric. The "low water mark" of the cache. Filling resumes when the level falls below this value. QOSDK_OPT_WSR_TYPE = 7, //!< Numeric. The type of WSR used. The value is one of the values from the tQOSDK_WSRTYPE enum. QOSDK_OPT_WSR_PATH = 8, //!< String. The path to the WSR source. QOSDK_OPT_HEALTH_TESTS_OUTPUT = 9, //!< Numeric (Boolean). Whether the output health tests are run. QOSDK_OPT_SEED_SIGNATURE = 10, //!< Byte array containing the seed signature. QOSDK_OPT_SEED_CONTENT = 11, //!< Byte Array containing the seed itself. QOSDK_OPT_CACHE_THREAD_COUNT = 12, //!< Numeric. The number of threads servicing the cache. QOSDK_OPT_LICENSE_DATA = 13, //!< Byte array containing the license data. QOSDK_OPT_SEED_SIGNING_KEY = 14, //!< String containing the PEM-encoded seed signing key. QOSDK_OPT_OPERATION_MODE = 15, //!< Set operation mode of Quantum Origin. QOSDK_OPT_HEALTH_TESTS_DISABLED = 16, //!< Numeric (Boolean). Whether the health tests are disabled. QOSDK_OPT_HEALTH_TESTS_MAX_RETRY_COUNT = 17, //!< Numeric. The number of times to retry if health tests are failing. Leave unset to retry indefinitely. QOSDK_OPT_HEALTH_TESTS_RETRY_DELAY = 18, //!< Numeric. The initial delay between retry attempts in milliseconds. QOSDK_OPT_HEALTH_TESTS_RETRY_MULTIPLIER = 19, //!< Float. The multiplier for the delay each time we back off. QOSDK_OPT_HEALTH_TESTS_RETRY_DELAY_MAX = 20, //!< Numeric. The maximum delay between retry attempts in milliseconds. QOSDK_OPT_CACHE_TIMEOUT = 21, //!< Numeric. Number of milliseconds to wait for randomness from the cache before failing. } tQOSDK_OPTID; /** * @typedef QOSDK_OPT_ID * @see tQOSDK_OPTID */ typedef tQOSDK_OPTID QOSDK_OPT_ID; typedef enum tQOSDK_WSR_CB_ERRCODE { QOSDK_WSR_CB_SUCCESS = 0, //!< Operation completed successfully QOSDK_WSR_CB_FLOOR = 41000, //!< Base value for error codes returned by a user-define WSR callback function QOSDK_WSR_CB_RESULT_ENOMEM_OUT_OF_MEMORY = 41010, //!< ERROR: Memory allocation for object failed QOSDK_WSR_CB_RESULT_EPARAM_NO_BUFFER_SUPPLIED = 41020, //!< ERROR: Ptr to destination buffer is NULL QOSDK_WSR_CB_RESULT_EPARAM_NO_USERDATA = 41021, //!< ERROR: Ptr to UserData is NULL QOSDK_WSR_CB_RESULT_EINVAL_INVALID_SIZE = 41022, //!< ERROR: Invalid size of object QOSDK_WSR_CB_RESULT_EINVAL_INVALID_FUNCTIONPTR = 41023, //!< ERROR: Function pointer is NULL QOSDK_WSR_CB_RESULT_ERANGE_OUT_OF_RANGE = 41024, //!< ERROR: Value is out of range QOSDK_WSR_CB_RESULT_ENOINIT_NOT_INITIALISED = 41030, //!< ERROR: Subsystem/device is not initialized QOSDK_WSR_CB_RESULT_FAILED_TO_OPEN_RANDOM_SOURCE = 41040, //!< ERROR: Failed to open randomness source QOSDK_WSR_CB_RESULT_FAILED_TO_READ_RANDOM_SOURCE = 41045, //!< ERROR: Failed to read from randomness source QOSDK_WSR_CB_RESULT_FAILED_TO_RETRIEVE_WSR_MATERIAL = 41050, //!< ERROR: Failed to retrieve WSR material QOSDK_WSR_CB_RESULT_UNSPECIFIED_ERROR = 41099 //!< ERROR: Unspecified error } tQOSDK_WSR_CB_ERRCODE; /** * @typedef QuantumOriginWsrCallbackErrorCode * @see tQOSDK_WSR_CB_ERRCODE */ typedef tQOSDK_WSR_CB_ERRCODE QuantumOriginWsrCallbackErrorCode; /** * tQOSDK_RESULT : Quantum Origin SDK numeric return/error code. * * An enum of Quantum Origin SDK numeric error codes as returned from various API functions. * For completeness, this enum includes an entry for 'success', namely ERC_QOSDK_OK, with value zero. * The most recent error code can also be retrieved with a call to qosdk_get_error_code(). * The qosdk_get_error_description() function can be called to help determine the nature/cause of a specific failure. */ typedef int tQOSDK_RESULT; /** * tQOSDK_CTX : Quantum Origin SDK object/context. * * A pointer to a Quantum Origin SDK object (tQOSDK_CTX *) is passed * to most API functions in order to identify the object context. */ typedef void tQOSDK_CTX; /** * tQOSDK_CONFIG : A structure containing the active configuration values. * * The internals of this structure are subject to change without notice and thus should not be accessed directly. */ typedef struct QuantumOriginConfig tQOSDK_CONFIG; /** * tQOSDK_RNG_GET_WSR_DATA_FN_PTR : A callback function for providing a weak source of randomness. * * Notes: * 1. This callback may be called from multiple threads, so should be thread safe. * 2. It is recommended that a forward declaration of the form... * static tQOSDK_RNG_GET_WSR_DATA_FN my_wsr_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. * * For example: * @code * ... * static tQOSDK_RNG_GET_WSR_DATA_FN my_wsr_callback; * static int my_wsr_callback(void *pUserData, unsigned char *pOutput, size_t outputLen) * { * // Store outputLen bytes of randomness to the buffer pointed to by pOutput. * return ERC_QOSDK_OK; * } * ... * @endcode * * @param pUserData Pointer to arbitrary user-specified data. * @param pOutput Pointer to the memory location that will receive the randomness. * @param outputLen The amount of randomness that is being requested. * * @return Must return ERC_QOSDK_OK (zero) on success, or any other value on failure. */ typedef int(tQOSDK_RNG_GET_WSR_DATA_FN)(void *pUserData, unsigned char *pOutput, size_t outputLen); typedef tQOSDK_RNG_GET_WSR_DATA_FN *tQOSDK_RNG_GET_WSR_DATA_FN_PTR; /** * tQOSDK_LOGGER_CALLBACK_FN : A typedef of a logging callback function that will assist * with the correctness of the function definition and declaration. * * Notes: * 1. This callback may be called from multiple threads, so should be thread safe. * 2. It is 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: * @code * ... * // Forward declaration * 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. * } * ... * @endcode * * @param loglevel The severity of the log entry. The value is one of those in tQOSDK_LOGLEVEL. * @param szMsg The null-terminated error message. * @param msgLen The length of the error message (excluding the null-terminator). * * @return void */ typedef void(tQOSDK_LOGGER_CALLBACK_FN)(const tQOSDK_LOGLEVEL loglevel, const char *szMsg, size_t msgLen); typedef tQOSDK_LOGGER_CALLBACK_FN *tQOSDK_LOGGER_CALLBACK_FN_PTR; /** * qosdk_init_from_config_file() : Initialize a QO SDK context from a config file. * * @param szConfigFilename A null terminated string specifying the relative or absolute path to the configuration file. * @param szNodePath A null terminated string specifying the parent yaml node under which the configuration exists e.g. "", "/" or "generator". * * @return On success, returns a ptr to a Quantum Origin context. This is used and required for various other calls to the Quantum Origin API. * On error, returns NULL. A call to qosdk_get_error_description() and qosdk_get_error_code() can be called to determine the nature/cause of the failure. */ extern tQOSDK_CTX *qosdk_init_from_config_file(const char *szConfigFilename, const char *szNodePath); /** * qosdk_init_from_config_struct() : Initialize a Quantum Origin context from a config struct. * * NOTE: All calls to the required setopt functions must be made prior to calling this function. * Any subsequent calls to setopt functions after a call to qosdk_init_from_config_struct() will have no effect. * * @param pQuantumOriginConfig A pointer to a Quantum Origin config struct as returned from a call to qosdk_setopt_init() and modified as required with calls to * any of qosdk_setopt_int(), qosdk_setopt_str(), qosdk_setopt_bytes() and qosdk_setopt_wsr_callback() functions. * * @return On success, returns a pointer to a Quantum Origin context. * On error, returns NULL. A call to qosdk_get_error_description() and qosdk_get_error_code() can be called to determine the nature/cause of the failure. */ extern tQOSDK_CTX *qosdk_init_from_config_struct(const tQOSDK_CONFIG *pQuantumOriginConfig); /** * qosdk_setopt_init() : Initialize a Quantum Origin config to be used in the Quantum Origin "setopt" set-up calls. * * @return On success, a pointer an internal config context is returned. * On error, returns NULL. The only cause for a potential failure is an out-of-memory condition. */ extern tQOSDK_CONFIG *qosdk_setopt_init(void); /** * qosdk_setopt_bytes() : Set the value of a config option whose type is bytes_t (std::vector). * * This does a deep copy of the data pointed to by pValue to the underlying std:vector using the assign method. * Consequently, the data at pValue is not required after this call, and may be destroyed or reused. * * @param pQuantumOriginConfig A pointer to a Quantum Origin config struct as returned from a call to qosdk_setopt_init(), containing values required to initialise a * Quantum Origin context * @param option An QOSDK_OPT_ID enum for a config option whose type is byte. * @param pValue A pointer to the value to which the specified option is set. * @param cbValue The number of bytes of the value. * * @return On success, returns ERC_QOSDK_OK. * On error, returns an error code identifying the problem. * The functions qosdk_get_error_description() and qosdk_get_error_code() can be called to help determine the nature/cause of the failure. */ extern tQOSDK_RESULT qosdk_setopt_bytes(tQOSDK_CONFIG *pQuantumOriginConfig, tQOSDK_OPTID option, unsigned char *pValue, size_t cbValue); /** * qosdk_setopt_str() : Set the value of a config option whose type is a string (char*). * * @param pQuantumOriginConfig A pointer to a Quantum Origin config struct as returned from a call to qosdk_setopt_init(), containing values required to initialise a * Quantum Origin context * @param option An QOSDK_OPT_ID enum for a config option whose type is string. * @param szValue A pointer to a null terminated string value to which the specified option is set. * * @return On success, returns ERC_QOSDK_OK. * On error, returns an error code identifying the problem. * The functions qosdk_get_error_description() and qosdk_get_error_code() can be called to help determine the nature/cause of the failure. */ extern tQOSDK_RESULT qosdk_setopt_str(tQOSDK_CONFIG *pQuantumOriginConfig, tQOSDK_OPTID option, const char *szValue); /** * qosdk_setopt_int() : Set the value of a config option whose type is an int. * * @param pQuantumOriginConfig A pointer to a Quantum Origin config struct as returned from a call to qosdk_setopt_init(), containing values required to initialise a * Quantum Origin context * @param option An QOSDK_OPT_ID enum for a config option whose type is int. * @param value The value to which the specified option is set. * * @return On success, returns ERC_QOSDK_OK. * On error, returns an error code identifying the problem. * The functions qosdk_get_error_description() and qosdk_get_error_code() can be called to help determine the nature/cause of the failure. */ extern tQOSDK_RESULT qosdk_setopt_int(tQOSDK_CONFIG *pQuantumOriginConfig, tQOSDK_OPTID option, size_t value); /** * qosdk_setopt_float() : Set the value of a config option whose type is a float. * * @param pQuantumOriginConfig A pointer to a Quantum Origin config struct as returned from a call to qosdk_setopt_init(), containing values required to initialise a * Quantum Origin context * @param option An QOSDK_OPT_ID enum for a config option whose type is float. * @param value The value to which the specified option is set. * * @return On success, returns ERC_QOSDK_OK. * On error, returns an error code identifying the problem. * The functions qosdk_get_error_description() and qosdk_get_error_code() can be called to help determine the nature/cause of the failure. */ extern tQOSDK_RESULT qosdk_setopt_float(tQOSDK_CONFIG *pQuantumOriginConfig, tQOSDK_OPTID option, float value); /** * qosdk_setopt_wsr_callback() : Set the value of the WSR callback config option * * @param pQuantumOriginConfig A pointer to a Quantum Origin config struct as returned from a call to qosdk_setopt_init(), containing values required to initialise a * Quantum Origin context * @param pWSRCallbackFn A pointer to the callback function which can supply the secondary source of randomness. * @param pUserData Point to arbitrary user-specified data (will be passed on to the callback function) * * @return On success, returns ERC_QOSDK_OK. * On error, returns an error code identifying the problem. * The functions qosdk_get_error_description() and qosdk_get_error_code() can be called to help determine the nature/cause of the failure. * * 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. */ extern tQOSDK_RESULT qosdk_setopt_wsr_callback(tQOSDK_CONFIG *pQuantumOriginConfig, tQOSDK_RNG_GET_WSR_DATA_FN_PTR pWSRCallbackFn, void *pUserData); /** * qosdk_setopt_cleanup() : Clean up any memory allocated dynamically during the easy setopt process * * @param pQuantumOriginConfig A pointer to a Quantum Origin config struct as returned from a call to qosdk_setopt_init(), containing values required to initialise a * Quantum Origin context */ extern void qosdk_setopt_cleanup(tQOSDK_CONFIG *pQuantumOriginConfig); /** * qosdk_get_randomness() : Request randomness from the provided Quantum Origin context. * * @param pQuantumOrigin A pointer to an initialized Quantum Origin context. * @param pBuffer A buffer of at least buf_size to be filled with random bytes. * @param cbBuffer The size of pBuffer in bytes. * @param pBytesReturned The number of bytes written to pBuffer on return. * * @return On success, returns ERC_QOSDK_OK (0) * On error, returns a non-zero error code indicating the cause of the problem. * The functions qosdk_get_error_description() and qosdk_get_error_code() can be called to help determine the nature/cause of the failure. */ extern tQOSDK_RESULT qosdk_get_randomness(tQOSDK_CTX *pQuantumOrigin, unsigned char *pBuffer, size_t cbBuffer, size_t *pBytesReturned); /** * qosdk_initialise_logging() : Initialise Quantum Origin logging subsystem. * * The logging subsystem must be initialised before adding, for example, a logging callback function. * * In the case of the setopt approach (i.e. systems that use qosdk_init_from_config_struct()), this is always the case. * * In the case of the config-file approach (i.e. systems that use qosdk_init_from_config_file()), this function needs * to be called only if a logging callback, or similar, needs to be registered before a subsequent call to qosdk_init_from_config_file(). * This is because the qosdk_init_from_config_file() function automatically initialises the logging subsystem during the processing * of the logging entries in the config file. * * @param logMode A valid logMode to use as the initial setting. This can be changed later with a call to qosdk_setopt_int(). * See \ref tQOSDK_LOGMODE above for the details of the available log modes. * @param logLevel A valid logLevel to use as the initial setting. This can be changed later with a call to qosdk_setopt_int(). * See \ref tQOSDK_LOGLEVEL above for the details of the available log levels. * @param logPath The path to a logfile to use as the initial setting. This parameter is used only for FILE related log modes. This can be changed later * with a call to qosdk_setopt_int(). See \ref tQOSDK_LOGLEVEL above for the details of the available log levels. * * @return On success, returns ERC_QOSDK_OK. * On error, returns an error code identifying the problem. * The functions qosdk_get_error_description() and qosdk_get_error_code() can be called to help determine the nature/cause of the failure. */ extern tQOSDK_RESULT qosdk_initialise_logging(tQOSDK_LOGMODE logMode, tQOSDK_LOGLEVEL logLevel, const char *szLogPath); /** * qosdk_set_logging_callback() : Register a logging callback handler. * * @param pLoggingCallbackFn A pointer to a callback function of type \ref tQOSDK_LOGGER_CALLBACK_FN, which can supply the secondary source of randomness. * See \ref tQOSDK_LOGGER_CALLBACK_FN above for the details of this callback function. * * @return On success, returns ERC_QOSDK_OK. * On error, returns an error code identifying the problem. * The functions qosdk_get_error_description() and qosdk_get_error_code() can be called to help determine the nature/cause of the failure. */ extern tQOSDK_RESULT qosdk_set_logging_callback(tQOSDK_LOGGER_CALLBACK_FN *pLoggingCallbackFn); /** * Use the Quantum Origin logger to log message. * * @param loglevel The severity of the log entry. The value is one of those in tQOSDK_LOGLEVEL * @param psMsg A pointer to a null-terminated string containing the log message. * @param ... Optional parameters to be passed into the string formatter. */ extern void qosdk_log_message(const tQOSDK_LOGLEVEL logLevel, const char *pMsg, ...); /** * Clear the logging callback */ extern void qosdk_clear_logging_callback(void); /** * qosdk_get_error_description() : Obtain the most recent error message generated by Quantum Origin. * * @return A pointer to a null-terminated string containing the latest error message. The caller should *not* attempt to free this string. */ extern const char *qosdk_get_error_description(void); /** * qosdk_get_error_code() : Obtain the most recent error code generated by Quantum Origin. * * @return The most recent error code */ extern tQOSDK_RESULT qosdk_get_error_code(void); /** * qosdk_destroy() : Destroy the given Quantum Origin context. * * @param pQuantumOrigin Pointer to a context previously obtained from qosdk_init_from_config_file() or qosdk_init_from_config_struct() */ extern void qosdk_destroy(tQOSDK_CTX *pQuantumOrigin); #ifdef __cplusplus } #endif