Generate Symmetric Key (QC3GENSK, Qc3GenSymmetricKey)
Required Parameter Group:
| 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(*) |
Service Program Name: QC3KEYGN
Default Public Authority: *USE
Threadsafe: Yes
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.
Authorities and Locks
- Required device description authority
- *USE
Required Parameter Group
- Key type
- INPUT; BINARY(4)
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.
- Key size
- INPUT; BINARY(4)
The length of key to generate in bytes.
Refer to the key type parameter for restrictions. - Key format
- INPUT; CHAR(1)
The format in which to return the key.
Following are the valid values.0 Binary string.
The key is returned as a binary value. - Key form
- INPUT; CHAR(1)
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.
- Key-encrypting key
- INPUT; CHAR(*)
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
- Master key ID
- 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
- Reserved
- Must be null (binary 0s).
- Disallowed function
- INPUT; BINARY(4)
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.
- Master key KVV
- The key verification value of the master key that was used to encrypt
the key is returned in this field. This value should be saved along with the
encrypted key value. When the encrypted key value is used on an API and the KVV
is supplied, the API will be able to determine which version of the master key
should be used to decrypt the key. This field must be null (binary 0s)
on input.
- 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 encrypting the generated key.
- Cryptographic service provider
- INPUT; CHAR(1)
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.
- Cryptographic device name
- INPUT; CHAR(10)
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. - Key string
- OUTPUT; CHAR(*)
The area to store the generated key string.
- Length of area provided for key string
- INPUT; BINARY(4)
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. - Length of key string returned
- OUTPUT; BINARY(4)
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. - 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. |
| 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. |
API introduced: V5R3
[ Back to top | Cryptographic Services APIs | APIs by category ]