| 1 | Key type | Input | Binary(4) |
| 2 | Key size | Input | Binary(4) |
| 3 | Key format | Input | Char(1) |
| 4 | Key form | Input | Char(1) |
| 5 | Key-encrypting key | Input | Char(*) |
| 6 | Key-encrypting algorithm | Input | Char(8) |
| 7 | Cryptographic service provider | Input | Char(1) |
| 8 | Cryptographic device name | Input | Char(10) |
| 9 | Key string | Output | Char(*) |
| 10 | Length of area provided for key string | Input | Binary(4) |
| 11 | Length of key string returned | Output | Binary(4) |
| 12 | Error code | I/O | Char(*) |
The Generate Symmetric Key (OPM, QC3GENSK; ILE, Qc3GenSymmetricKey) API generates a random key value that can be used with symmetric cipher algorithms DES, Triple DES, AES, RC2, and RC4-compatible, or the HMAC algorithms MD5, SHA-1, SHA-256, SHA-384, and SHA-512.
Information on cryptographic standards can be found in Create Algorithm Context (OPM, QC3CRTAX; ILE, Qc3CreateAlgorithmContext) API.
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. AES keys are supported only by the software CSP. |
| 23 | RC2 The key size can be 1 - 128. RC2 keys are supported only by the software CSP. |
| 30 | RC4-compatible The key size can be 1 - 256. RC4-compatible keys are supported only by the software CSP. Because of the nature of the RC4-compatible operation, using the same key for more than one message will severely compromise security. |
The length of key to generate in bytes.
Refer to the key type parameter for restrictions.
The format in which to return the key.
Following are the valid values.
| 0 | Binary string. The key is returned as a binary value. |
The form in which to return the key.
| 0 | Clear. The key string is returned in the clear. |
| 1 | Encrypted. The key string is returned encrypted with a key-encrypting key. Tokens are specified in the key-encrypting key and key-encrypting algorithm parameters and used to encrypt the generated key before returning it. |
| 2 | Encrypted with a master key The key string is returned encrypted with a master key. The master key is specified in the key-encrypting key parameter. |
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 key context token to use to encrypt the generated key.
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 |
| 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 |
This parameter specifies the functions that cannot be used with 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. This value should be saved along with the encrypted key value because it will be required when the encrypted key value is used on an API.
| 0 | No functions are disallowed. |
| 1 | Encryption is disallowed. |
| 2 | Decryption is disallowed. |
| 4 | MACing is disallowed. |
| 8 | Signing is disallowed. |
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 encrypting the generated key.
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. If the requested key type or form is not available in software, an error is returned. |
| 2 | Hardware CSP. The system will perform the key generate operation using cryptographic hardware. If the requested key type or form is not available 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. |
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.
The area to store the generated key string.
The length of the key string parameter.
The length of the generated key string will be the length specified in the key size parameter. If the key form specifies 1 (encrypted), you must allow room for padding the encrypted key string to the next block length multiple. (e.g. Add an additional 8 bytes for DES.) For more information on block length, see Create Algorithm Context (OPM, QC3CRTAX; ILE, Qc3CreateAlgorithmContext) API.
The length of the key string returned in the key string parameter.
If the length of area provided for the key string is too small, an error will be generated and no data will be returned in the key string parameter.
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. |
| CPF9D94 E | A pending value exists for a master key. |
| CPF9DAA D | A key requires translation. |
| CPF9DAB E | A key can not be decrypted. |
| CPF9DAC E | Disallowed function value not valid. |
| CPF9DAD E | The master key ID is not valid. |
| CPF9DAF E | Version &2 of master key &1 is not set. |
| CPF9DC2 E | Key-encrypting algorithm context not compatible with key-encrypting key context. |
| CPF9DC4 E | A key-encrypting algorithm context token does not reference a valid algorithm context. |
| CPF9DC5 E | A key-encrypting key context token does not reference a valid key context. |
| CPF9DC6 E | Algorithm not valid for encrypting or decrypting a key. |
| CPF9DD6 E | Length of area provided for output data is too small. |
| 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. |
| CPF9DE7 E | Key type not valid. |
| CPF9DE8 E | Key form not valid. |
| CPF9DE9 E | Key format not valid. |
| CPF9DEA E | Key size not valid. |
| CPF9DEC E | Cryptographic service provider not valid. |
| CPF9DEE E | Reserved field not null. |
| CPF9DF0 E | Operation, algorithm, or mode not available on the requested CSP (cryptographic service provider). |
| 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. |
| CPF9DF6 E | Key can not be encrypted. |
| CPF9DF7 E | Algorithm context not compatible with key context. |
| CPF9DF8 E | Cryptographic device name not valid. |
| CPF9DF9 E | Cryptographic device not found. |
| CPF9DFB E | Cryptographic service provider (CSP) conflicts with the key context CSP. |
| CPF9DFC E | The key-encrypting algorithm or key context token is not valid. |
| CPF9DFD E | Not authorized to device. |
| CPF9DFE E | Cryptographic device not available. |
[ Back to top | Cryptographic Services APIs | APIs by category ]