WindowsAPI Reference.
QWQNG.QNG 3.6 API
v2019.11.15 © 2019 The Quantum World Corporation.
Introduction
Requirements
The QWQNG.QNG ActiveX control requires Windows 7 or later.
Description
QNG hardware is accessed using the QWQNG.QNG ActiveX control. As such, it is widely supported among different Windows environments and languages. If you do not find a basic example suitable for your particular environment, consult your developers guide on how to use ActiveX controls.
The quickest way to get started is by looking at the properties for reading random numbers from the QNG device and trying the example code given for each property. The properties for reading random numbers from the device are RandInt32, RandUniform, RandNormal, and RandBytes. The example code is meant to concisely demonstrate the use of the QWQNG.QNG ActiveX methods and properties and thus does not adhere to best coding practices, such as exception/error handling, etc.
Notes
The QWQNG.QNG ActiveX control version 3.6 is drop-in compatible with client applications that were designed for previous versions of the ActiveX control.
QNG hardware constantly reports hardware run-time test results. If run-time test results appear questionable, the QWQNG.QNG ActiveX control immediately shuts down the hardware and reports the exception. See the section on Runtime Testing for more information.
The QWQNG.QNG control provides custom HRESULT codes on every method or property call. HRESULT codes provide exception/error detail. If any error condition is detected, the hardware device will be shut down and the appropriate HRESULT code will be passed to the caller. The HRESULT error code will persist until a Reset() call is issued. The Reset() call will attempt to restart the hardware and clear the error code. See the section on Error Handling for examples and more information.
During a programming session, a programming environment typically sets the Ambient Properties for an ActiveX control to design mode. In design mode the QWQNG.QNG control will return default values for RandInt32 (123456789), RandUniform (0.123456789), RandNormal (1.23456789) and RandBytes (1234567890123…). If the QWQNG.QNG control returns these values at run-time, please make sure the User Mode Ambient Property is set to TRUE at run-time. This should normally not be an issue, however.
Support
Contact ComScire via email, phone, or mail regarding any support issues. Please visit our Contact Us page to obtain our latest support contact information.
API Reference
RandInt32
HRESULT RandInt32([out, retval] LONG* pVal)
Returns
Random 32 bit integer as LONG (VT_I4)
Remarks
RandInt32 is a COM property that returns a 32 bit random integer. Each RandInt32 integer contains 32 bits of entropy.
C++ Example
C# Example
Python Example
RandUniform
HRESULT RandUniform([out, retval] DOUBLE* pVal)
Returns
Random uniform number [0,1) as DOUBLE (VT_R8)
Remarks
RandUniform is a COM property that returns a double float that is randomly selected from a uniform distribution. Each RandUniform number contains 48 bits of entropy.
C++ Example
C# Example
Python Example
RandNormal
HRESULT RandNormal([out, retval] DOUBLE* pVal)
Returns
Random normal number with mean zero and standard deviation one as DOUBLE (VT_R8)
Remarks
RandNormal is a COM property that returns a double float that is randomly selected from a normal distribution. RandNormal numbers are produced by transforming uniform numbers, with 48 bits of entropy each, into normal numbers using the Box-Muller method.
C++ Example
C# Example
Python Example
RandBytes
HRESULT RandBytes([in] LONG Length, [out, retval] VARIANT* pVal)
Parameters
Length: Number of bytes to be returned from RandBytes. Must not exceed 8192 for generator output rate of 32 Mbps or less, 65536 for generator output rate of 64 or 128 Mbps.
Returns
Byte array as VARIANT SAFEARRAY of BYTES (VT_ARRAY of VT_U1)
Remarks
RandBytes is a COM property that returns a byte array of random bytes. Each byte contains 8 bits of entropy. If Length exceeds maximum allowed requested bytes, the control will return the QNG_E_IO_ARRAY_OVERSIZED error code. For information on using Variant SAFEARRAY’s, please consult documentation specific to your programming environment.
C++ Example
C# Example
Python Example
Clear
HRESULT Clear(VOID)
Remarks
Clear is a COM method that purges internal data buffers. If random data is not continuously consumed, random data will remain available in internal buffers. A call to Clear will remove “stale” data from the buffers.
C++ Example
C# Example
Python Example
Reset
HRESULT Reset(VOID)
Remarks
Reset() is a COM method that clears the buffers and resets the hardware device.
C++ Example
C# Example
Python Example
DeviceId
HRESULT DeviceId([out, retval] BSTR* devId)
Returns
Serial number as a binary string.
Remarks
DeviceId is a COM property that returns a the device serial number as a BSTR.
C++ Example
C# Example
Python Example
RuntimeInfo
HRESULT RuntimeInfo([out, retval] VARIANT* runtimeInfo)
Returns
Float array as VARIANT SAFEARRAY of 32 bit floating point numbers (VT_ARRAY of VT_R4)
Remarks
RuntimeInfo is a COM property that returns a SAFEARRAY of 17 floating point numbers. The numbers indicate the internal runtime state. Assuming a zero index based array:
runtimeInfo[0]: General statistical status. A zero (0) indicates that all internal statistics are within expected ranges and a minus one (-1) indicates an exception. runtimeInfo[1]: Entropy H(P) of final output channel. runtimeInfo[2]: Predictability value (P) of final output channel. runtimeInfo[3]: Bias of final output channel. runtimeInfo[4]: 1st order serial correlation of final output channel. runtimeInfo[5]: Entropy H(P) of 1st raw generator channel. runtimeInfo[6]: Predictability value (P) of 1st raw generator channel. runtimeInfo[7]: Bias of 1st raw generator channel. runtimeInfo[8]: 1st order serial correlation of 1st raw generator channel. runtimeInfo[9]: Entropy H(P) of 2nd raw generator channel. runtimeInfo[10]: Predictability value (P) of 2nd raw generator channel. runtimeInfo[11]: Bias of 2nd raw generator channel. runtimeInfo[12]: 1st order serial correlation of 2nd raw generator channel. runtimeInfo[13]: Entropy H(P) of 3rd raw generator channel. runtimeInfo[14]: Predictability value (P) of 3rd raw generator channel. runtimeInfo[15]: Bias of 3rd raw generator channel. runtimeInfo[16]: 1st order serial correlation of 3rd raw generator channel.
RuntimeInfo is not supported on devices prior to the model R2000KU.
C++ Example
C# Example
Python Example
Diagnostics
HRESULT Diagnostics([in] LONG dxCode, [out, retval] VARIANT* dxInfo)
Returns
Byte array as VARIANT SAFEARRAY of BYTES (VT_ARRAY of VT_U1)
Remarks
Diagnostics is a COM property that returns a SAFEARRAY of 128 bytes for a specified internal pre-output raw data channel on a specific level of processing. Diagnostics provides insight into three entropy combining levels of processing in PureQuantum® (PQ) and the final raw output stream in CryptoStrong™ (CS) generators. Each successive level, beginning with level 1, combines more entropy per bit towards the final output. The final output itself exceeds NIST defined full entropy without utilizing correction, whitening, or conditioning. Note that low-level pre-output data is not expected to look perfectly random. Therefore, data gathered from Diagnostics should never be used in random data consuming applications. The intention of Diagnostics is to allow measurements into the the pre-output generation levels to follow and confirm theoretical generation models. More information on PureQuantum® and CryptoStrong™ generation internals can be found in whitepapers published on the ComScire website. Diagnostics allows access to three levels of pre-output generation with three channels per level, and the final combined output for CryptoStrong™ generators. The following lists corresponding hex Diagnostics codes (dxCode) for each level and channel:
Level 1, Channel 1: | 0x10 |
Level 1, Channel 2: | 0x11 |
Level 1, Channel 3: | 0x12 |
Level 2, Channel 1: | 0x13 |
Level 2, Channel 2: | 0x14 |
Level 2, Channel 3: | 0x15 |
Level 3, Channel 1: | 0x16 |
Level 3, Channel 2: | 0x17 |
Level 3, Channel 3: | 0x18 |
Final Output (CS Model only): | 0x19 |
Note that there may be other undocumented Diagnostics codes (dxCode). However, using these codes may produce unexpected outputs or results. Nonetheless, random data obtained through the random API calls (RandInt32, RandUniform, RandNormal, RandBytes) is entirely unaffected by Diagnostics calls. Diagnostics is not supported on devices prior to the PureQuantum® (PQ) and CryptoStrong™ (CS) models. Final output stream (dxCode: 0x19) is only available in CryptoStrong™ models.
C++ Example
C# Example
Python Example
Error Handling
The QWQNG.QNG ActiveX control returns a set of custom HRESULT error codes. Check your programming language/environment documentation to get more information on how to handle ActiveX errors or exceptions. All error conditions will persist until cleared by a succesful Reset method call.
HResult Codes
C++ Example
C# Example
Python Example
Select Algorithms
Random Range
Remarks
This algorithm uniformly selects a single number from a range of integers. It is equivalent to drawing a single number out of a bin that contains each number in the range from min-value to max-value. The maximum range length for this algorithm is 2^32, since 32 bit integers are assumed for randomizing. Note that exception and boundary conditions are not handled in the example code and should be added to production code.
Pseudo-Code
Python Example
Random Sample
Remarks
This algorithm uniformly draws n number of elements out of a given set of elements. It is equivalent to randomly selecting and removing items from a fixed set bin one by one.
Pseudo-Code
Python Example