Add Keystore File Entry (ADDCKMKSFE)
The Add Keystore File Entry (ADDCKMKSFE) command stores the specified key value 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:
- You must have object operational (*OBJOPR), read (*READ) and add (*ADD) authorities to the keystore file.
- You must have execute (*X) authority to the directories in the path name prefix of the stream file if specified.
- You must have read (*R) authority to the stream file if specified.
| 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, *SHA256, *SHA384, *SHA512, *DES, *TDES, *AES, *RC2, *RC4, *RSAPUB, *RSAPRV |
Required, Positional 3 |
| FORMAT |
Key format |
*BIN, *BER, *PEM |
Required, Positional 4 |
| STRING |
Key string |
Element list |
Optional, Positional 5 |
| Element 1: Hexadecimal key value |
Character value |
| Element 2: Length of key string |
Unsigned integer |
| STMF |
Stream file |
Path name |
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.
- *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 last bit is sometimes used as a parity bit. 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 last bit is sometimes used as a parity bit. 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.
- *RSAPUB
- An asymmetric encryption algorithm that uses a public/private key pair. The public key part can be used for encryption, or for verifying a digital signature. The FORMAT parameter must specify *BER or *PEM.
- *RSAPRV
- An asymmetric encryption algorithm that uses a public/private key pair. The private key part can be used for decryption, or digital signature generation. The FORMAT parameter must specify *BER.
Key format (FORMAT)
Specifies the format of the key string parameter.
This is a required parameter.
-
- *BIN
- The key is specified as a binary value. All key types, except RSA, must use this format.
- *BER
- If the key TYPE parameter specifies *RSAPUB, the key STRING parameter may specify the key in ASN.1 Basic Encoding Rules (BER) X.509 Certificate or SubjectPublicKeyInfo format. For specifications of these formats, refer to RFC 3280. If the key TYPE parameter specifies *RSAPRV, the key STRING parameter must specify the key in BER encoded PKCS #8 format. For specifications of this format, refer to RSA Security Inc. Public-Key Cryptography Standards.
- *PEM
- If the key TYPE parameter specifies *RSAPUB, the key STRING parameter may specify the key in a Privacy Enhanced Mail (PEM) based certificate.
Key string (STRING)
Specifies the key string. Either this parameter or the STMF parameter can be used to specify the key.
-
- hexadecimal-value
- Specify in hexadecimal (0-1, A-F) the key string. (Every two characters represent a byte.) For all but RSA keys, the key string is a simple binary value. For RSA keys, the key string must be in a special format. See the FORMAT parameter for more information.
Stream file (STMF)
Specifies the path name for the stream file that contains the key string. Either this parameter or the STRING parameter can be used to specify the key.
-
- path-name
- Specify the path name of the stream file.
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.
Example 1: Add a Keystore File Entry Using a Key String
ADDCKMKSFE KEYSTORE(MYLIB/MYKEYSTORE) RCDLBL('Byllesby')
KEYTYPE(*AES) FORMAT(*BIN)
LEN(16) STRING(8276B09145C1324AC300D267F5D26694)
This command adds a 16-byte (128-bit) AES key to keystore file MYKEYSTORE in library MYLIB with label Byllesby.
Example 2: Add a Keystore File Entry Using a Stream File
ADDCKMKSFE KEYSTORE(MYLIB/MYKEYSTORE) RCDLBL('Pepin')
KEYTYPE(*RSAPRV) FORMAT(*BER)
LEN(*EOF) STMF('/myKeys/key1.SIGN')
DISALLOW(*ENCRYPT *DECRYPT *MAC)
This command adds an RSA public/private key pair to keystore file MYKEYSTORE in library MYLIB with a label Pepin. The key is specified in BER-encoded format in stream file myKeys/key.SIGN. The length of keystring is the total length of data in the file. The resulting key record can only be used in digital signing and verification operations.
*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.
- CPF9DA9
- The format of the PEM certificate is not valid.
- 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.
- CPF9DDD
- The key string length is not valid.