Extract Public Key (QC3EXTPB, Qc3ExtractPublicKey) API

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

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