Extract Public Key (QC3EXTPB, Qc3ExtractPublicKey)

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 key store. 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.

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.

The key string parameter identifies a key in key store. To create a key in key store, use the Generate Key Record (OPM, QC3GENKR; ILE, Qc3GenKeyRecord) or Write Key Record (OPM, QC3WRTKR; ILE, Qc3WriteKeyRecord) API. The key string parameter should contain the following structure:

Offset		Type	Field
Dec	Hex	Type	Field
0	0	CHAR(20)	Qualified key store file name
20	14	CHAR(32)	Record label
52	34	CHAR(4)	Reserved

Qualified key store file name

The key store 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 key store 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 key store 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	Type	Field
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.

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 key store file.
CPF9DA0 E	Error occured opening key store file.
CPF9DA1 E	Key record not found.
CPF9DA5 E	Key store file not found.
CPF9DA6 E	The key store file is not available.
CPF9DA7 E	File is corrupt or not a valid key store 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 key store file name not valid.
CPF9DB6 E	Record label not valid.
CPF9DB8 E	Error occured retrieving key record from key store.
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.

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 key store file.

CPF9DA0 E

Error occured opening key store file.

CPF9DA1 E

Key record not found.

CPF9DA5 E

Key store file not found.

CPF9DA6 E

The key store file is not available.

CPF9DA7 E

File is corrupt or not a valid key store 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 key store file name not valid.

CPF9DB6 E

Record label not valid.

CPF9DB8 E

Error occured retrieving key record from key store.

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.