Generate Pseudorandom Numbers (QC3GENRN, Qc3GenPRNs) API
Required Parameter Group:
1 | PRN data | Output | Char(*) |
2 | PRN data length | Input | Binary(4) |
3 | PRN type | Input | Char(1) |
4 | PRN Parity | Input | Char(1) |
5 | Error code | I/O | Char(*) |
Service Program Name: QC3PRNG
Default Public Authority: *USE
Threadsafe: Yes
The Generate Pseudorandom Numbers (OPM, QC3GENRN; ILE, Qc3GenPRNs) API generates a pseudorandom binary stream.
The pseudorandom number generator is composed of two parts: pseudorandom number generation and seed management. Pseudorandom number generation is performed using the FIPS 186-1 algorithm. Cryptographically-secure pseudorandom numbers rely on good seed. The FIPS 186-1 key and seed values are obtained from the system seed digest. The system automatically generates seed using data collected from system information or by using the random number generator function on a cryptographic coprocessor, such as a 4764, if one is available. System-generated seed can never be truly unpredictable. If a cryptographic coprocessor is not available, you can use the Add Seed for PRNG (Qc3AddPRNGSeed) API to add your own random seed to the system seed digest. This should be done as soon as possible any time the Licensed Internal Code is installed.
Authorities and Locks
None.
Required Parameter Group
- PRN data
- OUTPUT; CHAR(*)
The generated pseudorandom binary stream.
- PRN data length
- INPUT; BINARY(4)
The number of pseudorandom number bytes to return in the PRN data parameter. If 0 is specified, no pseudorandom numbers are returned.
- PRN type
- INPUT; CHAR(1)
The API can generate a real pseudorandom binary stream or a test binary stream.
The FIPS 186-1 algorithm obtains the inital key and seed values from the system seed digest when generating a real pseudorandom binary stream. When generating a test binary stream, the algorithm uses preset values for the key and seed. Valid values are:
0 Generate real pseudorandom numbers. 1 Generate test pseudorandom numbers.
- PRN Parity
- INPUT; CHAR(1)
The API sets each byte of the pseudorandom number binary stream to the specified parity by altering the low order bit in each byte as necessary. Valid values are:
0 Do not set parity. 1 Set each byte to odd parity. 2 Set each byte to even parity.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
Error Messages
Message ID | Error Message Text |
---|---|
CPF3C19 E | Error occurred with receiver variable specified. |
CPF3CF1 E | Error code parameter not valid. |
CPFBAF1 E | PRN type not valid. |
CPFBAF2 E | Parity not valid. |
CPFBAF3 E | The system seed digest is not ready. |
API introduced: V5R1
[ Back to top | Cryptographic Services APIs | Miscellaneous APIs | APIs by category ]