Generate Diffie-Hellman Key Pair (QC3GENDK, Qc3GenDHKeyPair)

Diffie-Hellman (D-H) is a public key algorithm used for producing a shared secret key. It is described in RFC 2631 and Public Key Cryptography Standard (PKCS) #3. The Generate Diffie-Hellman Key Pair (OPM, QC3GENDK; ILE, Qc3GenDHKeyPair) API generates a Diffie-Hellman (D-H) private/public key pair. The key pair is used to create a shared secret key using the Calculate Diffie-Hellman Secret Key (OPM, QC3CALDS; ILE, Qc3CalculateDHSecretKey) API. The key pair can not be used for data encryption or signing.

Information on cryptographic standards can be found in the Create Algorithm Context (OPM, QC3CRTAX; ILE, Qc3CreateAlgorithmContext) API documentation.

Authorities and Locks

Required API authority

*USE

Required device description authority

*USE

Required Parameter Group

D-H parameters

INPUT; CHAR(*)

The ASN.1 BER encoded D-H parameters.
These parameters are obtained from the Generate Diffie-Hellman Parameters (OPM, QC3GENDP; ILE, Qc3GenDHParms) API or from another party.

Length of D-H parameters

INPUT; BINARY(4)

The length of the D-H parameters.

Cryptographic service provider

INPUT; CHAR(1)

The cryptographic service provider (CSP) that will perform the D-H operations (both generate D-H key pair and calucalte D-H secret key).

0	Any CSP. The system will choose an appropriate CSP to perform the D-H operations.
1	Software CSP. The system will perform the D-H operations using software. If the requested algorithm is not available in software, an error is returned.
2	Hardware CSP. The system will perform the D-H operations using cryptographic hardware. If the requested algorithm is not available in hardware, an error is returned. A specific cryptographic device can be specified using the cryptographic device name parameter. If the cryptographic device is not specified, the system will choose an appropriate one.

Cryptographic device name

INPUT; CHAR(10)

The name of a cryptographic device description.
This parameter is valid when the cryptographic service provider parameter specifies 2 (hardware CSP). Otherwise, this parameter must be blanks or the pointer to this parameter set to NULL.

D-H algorithm context token

OUTPUT; CHAR(8)

The area to store the token for the created D-H algorithm context.
The D-H parameters and private key will be stored in the context upon completion of this operation. This token should be supplied on the Calculate Diffie-Hellman Secret Key (OPM, QC3CALDS; ILE, Qc3CalculateDHSecretKey) API. Once the D-H secret key has been calculated, you should destroy the D-H algorithm context using the Destroy Algorithm Context (OPM, QC3DESAX; ILE, Qc3DestroyAlgorithmContext) API.

D-H public key

OUTPUT; CHAR(*)

The area to store the D-H public key.
The D-H public key must be given to the party with whom the secret key will be shared.

Length of area provided for D-H public key

INPUT; BINARY(4)

The length of the D-H public key parameter in bytes.
The size of the public key will be no greater than the key size. (See Generate Diffie-Hellman Parameters (OPM, QC3GENDP; ILE, Qc3GenDHParms) API.) Because key size is normally specified in bits, divide that value by 8 to obtain the length of area needed for the D-H public key.

Length of D-H public key returned

OUTPUT; BINARY(4)

The length of the generated D-H public key returned in the D-H public key parameter.
If the length of area provided is too small, an error will be generated and no data will be returned in the D-H 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