Write Key Record (QC3WRTKR, Qc3WriteKeyRecord)

Required Parameter Group:

1	Qualified key store file name	Input	Char(20)
2	Record label	Input	Char(32)
3	Key string	Input	Char(*)
4	Length of key string	Input	Binary(4)
5	Key format	Input	Char(1)
6	Key type	Input	Binary(4)
7	Disallowed function	Input	Binary(4)
8	Key form	Input	Char(1)
9	Key-encrypting key context token	Input	Char(8)
10	Key-encrypting algorithm context token	Input	Char(8)
11	Error code	I/O	Char(*)

Service Program Name: QC3KRWRT

Default Public Authority: *USE

Threadsafe: Yes

The Write Key Record (OPM, QC3WRTKR; ILE, Qc3WriteKeyRecord) API stores the specified key value in a key store file.

For more information about cryptographic services key store, refer to Cryptographic Services Key Store.

Authorities and Locks

Required file authority

*OBJOPR, *READ, *ADD

Required Parameter Group

Qualified key store file name

INPUT; CHAR(20)

The key store 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 key store file is located.

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 string

INPUT; CHAR(*)

A binary string or a formatted structure containing the key. The exact format of the key string is specified in the key format parameter.

Length of key string

INPUT; BINARY(4)

Length of the key string specified in the key string parameter.

Note this is not the same thing as key length. Key length is determined based on the other parameters. Following are some examples:

If key format is 0 (binary string) and
- the key form is 0 (clear) then the key length equals the length of key string.
- the key form is 1 (encrypted) then the key length will be the decrypted key string length.
If key format is 1 (BER string) then the key length will be the length specified within the BER string.
If key format is 6 (PEM certificate) then the key length will be the length specified in the certificate.

Most algorithms have key length requirements. Refer to the key type parameter for restrictions on key length.

Key format

INPUT; CHAR(1)

Format of the key string parameter.
Following are the valid values.

0	Binary string. The key is specified as a binary value. To obtain a good random key value, use the Generate Symmetric Key (OPM, QC3GENSK; ILE, Qc3GenSymmetricKey), or Generate Pseudorandom Numbers (OPM, QC3GENRN; ILE, Qc3GenPRNs) API.
1	BER string. If the key type field specifies 50 (RSA public), the key may be specified in BER encoded X.509 Certificate or SubjectPublicKeyInfo format. For specifications of these formats, refer to RFC 3280. If the key type field specifies 51 (RSA private), the key must be specified in BER encoded PKCS #8 format. For specifications of this format, refer to RSA Security Inc. Public-Key Cryptography Standards. To generate a PKA key pair, use the Generate PKA Key Pair (OPM, QC3GENPK; ILE, Qc3GenPKAKeyPair) API.
6	PEM certificate. The key string parameter contains a PEM based certificate.

Key type

INPUT; BINARY(4)

The type of key.
Following are the valid values.

1	MD5 The key format must be 0. 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 The key format must be 0. 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 The key format must be 0. 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 The key format must be 0. 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 The key format must be 0. 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 The key format must be 0. The key must be 8 bytes in length. Only 7 bits of each byte are used as the actual key. The rightmost bit of each byte is used to set parity. Some cryptographic service providers require that a DES key have odd parity in every byte. Others ignore parity.
21	Triple DES The key format must be 0. The key must be 8, 16, or 24 bytes in length. 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 24 bytes are supplied in the key string, 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 16 bytes are supplied, the first 8 bytes are used for key 1 and key 3, and the second 8 bytes for key 2. If only 8 bytes are supplied, it will be used for all 3 keys (essentially making the operation equivalent to a single DES operation). Only 7 bits of each byte are used as the actual key. The rightmost bit of each byte is used to set parity. Some cryptographic service providers require that a Triple DES key have odd parity in every byte. Others ignore parity.
22	AES The key format must be 0. The key must be 16, 24, or 32 bytes in length.
23	RC2 The key format must be 0. The key must be from 1 to 128 bytes in length.
30	RC4-compatible The key format must be 0. The key must be from 1 to 256 bytes in length. Because of the nature of the RC4-compatible algorithm, using the same key for more than one message will severely compromise security.
50	RSA public The key format must be 1 or 6.
51	RSA private The key format must be 1.

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.

Key form

INPUT; CHAR(1)

An indicator specifying if the key string parameter is in encrypted form.

0	Clear. The key string is not encrypted.
1	Encrypted. The key string is encrypted. The key-encrypting key context token and key-encrypting algorithm context token parameters are used to decrypt the key string when a cryptographic operation is performed. This option is only allowed with key formats 0 (binary string) and 1 (BER string.)

Key-encrypting key context token

INPUT; CHAR(8)

The key context token specifying the key for decrypting the key string parameter. If the key string parameter is not encrypted (key form parameter is 0), this parameter must be set to blanks or the pointer to this parameter set to NULL.

Key-encrypting algorithm context token

INPUT; CHAR(8)

The algorithm context token specifying the algorithm for decrypting the key string parameter. If the key string parameter is not encrypted (key form parameter is 0), this parameter must be set to 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.

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.
CPF9D9E D	Record label already exists.
CPF9D9F D	Not authorized to key store file.
CPF9DA0 D	Error occured opening key store file.
CPF9DA5 D	Key store file not found.
CPF9DA6 D	The key store file is not available.
CPF9DA7 D	File is corrupt or not a valid key store file.
CPF9DA9 D	The PEM certificate contains invalid formatting.
CPF9DAC E	Disallowed function value not valid.
CPF9DB3 E	Qualified key store file name not valid.
CPF9DB6 E	Record label not valid.
CPF9DB7 E	Error occured writing to key store.
CPF9DB8 E	Error occured retrieving key record from key store.
CPF9DC2 E	Key-encrypting algorithm context not compatible with key-encrypting key context.
CPF9DC6 E	Algorithm not valid for encrypting or decrypting a key.
CPF9DD7 E	The key-encrypting key context for the specified key is not valid or was previously destroyed.
CPF9DD8 E	The key-encrypting algorithm context for the specified key is not valid or was previously destroyed.
CPF9DDA E	Unexpected return code &1.
CPF9DDB E	The key string or Diffie-Hellman parameter string is not valid.
CPF9DDD E	The key string length is not valid.
CPF9DE7 E	Key type not valid.
CPF9DE8 E	Key form not valid.
CPF9DE9 E	Key format not valid.
CPF9DF1 E	The algorithm context token does not reference a valid algorithm context.
CPF9DF3 E	Algorithm in algorithm context not valid for requested operation.
CPF9DF4 E	The key context token does not reference a valid key context.
CPF9DFC E	The key-encrypting algorithm or key context token is not valid.

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.

CPF9D9E D

Record label already exists.

CPF9D9F D

Not authorized to key store file.

CPF9DA0 D

Error occured opening key store file.

CPF9DA5 D

Key store file not found.

CPF9DA6 D

The key store file is not available.

CPF9DA7 D

File is corrupt or not a valid key store file.

CPF9DA9 D

The PEM certificate contains invalid formatting.

CPF9DAC E

Disallowed function value not valid.

CPF9DB3 E

Qualified key store file name not valid.

CPF9DB6 E

Record label not valid.

CPF9DB7 E

Error occured writing to key store.

CPF9DB8 E

Error occured retrieving key record from key store.

CPF9DC2 E

Key-encrypting algorithm context not compatible with key-encrypting key context.

CPF9DC6 E

Algorithm not valid for encrypting or decrypting a key.

CPF9DD7 E

The key-encrypting key context for the specified key is not valid or was previously destroyed.

CPF9DD8 E

The key-encrypting algorithm context for the specified key is not valid or was previously destroyed.

CPF9DDA E

Unexpected return code &1.

CPF9DDB E

The key string or Diffie-Hellman parameter string is not valid.

CPF9DDD E

The key string length is not valid.

CPF9DE7 E

Key type not valid.

CPF9DE8 E

Key form not valid.

CPF9DE9 E

Key format not valid.

CPF9DF1 E

The algorithm context token does not reference a valid algorithm context.

CPF9DF3 E

Algorithm in algorithm context not valid for requested operation.

CPF9DF4 E

The key context token does not reference a valid key context.

CPF9DFC E

The key-encrypting algorithm or key context token is not valid.