| 1 | Qualified keystore file name | Input | Char(20) |
| 2 | Record label | Input | Char(32) |
| 3 | Key type | Input | Binary(4) |
| 4 | Key size | Input | Binary(4) |
| 5 | Public key exponent | Input | Binary(4) |
| 6 | Disallowed function | Input | Binary(4) |
| 7 | Cryptographic service provider | Input | Char(1) |
| 8 | Cryptographic device name | Input | Char(10) |
| 9 | Error code | I/O | Char(*) |
The Generate Key Record (OPM, QC3GENKR; ILE, Qc3GenKeyRecord) API generates a random key or key pair and stores it in a keystore file.
For more information about cryptographic services keystore, see Cryptographic services key management.
The keystore file where the key will be stored. The first 10 characters
contain the file name. The second 10 characters contain the name of the library
where the keystore file is located.
You can use the following special values for the
library name.
| *CURLIB | The job's current library is used to locate the keystore file. If no library is specified as the current library for the job, the QGPL library is used. |
| *LIBL | The job's library list is searched for the first occurence of the specified file name. |
The label for the key record. The label will be converted from the job CCSID, or if 65535, the job default CCSID (DFTCCSID) job attribute to CCSID 1200 (Unicode UTF-16).
The type of key.
Following are the valid values.
| 1 | MD5 An MD5 key is used for HMAC (hash message authentication code) operations. The minimum length for an MD5 HMAC key is 16 bytes. A key longer than 16 bytes does not significantly increase the function strength unless the randomness of the key is considered weak. A key longer than 64 bytes will be hashed before it is used. |
| 2 | SHA-1 An SHA-1 key is used for HMAC (hash message authentication code) operations. The minimum length for an SHA-1 HMAC key is 20 bytes. A key longer than 20 bytes does not significantly increase the function strength unless the randomness of the key is considered weak. A key longer than 64 bytes will be hashed before it is used. |
| 3 | SHA-256 An SHA-256 key is used for HMAC (hash message authentication code) operations. The minimum length for an SHA-256 HMAC key is 32 bytes. A key longer than 32 bytes does not significantly increase the function strength unless the randomness of the key is considered weak. A key longer than 64 bytes will be hashed before it is used. |
| 4 | SHA-384 An SHA-384 key is used for HMAC (hash message authentication code) operations. The minimum length for an SHA-384 HMAC key is 48 bytes. A key longer than 48 bytes does not significantly increase the function strength unless the randomness of the key is considered weak. A key longer than 128 bytes will be hashed before it is used. |
| 5 | SHA-512 An SHA-512 key is used for HMAC (hash message authentication code) operations. The minimum length for an SHA-512 HMAC key is 64 bytes. A key longer than 64 bytes does not significantly increase the function strength unless the randomness of the key is considered weak. A key longer than 128 bytes will be hashed before it is used. |
| 20 | DES Only 7 bits of each byte are used as the actual key. The rightmost bit of each byte will be set to odd parity because some cryptographic service providers require that a DES key have odd parity in every byte. The key size parameter must specify 8. |
| 21 | Triple DES Only 7 bits of each byte are used as the actual key. The rightmost bit of each byte will be set to odd parity because some cryptographic service providers require that a DES key have odd parity in every byte. The key size can be 8, 16, or 24. Triple DES operates on an encryption block by doing a DES encrypt, followed by a DES decrypt, and then another DES encrypt. Therefore, it actually uses three 8-byte DES keys. If the key is 24 bytes in length, the first 8 bytes are used for key 1, the second 8 bytes for key 2, and the third 8 bytes for key 3. If the key is 16 bytes in length, the first 8 bytes are used for key 1 and key 3, and the second 8 bytes for key 2. If the key is only 8 bytes in length, it will be used for all 3 keys (essentially making the operation equivalent to a single DES operation). |
| 22 | AES The key size can be 16, 24, or 32. |
| 23 | RC2 The key size can be 1 - 128. |
| 30 | RC4-compatible The key size can be 1 - 256. Because of the nature of the RC4-compatible operation, using the same key for more than one message will severely compromise security. |
| 50 | RSA The key size specifies the modulus length in bits and must be an even number in the range 512 - 4096. Both the RSA public and private key parts are stored in the key record. |
The length of key to generate. For RSA keys this length is specified in
bits. For all other keys it is specified in bytes.
Refer to the key type parameter for restrictions.
This parameter is valid when key type parameter specifies 50 (RSA). Otherwise, this parameter must be set to 0. To maximize performance, the public key exponent is limited to the following two values.
| 3 | Or hex 00 00 00 03. |
| 65,537 | Or hex 00 01 00 01. |
This parameter specifies the functions that cannot be used with this key record. The values listed below can be added together to disallow multiple functions. For example, to disallow everything but MACing, set the value to 11.
| 0 | No functions are disallowed. |
| 1 | Encryption is disallowed. |
| 2 | Decryption is disallowed. |
| 4 | MACing is disallowed. |
| 8 | Signing is disallowed. |
The cryptographic service provider (CSP) that will perform the key generate operation.
| 0 | Any CSP. The system will choose an appropriate CSP to perform the key generate operation. |
| 1 | Software CSP. The system will perform the key generate operation using software. |
| 2 | Hardware CSP. The system will perform the key generate operation using cryptographic hardware. If the requested key type can not be generated in hardware, an error is returned. A specific cryptographic device can be specified using the cryptographic device name parameter. If the cryptographic device is not specified, the system will choose an appropriate one. |
The name of a cryptographic device description.
This parameter is valid when the cryptographic service provider parameter specifies 2 (hardware CSP). Otherwise, this parameter must be blanks or the pointer to this parameter set to NULL.
The structure in which to return error information. For the format of the structure, see Error code parameter.
| Message ID | Error Message Text |
|---|---|
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3C1E E | Required parameter &1 omitted. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
| CPF9D94 E | A pending value exists for a master key. |
| CPF9D9E E | Record label already exists. |
| CPF9D9F E | Not authorized to keystore file. |
| CPF9DA0 E | Error occured opening keystore file. |
| CPF9DA5 E | Keystore file not found. |
| CPF9DA6 E | The keystore file is not available. |
| CPF9DA7 E | File is corrupt or not a valid keystore file. |
| CPF9DAC E | Disallowed function value not valid. |
| CPF9DB3 E | Qualified keystore file name not valid. |
| CPF9DB6 E | Record label not valid. |
| CPF9DB7 E | Error occured writing to keystore. |
| CPF9DB8 E | Error occured retrieving key record from keystore. |
| CPF9DDA E | Unexpected return code &1. |
| CPF9DE7 E | Key type not valid. |
| CPF9DEA E | Key size not valid. |
| CPF9DEB E | Public key exponent not valid. |
| CPF9DEC E | Cryptographic service provider not valid. |
| CPF9DF0 E | Operation, algorithm, or mode not available on the requested CSP (cryptographic service provider). |
| CPF9DF8 E | Cryptographic device name not valid. |
| CPF9DF9 E | Cryptographic device not found. |
| CPF9DFD E | Not authorized to device. |
| CPF9DFE E | Cryptographic device not available. |
[ Back to top | Cryptographic Services APIs | APIs by category ]