Create Key Context (QC3CRTKX, Qc3CreateKeyContext) API
Required Parameter Group:
1 | Key string | Input | Char(*) |
2 | Length of key string | Input | Binary(4) |
3 | Key format | Input | Char(1) |
4 | Key type | Input | Binary(4) |
5 | Key form | Input | Char(1) |
6 | Key-encrypting key | Input | Char(*) |
7 | Key-encrypting algorithm | Input | Char(8) |
8 | Key context token | Output | Char(8) |
9 | Error code | I/O | Char(*) |
Service Program Name: QC3CTX
Default Public Authority: *USE
Threadsafe: Yes
The Create Key Context (OPM, QC3CRTKX; ILE, Qc3CreateKeyContext) API creates a temporary area for holding a cryptographic key. The API returns a token which can be used on subsequent cryptographic APIs when specifying a key. The key context can not be shared between jobs. It should be destroyed by using the Destroy Key Context (OPM, QC3DESKX; ILE, Qc3DestroyKeyContext) API. If the key context is not destroyed before relinquishing control, it could be used by other users of the job. If not explicitly destroyed, the key context will be destroyed at job end.
Information on cryptographic standards can be found in Create Algorithm Context (OPM, QC3CRTAX; ILE, Qc3CreateAlgorithmContext) API.
Authorities and Locks
- Required file authority
- *OBJOPR, *READ
Required Parameter Group
- Key string
- INPUT; CHAR(*)
A binary string, a formatted structure containing the key, or a reference to the location of 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 4 (a stored key) then the key length is obtained from the stored key record.
- If key format is 5 (a PKCS5 key) then the key length is the specified derived key length.
- If key format is 6 (PEM certificate) then the key length will be the length specified in the certificate.
- If key format is 7 or 8 (a key from certificate store) then the key length will be the length stored in the certificate.
Most algorithms have key length requirements. Refer to the key type parameter for restrictions on key length.
- If key format is 0 (binary string) and
- 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) API or the 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. Similarly, if the key type field specifies 56 (ECC public), the key may be specified in BER encoded X.509 Certificate or SubjectPublicKeyInfo formats. If the key type field specifies 57 (ECC private), the key must be specified in BER encoded PKCS #8 format. For details related to the ECC public and private key syntax, see also SEC1 and ANSI X9.62. To generate an elliptic curve PKA key pair, use the Generate ECC Key Pair (OPM, QC3GENECC; ILE, Qc3GenECCKeyPair) API.
4 Keystore label. The key string parameter identifies a key from keystore. To create a key in keystore, use the Generate Key Record (OPM, QC3GENKR; ILE, Qc3GenKeyRecord) API or the Write Key Record (OPM, QC3WRTKR; ILE, Qc3WriteKeyRecord) API. The length of key string parameter must specify 56. The key string parameter should contain the following structure:
Offset Type Field Dec Hex 0 0 CHAR(20) Qualified keystore file name 20 14 CHAR(32) Record label 52 34 CHAR(4) Reserved
- Qualified keystore file name
- The keystore file where the key is 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
- The label of 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).
- Reserved
- Must be null (binary 0s).
5 PKCS5 passphrase. A key is derived using RSA Data Security, Inc. Public-Key Cryptography Standard (PKCS) #5. The length of key string parameter must be in the range of 41 to 296. The key string parameter should contain the following structure:
Offset Type Field Dec Hex 0 0 CHAR(4) Reserved 4 4 BINARY(4) Derived key length 8 8 BINARY(4) Iteration count 12 C BINARY(4) Salt length 16 10 CHAR(16) Salt 32 20 BINARY(4) Passphrase CCSID 36 24 BINARY(4) Passphrase length 40 28 CHAR(*) Passphrase
- Reserved
- Must be null (binary 0s).
- Derived key length
- The length of key requested. The minimum allowed length is 1.
- Iteration count
- Used to greatly increase the cost of an exhaustive search
while modestly increasing the cost of key derivation.
The minimum allowed value is 1. The standard recommends
a minimum of 1,000.
The maximum allowed length is 100,000.
- Salt length
- The length of salt. The length must be in the range of 1 to 16.
- Salt
- Used to help thwart attacks by producing a large set
of keys for each passphrase. The standard recommends the salt be
generated at random and be at least 8 bytes long. You can use the
Generate Pseudorandom Numbers (OPM, QC3GENPRN;
ILE, Qc3GenPRNs) API to obtain a random value. Additionally,
data that distinguishes between various operations can be added to the salt
for additional security. Refer to the standard for more information.
- Passphrase CCSID
- INPUT; BINARY(4)
The CCSID of the passphrase. The passphrase will be converted from the specified CCSID to Unicode before calling the PKCS5 algorithm.
-1 The CCSID of the job is ignored and no conversion of the passphrase data will occur. The raw octet string of the passphrase will be directly passed to the PKCS5 algorithm. 0 The CCSID of the job is used to determine the CCSID of the data to be converted. If the job CCSID is 65535, the CCSID from the default CCSID (DFTCCSID) job attribute is used. 1-65533 A valid CCSID in this range is used. For a list of valid CCSIDs, see the i5/OS globalization topic collection.
- Passphrase length
- The length of passphrase. The length must be in the range of 1 to 256.
- Passphrase
- A text string.
6 PEM certificate. The key string parameter contains an ASCII encoded 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, 4, or 5. 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, 4, or 5. 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, 4, or 5. 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, 4, or 5. 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, 4, or 5. 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, 4, or 5. 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, 4, or 5. 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, 4, or 5. The key must be 16, 24, or 32 bytes in length.23 RC2
The key format must be 0, 4, or 5. The key must be from 1 to 128 bytes in length.30 RC4-compatible
The key format must be 0, 4, or 5. The key must be from 1 to 256 bytes in length. Because of the nature of the RC4-compatible operation, using the same key for more than one message will severely compromise security.50 RSA public
The key format must be 1, 4, or 6.51 RSA private
The key format must be 1 or 4.56 ECC public
The key format must be 1 or 4.57 ECC private
The key format must be 1 or 4.
- 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 with a KEK
The key string is encrypted with a key-encrypting key. Tokens are specified in the key-encrypting key and key-encrypting algorithm parameters and 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.)2 Encrypted with a master key
The key string is encrypted with a master key. The master key is specified in the key-encrypting key parameter. This option is only allowed with key formats 0 (binary string) and 1 (BER string.)
- Key-encrypting key
- INPUT; CHAR(*)
The key under which the key string parameter is encrypted
For key form 0 (clear), this parameter must be set to blanks or the pointer to this parameter set to NULL.
For key form 1 (encrypted), this parameter specifies the 8-byte key context token to use for decrypting the key string parameter.
For key form 2 (encrypted with a master key), this parameter has the following structure:
Offset Type Field Dec Hex 0 0 BINARY(4) Master key ID 4 4 CHAR(4) Reserved 8 8 BINARY(4) Disallowed function 12 C CHAR(20) Master key KVV
- Master key ID
- The master key to use for decrypting the key string parameter.
The master key IDs are
1 Master key 1 2 Master key 2 3 Master key 3 4 Master key 4 5 Master key 5 6 Master key 6 7 Master key 7 8 Master key 8
- Disallowed function
- INPUT; BINARY(4)
This parameter specifies the functions that are not allowed to be used with this key. This value was XOR'd into the master key when this key was encrypted and therefore must be used when creating a key context for this key. 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.
- Master key KVV
- The master key verification value. The master key version with a KVV that
matches this value will be used to decrypt the key. If this value is
null, the current version of the master key will be used.
- Reserved
- Must be null (binary 0s).
- Key-encrypting algorithm
- INPUT; CHAR(8)
For key form 0 (clear) and 2 (encrypted with a master key), this parameter must be set to blanks or the pointer to this parameter set to NULL.
For key form 1 (encrypted), this parameter specifies the algorithm context token to use for decrypting the key string parameter.
- Key context token
- OUTPUT; CHAR(8)
The area to store the token for the created key context.
Each token will contain an authentication value. If the token is used on a subsequent API but with an incorrect authentication value, the user will be subjected to a 10 second penalty wait. For each authentication error in that job, the penalty wait will increase 10 seconds up to a maximum of 10 minutes.
- 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
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. |
CPF9D9F E | Not authorized to keystore file. |
CPF9DA0 E | Error occured opening keystore file. |
CPF9DA1 E | Key record not found. |
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. |
CPF9DAD E | The master key ID is not valid. |
CPF9DB1 E | The CCSID is not valid. |
CPF9DB3 E | Qualified keystore file name not valid. |
CPF9DB6 E | Record label not valid. |
CPF9DB8 E | Error occured retrieving key from keystore. |
CPF9DBA E | Derived key length not valid. |
CPF9DBB E | Iteration count not valid. |
CPF9DBC E | Salt length not valid. |
CPF9DBD E | Passphrase length not valid. |
CPF9DDA E | Unexpected return code &1. |
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. |
CPF9DEE E | Reserved field not null. |
CPF9DF1 E | The algorithm context token does not reference a valid algorithm context. |
CPF9DF2 E | The algorithm context is not found or was previously destroyed. |
CPF9DF3 E | Algorithm in algorithm context not valid for requested operation. |
CPF9DF4 E | The key context token does not reference a valid key context. |
CPF9DF5 E | The key context is not found or was previously destroyed. |
CPF9DF7 E | Algorithm context not compatible with key context. |
CPF9DFC E | The key-encrypting algorithm or key context token is not valid. |
API introduced: V5R3
[ Back to top | Cryptographic Services APIs | APIs by category ]