Pseudo random number generation functions

libica provides two methods of random number (random bit) generation.

The two provided random number or random bit generators are:

a conventional random number generator (ica_random_number_generate).
a NIST SP800-90A compliant deterministic random bit generator (DRBG). This generator is implemented by a combination of five separate functional APIs and is hereafter referred to as ica_drbg (see NIST compliant ica_drbg functions) to denote the complete generator as a whole.
Note: The ica_drbg API does not use a random source that is compliant to FIPS 140-3. However, this API is not blocked if libica is running in FIPS mode. Therefore applications that are obliged to only use FIPS 140-3 compliant APIs, must not use ica_drbg functions.

These functions are declared in: include/ica_api.h.

Conventional ica_random_number_generate function

libica initialization tries to seed the CPACF random generator. To get the seed, device /dev/hwrng is opened. Device /dev/hwrng provides true random data from crypto adapters over the crypto device driver (main module name is ap, with an alias name z90crypt, which is linking to ap). If that fails, the initialization mechanism uses device /dev/urandom. Within the initialization, a byte counter s390_byte_count is set to 0. If the CPACF pseudo random generator is available, after 4096 bytes of the pseudo random number are generated, the random number generator is seeded again. If the CPACF pseudo random generator is not available, random numbers are read from /dev/urandom.

Since libica version 2.6, this API internally invokes the NIST compliant ica_drbg functionality. The original code of this API is only processed if no MSA5, or at least no MSA2 support is available, which is the prerequisite of the ica_drbg API (see NIST compliant ica_drbg functions).

NIST compliant ica_drbg functions

The following APIs make up the complete ica_drbg functionality:

The implementation is designed to be thread-safe such that different threads can share the same ica_drbg instantiation.

The ica_drbg functionality uses certain definitions and supports the following DRBG mechanisms as shown in Table 1.


typedef struct ica_drbg_mech ica_drbg_mech_t;
extern ica_drbg_mech_t *const ICA_DRBG_SHA512;

Table 1. Supported DRBG mechanisms
The table lists the supported DRBG mechanisms for the ica_drbg function. In three columns, it lists the name of the DRBG mechanism, the supported security strengths (in bits), and the maximum byte length of involved parameters.
DRBG mechanism	supported security strengths (in bits)	max. byte length of pers/add parameters
DRBG_SHA512	112, 128, 196, 256	256 / 256

The following information list satisfies the NIST SP800-90A documentation requirements:

Entropy input is read from /dev/hwrng. If /dev/hwrng is not available, the entropy input is read from /dev/prandom.
ica_drbg provides the ica_drbg_health_test interface for validation and health testing. This function together with test parameters can be found in libica/src/include/s390_drbg.h. Nonce and entropy input can be injected via these parameters for the purpose of known answer testing.
No further support functions other than health testing are supported.
The only DRBG mechanism currently implemented is Hash_DRBG using SHA-512.
ica_drbg supports 112, 128, 196, and 256 bits of security.
ica_drbg supports prediction resistance.
The generate function is tested every 2⁶⁴ - 1 calls. This interval size is chosen, because CPACF hardware failures should not happen frequently.
The integrity of the health test can be determined by inspecting the checksum/hash of the package before install.