Extract Public Key (QC3EXTPB, Qc3ExtractPublicKey) API


  Required Parameter Group:

1 Key string Input Char(*)
2 Length of key string Input Binary(4)
3 Key string format Input Char(1)
4 Key form Input Char(1)
5 Key-encrypting key Input Char(*)
6 Key-encrypting algorithm Input Char(8)
7 Public key Output Char(*)
8 Length of area provided for public key Input Binary(4)
9 Length of public key returned Output Binary(4)
10 Error code I/O Char(*)

 Service Program Name: QC3PBEXT

 Default Public Authority: *USE

 Threadsafe: Yes

The Extract Public Key (OPM, QC3EXTPB; ILE, Qc3ExtractPublicKey) API extracts a public key from a BER encoded PKCS #8 string or from a key record containing a public or private PKA key.


Authorities and Locks

Required file authority
*OBJOPR, *READ


Required Parameter Group

Key string
INPUT; CHAR(*)

A BER encoded PKCS #8 string, or a formatted structure identifying a key record in keystore. The exact format of the key string is specified in the key string format parameter.

Length of key string
INPUT; BINARY(4)

Length of the key string specified in the key string parameter.

Key string format
INPUT; CHAR(1)

Format of the key string parameter.
Following are the valid values.

1 BER string. 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.
4 The key string parameter identifies a key in 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 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).
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. This option is only allowed with key string format 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 string format 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

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 decrypting the key string. 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 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

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.

Public key
OUTPUT; CHAR(*)

The area to store the public key. This parameter will contain the extracted public key in BER encoded X.509 SubjectPublicKeyInfo format.

Length of area provided for public key
INPUT; BINARY(4)

The length of the public key parameter.

Length of public key returned
OUTPUT; BINARY(4)

The length of the extracted public key returned in the public key parameter.
If the length of area provided for the public key is too small, an error will be generated and no data will be returned in the public key 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.
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.
CPF9DAA D A key requires translation.
CPF9DAB E A key can not be decrypted.
CPF9DAC E Disallowed function value not valid.
CPF9DB3 E Qualified keystore file name not valid.
CPF9DB6 E Record label not valid.
CPF9DB8 E Error occured retrieving key record from keystore.
CPF9DDB E The key string or Diffie-Hellman parameter string is not valid.
CPF9DC2 E Key-encrypting algorithm context not compatible with key-encrypting key context.
CPF9DC3 E Unable to decrypt data or key.
CPF9DC6 E Algorithm not valid for encrypting or decrypting a key.
CPF9DCE E A data length is not valid.
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.
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.
CPF9DF3 E Algorithm in algorithm context not valid for requested operation.
CPF9DF4 E The key context token does not reference a valid key context.
CPF9DFC E The key-encrypting algorithm or key context token is not valid.


API introduced: V5R4

[ Back to top | Cryptographic Services APIs | APIs by category ]