Generate Keystore File Entry (GENCKMKSFE)

The Generate Keystore File Entry (GENCKMKSFE) command generates a random key or key pair and stores it in a keystore file.

For more information on keystore files, refer to the Cryptographic services key management section of the Security category in the IBM Systems Information Center at http://www.ibm.com/systems/infocenter/.

Restrictions:

Parameters

Keyword Description Choices Notes
KEYSTORE Keystore file Qualified object name Required, Positional 1
Qualifier 1: Keystore file Name
Qualifier 2: Library Name, *LIBL, *CURLIB
RCDLBL Record label Character value Required, Positional 2
KEYTYPE Key type *MD5, *SHA1, *SHA224, *SHA256, *SHA384, *SHA512, *DES, *TDES, *AES, *RC2, *RC4, *RSA, *ECC Required, Positional 3
KEYSIZE Key size 1-4096 Required, Positional 4
EXPONENT Public key exponent 3, 65537 Optional
DISALLOW Disallowed function Values (up to 3 repetitions): *NONE, *ENCRYPT, *DECRYPT, *MAC, *SIGN Optional

Keystore file (KEYSTORE)

Specifies the keystore file to use.

This is a required parameter.

Qualifier 1: Keystore file

name
Specify the name of the keystore file.

Qualifier 2: Library

*LIBL
All libraries in the library list for the current thread are searched until the first match is found.
*CURLIB
The current library for the thread is searched. If no library is specified as the current library for the thread, the QGPL library is searched.
name
Specify the name of the library to search for the file.

Record label (RCDLBL)

Specifies the label of a key record in the specified keystore file.

This is a required parameter.

character-value
Specify the key record label. The label is 32 characters and may contain any alphanumeric characters.

Key type (KEYTYPE)

Specifies the algorithm type of the key.

This is a required parameter.

*MD5
An MD5 key is used for hash message authentication code (HMAC) operations. Because of weaknesses in the algorithm, MD5 should not be used except for compatibility purposes. 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.
*SHA1
An SHA-1 key is used for HMAC operations. Because of weaknesses in the algorithm, SHA-1 should not be used except for compatibility purposes. 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.
*SHA224
An SHA-224 key is used for HMAC operations. The minimum length for an SHA-224 HMAC key is 28 bytes. A key longer than 28 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.
*SHA256
An SHA-256 key is used for HMAC 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.
*SHA384
An SHA-384 key is used for HMAC 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.
*SHA512
An SHA-512 key is used for HMAC 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.
*DES
An older, widely used symmetric encryption algorithm. DES should not be used except for compatibility purposes. 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.
*TDES
A symmetric encryption algorithm that improves the security of DES by performing the DES algorithm three times. 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).
*AES
A newly developed symmetric encryption algorithm designed to replace DES. AES offers faster and stronger encryption than TDES. The key size can be 16, 24, or 32.
*RC2
A variable-key-size symmetric encryption algorithm. The key size can be 1 - 128.
*RC4
A variable-key-size symmetric stream encryption algorithm. The key size can be 1 - 256. Because of the nature of the RC4 operation, using the same key for more than one message will severely compromise security.
*RSA
An asymmetric encryption algorithm that uses a public/private key pair. The key size is the modulus length, specified 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.
*ECC
An asymmetric encryption algorithm that uses a public/private key pair, generated from a set of domain parameters. The key size is specified in bits and must be a value equal to 160, 192, 224, 256, 384, 512 or 521. For a given elliptic curve operation on a prime field, Fp, the size corresponds to the choice of domain parameters being used. Both the ECC public and private key parts are stored in the key record.

Key size (KEYSIZE)

Specifies the size 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 is a required parameter.

unsigned-integer
Specify the size of the key to generate.

Public key exponent (EXPONENT)

Specifies the public-key exponent for an RSA key pair. To maximize performance, the public-key exponent is limited to the following two values. The value of 65537 may be more secure than a value of 3.

Note: This parameter will be ignored if any value other than *RSA is specified for the Key type (KEYTYPE) parameter.

65537
3

Disallowed function (DISALLOW)

Specifies the functions that cannot be used with this key record. Multiple functions can be disallowed.

Single values

*NONE
This key is allowed to be used in all cryptographic functions.

Other values (up to 3 repetitions)

*ENCRYPT
This key is not allowed to be used in encryption operations.
*DECRYPT
This key is not allowed to be used in decryption operations.
*MAC
This key is not allowed to be used in message authentication code (MAC) operations.
*SIGN
This key is not allowed to be used in digital signing operations.

Examples

Example 1: Generate an AES Keystore Entry 

GENCKMKSFE   KEYSTORE(MYLIB/MYKEYSTORE) RCDLBL('Byllesby')
             TYPE(*AES) SIZE(32)

This command generates a 32-byte (256-bit) AES key and stores it in keystore file MYKEYSTORE in library MYLIB.

Example 2: Generate an RSA Keystore Entry 

GENCKMKSFE   KEYSTORE(MYLIB/MYKEYSTORE) RCDLBL('Pepin')
             TYPE(*RSA) SIZE(2048) EXPONENT(3)
             DISALLOW(*ENCRYPT *DECRYPT *MAC)

This command generates a 2048-bit RSA public/private key pair that can only be used in digital signing and verification operations.

Error messages

*ESCAPE Messages

CPF3CF2
Error(s) occurred during running of &1 API.
CPF9872
Program or service program &1 in library &2 ended. Reason code &3.
CPF9D94
A pending value exists for a master key.
CPF9D9E
Record label already exists.
CPF9D9F
User not authorized to key store file.
CPF9DA0
Error opening key store file.
CPF9DA5
Key store file not found.
CPF9DA6
Key store file is not available.
CPF9DA7
File is corrupt or not a valid key store file.
CPF9DB3
Qualified keystore file name is not valid.
CPF9DB6
Record label not valid.
CPF9DB7
Error occured writing to the key store file.
CPF9DB8
Error occured reading record from key store.
CPF9DDA
Unexpected return code &1 from cryptographic service provider &2.