Generate PKA Key Pair (QC3GENPK, Qc3GenPKAKeyPair)

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 the Create Algorithm Context (OPM, QC3CRTAX; ILE, Qc3CreateAlgorithmContext) API documentation.

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 - 2048.

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 1504 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.
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.