10. AOCL-SecureRNG#

AOCL-SecureRNG is a library that provides the APIs to access the cryptographically secure random numbers generated by the AMD hardware based RNG. These are high quality robust random numbers designed for the cryptographic applications.

The library makes use of RDRAND and RDSEED x86 instructions exposed by the AMD hardware.

The applications can just link to the library and invoke a single or a stream of random numbers. The random numbers can be of 16-bit, 32-bit, 64-bit, or arbitrary size bytes.

Refer SecureRNG documentation for more information.

10.1. Installation#

Table 10.1 **Library name for AOCL-SecureRNG**#
Library	Linux		Windows
Library	Dynamic	Static	Dynamic	Static
AOCL-SecureRNG	libamdsecrng.so	libamdsecrng.a	amdsecrng.dll amdsecrng.lib	amdsecrng-static.lib

10.1.1. Using Pre-Built Libraries on Linux#

AOCL-SecureRNG library can be installed using standalone package available AOCL-SecureRNG Download section.

Alternatively, AOCL-SecureRNG binary can also be installed using AOCL master installer tar file available under AOCL Download section.

The master installer tar file could be used to install any standalone or whole package of pre-built AOCL libraries as explained in Using Master Package.

Local environment may use library after executing below command,

$ source $HOME/aocl/<version>/<gcc-or-aocc>/amd-libs.cfg

10.1.2. Using Pre-Built Libraries on Windows#

AOCL-SecureRNG binary for Windows can only be installed from AOCL windows installer exe file available under AOCL Download section.

The windows master installer could be used to install whole package of pre-built AOCL libraries as explained in Using Windows Packages.

Local environment may use library after setting PATH like below,

> set "PATH=C:\Program Files\AMD\AOCL-Windows\amd-secrng\lib\LP64;%PATH%"

10.2. Using AOCL-SecureRNG Library#

The following source files are included in the AOCL-SecureRNG package:

include/secrng.h : A header file that has declaration of all the library APIs.
src_lib/secrng.c : Contains the implementation of the APIs.
src_test/secrng_test.c : Test application to test all the library APIs.
Makefile : To compile the library and test the application.

You can use the included Makefile to compile the source files and generate dynamic and static libraries. Then, you can link it to your application and invoke the required APIs.

The following code snippet shows a sample usage of the library APIs:

Listing 10.1 test_secrng.c#

/* Check for RDRAND instruction support */
int ret = is_RDRAND_supported();
int N = 1000;

/* If RDRAND supported */
if (ret == SECRNG_SUPPORTED)
{
  uint64_t rng64;

  /* Get 64-bit random number */
  ret = get_rdrand64u(&rng64, 0);

  if (ret == SECRNG_SUCCESS)
    printf("RDRAND rng 64-bit value %lu\n\n", rng64);
  else
    printf("Failure in retrieving random value using RDRAND!\n");

  /* Get a range of 64-bit random values */
  uint64_t* rng64_arr = (uint64_t*) malloc(sizeof(uint64_t) * N);

  ret = get_rdrand64u_arr(rng64_arr, N, 0);
  if (ret == SECRNG_SUCCESS)
  {
    printf("RDRAND for %u 64-bit random values succeeded!\n", N);
    printf("First 10 values in the range : \n");
    for (int i = 0; i < (N > 10? 10 : N); i++)
      printf("%lu\n", rng64_arr[i]);
  }
  else
    printf("Failure in retrieving array of random values using RDRAND!\n");
}
else
{
  printf("No support for RDRAND!\n");
}

In the example, get_rdrand64u is invoked to return a single 64-bit random value and get_rdrand64u_arr is used to return an array of 1000, 64-bit random values.

10.2.1. Using on Linux#

AOCL-SecureRNG should be installed as instructed in Using Pre-Built Libraries on Linux.

Use following commands to build your application.

$ source $HOME/aocl/<version>/<gcc-or-aocc>/amd-libs.cfg
$ CC test_secrng.c -o test_secrng -lamdsecrng
$ ./test_secrng

Notes:
  1. CC can be 'gcc' or 'clang'.
  2. If 'clang', AOCL environment setting should be done after AOCC.

10.2.2. Using on Windows#

AOCL-SecureRNG should be installed as instructed in Using Pre-Built Libraries on Windows.

Complete the following steps to use AOCL-SecureRNG library on Windows:

Create a 64-bit console app project in Visual Studio 17 2022.
Use the following navigation to select Clang-cl compiler: Project > Properties > Configuration Properties > General > Platform Toolset > LLVM(Clang-cl)
Use secrng_test.c as a reference to find the AOCL-SecureRNG API call flow.
Include the AOCL-SecureRNG header file secrng.h and call required AOCL-SecureRNG APIs under window application.
Copy the AOCL-SecureRNG header file secrng.h and AOCL-SecureRNG DLL library amdsecrng.dll and amdsecrng.lib to same project folder.
Compile and then run the application.
You may create Fortran based project in similar manner and compile it using ifort compiler.
You can also compile your application using AOCL-SecureRNG static library amdsecrng-static.lib.

AOCL-SecureRNG - 5.0 English - 57404