The following demonstrates how to use C++ 11 language for retrieving random data from AlphaRNG device when used with AlphaRNG Software API.

Terms used in this document:

RSA1024, RSA2048 - asymmetric ciphers used for AlphaRNG device authentication and for establishing a connection session with the device. The public key is provided by AlphaRNG Software API source code and the corresponding private key is embedded into device.

AES-256-GCM, AES-128-GCM - symmetric ciphers used for securing data transmissions within a connection session.

HMAC-SHA256, HMAC-SHA128, HMAC-MD5 - authentication algorithms used for additional data authentication within a connection session.

Factory supplied RSA2048 public key - a unique public RSA 2048-bit key that can be exclusively used with one AlphaRNG device, shipped with the device as a PEM file. Its corresponding private key is securely embedded into device when manufactured.

A sample code for retrieving random bytes from an AlphaRNG device using RSA2048, AES-256-GCM and HMAC-SHA256 algorithms

#include <AlphaRngApi.h>
#include <array>

using namespace alpharng;

/**
 * @return 0 if ran successfully
 */
int main() {

    std::array<uint8_t, 10> rnd_array { };

    // Create a new AlphaRngApi instance for using with RSA2048, AES-256-GCM and HMAC-SHA256 algorithms for strong security.
    // Note: AES-GCM algorithm also ensures the authenticity of the original data before encryption.
    // HMAC-SHA256 algorithm is used here to authenticate the data after encryption.
    AlphaRngApi rng { AlphaRngConfig { MacType::hmacSha256, RsaKeySize::rsa2048, KeySize::k256, "" } };

    // Connecting to the first AlphaRNG device found
    if (!rng.connect(0)) {
        cerr << rng.get_last_error() << endl;
        return -1;
    }

    cout << endl << "AlphaRNG device open successfully" << endl << endl;

    cout << "*** Retrieving " << rnd_array.size() << " random bytes ***" << endl;

    // Retrieve random numbers from device
    if (!rng.get_entropy(rnd_array.data(), sizeof(rnd_array))) {
        cerr << rng.get_last_error() << endl;
        return -1;
    }

    for (auto el : rnd_array) {
        cout << "random byte : " << (int) el << endl;
    }

    return 0;
}

A sample code for retrieving random bytes from an AlphaRNG device using a factory supplied RSA2048 public key, AES-256-GCM and HMAC-SHA256 algorithms.

To achieve maximum security, each AlphaRNG device is shipped with a unique public RSA 2048-bit key that can be exclusively used with one such device. The following code example demonstrates how to authenticate and connect to an AlphaRNG device using a factory supplied RSA-2048 public key.


#include <AlphaRngApi.h>
#include <array>

using namespace alpharng;

/**
 * @return 0 if ran successfully
 */
int main() {

    std::array<uint8_t, 10> rnd_array { };

    // Create a new AlphaRngApi instance for using with RSA2048, AES-256-GCM and HMAC-SHA256 algorithms.
    // Use a factory supplied unique RSA-2048 public key (as a file) to achieve maximum security.
    // The supplied key can be used to uniquely identify an AlphaRNG device.
    AlphaRngApi rng { AlphaRngConfig { MacType::hmacSha256, RsaKeySize::rsa2048, KeySize::k256, "public_key-123456789012345.pem" } };

    // Connecting to the first AlphaRNG device found
    if (!rng.connect(0)) {
        cerr << rng.get_last_error() << endl;
        return -1;
    }

    cout << endl << "AlphaRNG device open successfully" << endl << endl;

    cout << "*** Retrieving " << rnd_array.size() << " random bytes ***" << endl;

    // Retrieve random bytes from device
    if (!rng.get_entropy(rnd_array.data(), sizeof(rnd_array))) {
        cerr << rng.get_last_error() << endl;
        return -1;
    }

    for (auto el : rnd_array) {
        cout << "random byte : " << (int)el << endl;
    }

    return 0;
}

A sample code for retrieving random integers from an AlphaRNG device using RSA2048 and AES-256-GCM algorithms

#include <AlphaRngApi.h>
#include <array>

using namespace alpharng;

/**
 * @return 0 if ran successfully
 */
int main() {

    std::array<int, 10> rnd_array { };

    // Create a new AlphaRngApi instance for using with RSA2048 and AES-256-GCM algorithms.
    // Note: To improve performance, we are not using any MAC algorithm in this example.
    AlphaRngApi rng { AlphaRngConfig { MacType::None, RsaKeySize::rsa2048, KeySize::k256, "" } };

    // Connecting to the first AlphaRNG device found
    if (!rng.connect(0)) {
        cerr << rng.get_last_error() << endl;
        return -1;
    }

    cout << endl << "AlphaRNG device open successfully" << endl << endl;

    cout << "*** Retrieving " << rnd_array.size() << " random integers ***" << endl;

    // Retrieve random integers from device
    if (!rng.get_entropy((unsigned char*) rnd_array.data(), sizeof(rnd_array))) {
        cerr << rng.get_last_error() << endl;
        return -1;
    }

    for (auto el : rnd_array) {
        cout << "random integer : " << el << endl;
    }

    return 0;
}

A sample code for retrieving random data from an AlphaRNG device using RSA2048 and MAC-SHA256 algorithms

#include <AlphaRngApi.h>
#include <array>

using namespace alpharng;

/**
 * @return 0 if ran successfully
 */
int main() {

    std::array<int, 10> rnd_array { };

    // Create a new AlphaRngApi instance for using with RSA2048 and MAC-SHA256 algorithms.
    // This is the case when encryption is not required and we only need to ensure
    // the authenticity of the data.
    // Note: To increase performance, use MAC-SHA160 or HMAC-MD5 if accepted.
    AlphaRngApi rng { AlphaRngConfig { MacType::hmacSha256, RsaKeySize::rsa2048, KeySize::None, "" } };

    // Connecting to the first AlphaRNG device found
    if (!rng.connect(0)) {
        cerr << rng.get_last_error() << endl;
        return -1;
    }

    cout << endl << "AlphaRNG device open successfully" << endl << endl;

    cout << "*** Retrieving " << rnd_array.size() << " random integers ***" << endl;

    // Retrieve random integers from device
    if (!rng.get_entropy((unsigned char*) rnd_array.data(), sizeof(rnd_array))) {
        cerr << rng.get_last_error() << endl;
        return -1;
    }

    for (auto el : rnd_array) {
        cout << "random integer : " << el << endl;
    }

    return 0;
}

A sample code for retrieving random data from an AlphaRNG device using no symmetric encryption or MAC algorithm.

#include <AlphaRngApi.h>
#include <array>

using namespace alpharng;

/**
 * @return 0 if ran successfully
 */
int main() {

    std::array<int, 10> rnd_array { };

    // Create a new AlphaRngApi instance with no symmetric encryption or MAC algorithm.
    // Note: RSA algorithm (1024-bit or 2048-bit) is still used to authenticate the device.
    AlphaRngApi rng { AlphaRngConfig { MacType::None, RsaKeySize::rsa2048, KeySize::None, "" } };

    // Connecting to the first AlphaRNG device found
    if (!rng.connect(0)) {
        cerr << rng.get_last_error() << endl;
        return -1;
    }

    cout << endl << "AlphaRNG device open successfully" << endl << endl;

    cout << "*** Retrieving " << rnd_array.size() << " random integers ***" << endl;

    // Retrieve random integers from device
    if (!rng.get_entropy((unsigned char*) rnd_array.data(), sizeof(rnd_array))) {
        cerr << rng.get_last_error() << endl;
        return -1;
    }

    for (auto el : rnd_array) {
        cout << "random integer : " << el << endl;
    }

    return 0;
}

A sample code for retrieving random bytes from AlphaRNG device noise sources using default security.

This code example retrieves raw (unprocessed) random bytes from the independent noise sources and can be used for the purposes of evaluating the quality of the noise circuits used by AlphaRNG devices.

#include <AlphaRngApi.h>
#include <array>

using namespace alpharng;

/**
 * @return 0 if ran successfully
 */
int main() {

    std::array<uint8_t, 10> rnd_array { };

    // Create a new AlphaRngApi instance using default constructor (HMAC-SHA256, RSA2048 and AES-256-GCM)
    AlphaRngApi rng { };

    // Connecting to the first AlphaRNG device found
    if (!rng.connect(0)) {
        cerr << rng.get_last_error() << endl;
        return -1;
    }

    cout << endl << "AlphaRNG device open successfully" << endl << endl;

    cout << "*** Retrieving " << rnd_array.size() << " random bytes from the noise source one ***" << endl;

    // Retrieve random integers from the noise source one
    if (!rng.get_noise_source_1(rnd_array.data(), sizeof(rnd_array))) {
        cerr << rng.get_last_error() << endl;
        return -1;
    }

    for (auto el : rnd_array) {
        cout << "random integer : " << (int) el << endl;
    }

    cout << endl;
    cout << "*** Retrieving " << rnd_array.size() << " random bytes from the noise source two ***" << endl;

    // Retrieve random integers from the noise source two
    if (!rng.get_noise_source_2(rnd_array.data(), sizeof(rnd_array))) {
        cerr << rng.get_last_error() << endl;
        return -1;
    }

    for (auto el : rnd_array) {
        cout << "random integer : " << (int) el << endl;
    }

    return 0;
}

A sample code for retrieving internal real-time information from an AlphaRNG device.

#include <AlphaRngApi.h>
#include <array>

using namespace alpharng;

/**
 * @return 0 if ran successfully
 */
int main() {

    // Create a new AlphaRngApi instance using default constructor (HMAC-SHA256, RSA2048 and AES-256-GCM)
    AlphaRngApi rng { };

    // Connecting to the first AlphaRNG device found
    if (!rng.connect(0)) {
        cerr << rng.get_last_error() << endl;
        return -1;
    }

    cout << endl << "AlphaRNG device open successfully" << endl << endl;

    cout << "*** Retrieving device information ***" << endl;

    string id;
    if (!rng.retrieve_device_id(id)) {
        cerr << rng.get_last_error() << endl;
        return -1;
    }
    cout << "Device identifier: " << id << endl;

    string model;
    if (!rng.retrieve_device_model(model)) {
        cerr << rng.get_last_error() << endl;
        return -1;
    }
    cout << "Device model: " << model << endl;

    unsigned char major;
    unsigned char minor;
    rng.retrieve_device_major_version(&major);
    rng.retrieve_device_minor_version(&minor);
    cout << "Device version: " << (int) major << "." << (int) minor << endl;

    unsigned char status;
    if (!rng.retrieve_rng_status(&status)) {
        cerr << rng.get_last_error() << endl;
        return -1;
    }
    cout << "Device status: " << (status == 0 ? "healthy" : "error") << endl;

    cout << "Device last error: " << rng.get_last_error() << endl;

    HealthTests ht = rng.get_health_tests();
    cout << "Max APT test failures per block: " << ht.get_max_apt_failures() << endl;
    cout << "Max RCT test failures per block: " << ht.get_max_rct_failures() << endl;

    cout << "Operations retried: " << rng.get_operation_retry_count() << endl;

    return 0;
}

A sample code for invoking AlphaRNG device internal health test.

#include <AlphaRngApi.h>
#include <array>

using namespace alpharng;

/**
 * @return 0 if ran successfully
 */
int main() {

    // Create a new AlphaRngApi instance using default constructor (using HMAC-SHA256, RSA2048, and AES-256-GCM)
    AlphaRngApi rng { };

    // Connecting to the first AlphaRNG device found
    if (!rng.connect(0)) {
        cerr << rng.get_last_error() << endl;
        return -1;
    }

    cout << endl << "AlphaRNG device open successfully" << endl << endl;

    cout << "*** Invoking device internal health diagnostics  ***" << endl;

    if (!rng.run_health_test()) {
        cerr << rng.get_last_error() << endl;
        return -1;
    }
    cout << "Device internal diagnostics ran successfully" << endl;

    rng.run_health_test();

    return 0;
}

A sample code that retrieves entropy bytes from an AlphaRNG device and stores those into a file

#include <AlphaRngApi.h>
#include <array>

using namespace alpharng;

/**
 * @return 0 if ran successfully
 */
int main() {

    // Create a new AlphaRngApi instance using default constructor (using HMAC-SHA256, RSA2048, and AES-256-GCM)
    AlphaRngApi rng { };

    // Connecting to the first AlphaRNG device found
    if (!rng.connect(0)) {
        cerr << rng.get_last_error() << endl;
        return -1;
    }

    cout << endl << "AlphaRNG device open successfully" << endl << endl;

    cout << "*** Retrieving 256 bytes of entropy from AlphaRNG device and storing to entropy_bytes.bin file ***"
            << endl;

    if (!rng.entropy_to_file("entropy_bytes.bin", 256)) {
        cerr << rng.get_last_error() << endl;
        return -1;
    }

    return 0;
}