gsk_generate_random

Generates a random byte stream.

Format

   #include <gskcms.h>

   gsk_status gsk_generate_random_bytes (  
                                                gsk_buffer *         buffer)

Parameters

buffer: Specifies the buffer for the random byte stream. The application is responsible for providing the buffer and setting the length and data fields appropriately.

Results

The function return value will be 0 if no error is detected. Otherwise, it will be one of the return codes listed in the gskcms.h include file. These are some possible errors:

[CMSERR_RNG]: Generate random bytes input buffer not valid.
[CMSERR_BAD_RNG_OUTPUT]: Generate random bytes produced duplicate output.
[CMSERR_ICSF_FIPS_DISABLED]: ICSF PKCS #11 services are disabled.
[CMSERR_ICSF_NOT_AVAILABLE]: ICSF services are not available.
[CMSERR_ICSF_NOT_FIPS]: ICSF PKCS #11 not operating in FIPS mode.
[CMSERR_ICSF_SERVICE_FAILURE]: ICSF callable service returned an error.

Usage

The gsk_generate_random_bytes() routine will return a random byte stream. The application provides the buffer for the byte stream. The length value determines how many bytes will be generated.

System SSL attempts to use the ICSF PKCS #11 pseudo-random callable service (CSFPPRF) to generate a random byte stream. If ICSF is unavailable or returns an error and System SSL is in non-FIPS mode, an internal RNG will be used to generate the random data. If System SSL is in FIPS mode, the API call will fail.

The contents of the generated byte stream can be modified by setting the GSK_RNG_ALLOW_ZERO_BYTES environment variable. A GSK_RNG_ALLOW_ZERO_BYTES setting of “TRUE”, “ON” or “1” will retain bytes with a zero value in the random byte stream. A setting of “FALSE”, “OFF” or “0” will remove bytes with a zero value from the random byte stream. The default setting is "TRUE".

Note: The GSK_RNG_ALLOW_ZERO_BYTES environment variable is processed during System SSL initialization and is not checked afterward.