Generate Key Record (QC3GENKR, Qc3GenKeyRecord) API

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.

Authorities and Locks

Required file authority

*OBJOPR, *READ, *ADD

Required device description authority

*USE

Required Parameter Group

Qualified keystore file name

INPUT; CHAR(20)

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.

Record label

INPUT; CHAR(32)

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).

Key type

INPUT; BINARY(4)

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.

Key size

INPUT; BINARY(4)

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.

Public key exponent

INPUT; BINARY(4)

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.

Disallowed function

INPUT; BINARY(4)

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.

Cryptographic service provider

INPUT; CHAR(1)

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.

Cryptographic device name

INPUT; CHAR(10)

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.

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

[ Back to top | Cryptographic Services APIs | APIs by category ]