Generate Diffie-Hellman Key Pair (QC3GENDK, Qc3GenDHKeyPair) API
Required Parameter Group:
| 1 | D-H parameters | Input | Char(*) |
| 2 | Length of D-H parameters | Input | Binary(4) |
| 3 | Cryptographic service provider | Input | Char(1) |
| 4 | Cryptographic device name | Input | Char(10) |
| 5 | D-H algorithm context token | Output | Char(8) |
| 6 | D-H public key | Output | Char(*) |
| 7 | Length of area provided for D-H public key | Input | Binary(4) |
| 8 | Length of D-H public key returned | Output | Binary(4) |
| 9 | Error code | I/O | Char(*) |
Service Program Name: QC3DH
Default Public Authority: *USE
Threadsafe: Yes
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 Create Algorithm Context (OPM, QC3CRTAX; ILE, Qc3CreateAlgorithmContext) API.
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 calculate 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
| 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. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
| CPF9DCB E | Length of D-H (Diffie-Hellman) parameters not valid. |
| CPF9DD6 E | Length of area provided for output data is too small. |
| CPF9DDA E | Unexpected return code &1. |
| CPF9DDB E | The key string or Diffie-Hellman parameter string is not valid. |
| CPF9DDC E | D-H (Diffie-Hellman) parameters not valid. |
| CPF9DEC E | Cryptographic service provider not valid. |
| CPF9DF8 E | Cryptographic device name not valid. |
| CPF9DF9 E | Cryptographic device not found. |
| CPF9DFD E | Not authorized to device. |
| CPF9DFE E | Cryptographic device not available. |
API introduced: V5R3
[ Back to top | Cryptographic Services APIs | APIs by category ]