Generate PKA Key Pair (QC3GENPK, Qc3GenPKAKeyPair) API
Required Parameter Group:
| 1 | Key type | Input | Binary(4) |
| 2 | Key size | Input | Binary(4) |
| 3 | Public key exponent | Input | Binary(4) |
| 4 | Key format | Input | Char(1) |
| 5 | Key form | Input | Char(1) |
| 6 | Key-encrypting key | Input | Char(*) |
| 7 | Key-encrypting algorithm | Input | Char(8) |
| 8 | Cryptographic service provider | Input | Char(1) |
| 9 | Cryptographic device name | Input | Char(10) |
| 10 | Private key string | Output | Char(*) |
| 11 | Length of area provided for private key string | Input | Binary(4) |
| 12 | Length of private key string returned | Output | Binary(4) |
| 13 | Public Key string | Output | Char(*) |
| 14 | Length of area provided for public key string | Input | Binary(4) |
| 15 | Length of public key string returned | Output | Binary(4) |
| 16 | Error code | I/O | Char(*) |
Service Program Name: QC3KEYGN
Default Public Authority: *USE
Threadsafe: Yes
The Generate PKA Key Pair (OPM, QC3GENPK; ILE, Qc3GenPKAKeyPair) API generates a random PKA key pair that can be used with the PKA cipher algorithm RSA.
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.50 RSA
- Key size
- INPUT; BINARY(4)
The modulus length in bits.
The key size must be an even number in the range 512 - 4096. - Public key exponent
- INPUT; BINARY(4)
To maximize performance, the public key exponent is limited to the following two values.
3 Or hex 00 00 00 03. 65,537 Or hex 00 01 00 01.
- Key format
- INPUT; CHAR(1)
The format in which to return the key.
Following are the valid values.1 BER string. The private key is returned in BER encoded PKCS #8 format. For specifications of this format, refer to RSA Security Inc. Public-Key Cryptography Standards. The public key is returned in BER encoded X.509 SubjectPublicKeyInfo format. For specifications of this format, refer to RFC 3280.
- Key form
- INPUT; CHAR(1)
The form in which to return the private key string.
0 Clear.
The key string is returned in the clear.1 Encrypted.
The private 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 private key string before returning it.2 Encrypted with a master key
The private 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 private key string.
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 encryption, set the value to 14. This value should be saved along with the encrypted private key string because it will be required when the encrypted private key string 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 private key string.
- Cryptographic service provider
- INPUT; CHAR(1)
The cryptographic service provider (CSP) that will perform the key generate operation.
1 Software CSP.
The system will perform the PKA key pair generation using software.
- Cryptographic device name
- INPUT; CHAR(10)
This parameter must be set to blanks or the pointer to this parameter set to NULL.
- Private key string
- OUTPUT; CHAR(*)
The area to store the generated private key string or the pointer to this parameter set to NULL.
- Length of area provided for the private key string
- INPUT; BINARY(4)
The length of the private key string parameter. At most, the generated private key string will be 2400 bytes.
- Length of private key string returned
- OUTPUT; BINARY(4)
The length of the generated private key string returned in the private key string parameter.
If the length of area provided is too small, an error will be generated and no data will be returned in the private key string parameter. - Public key string
- OUTPUT; CHAR(*)
The area to store the public key string.
- Length of area provided for the public key string
- INPUT; BINARY(4)
The length of the public key string parameter. At most, the public key string will be 512 bytes.
- Length of public key string returned
- OUTPUT; BINARY(4)
The length of the public key string returned in the public key string parameter.
If the length of area provided is too small, an error will be generated and no data will be returned in the public 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. |
| CPF9DEB E | Public key exponent not valid. |
| CPF9DEC E | Cryptographic service provider not valid. |
| 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. |
| 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. |
API introduced: V5R3
[ Back to top | Cryptographic Services APIs | APIs by category ]