Calculate Diffie-Hellman Secret Key (QC3CALDS, Qc3CalculateDHSecretKey)

Required Parameter Group:

1	D-H algorithm context token	Input	Char(8)
2	D-H public key	Input	Char(*)
3	Length of D-H public key	Input	Binary(4)
4	D-H secret key	Output	Char(*)
5	Length of area provided for D-H secret key	Input	Binary(4)
6	Length of D-H secret key returned	Output	Binary(4)
7	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. To share a secret key between two parties, both parties calculate the shared secret key using their own private key and the other party's public key. To share a secret key with more than two parties, see the example below.

Authorities and Locks

Required API authority

*USE

Required device description authority

*USE

Required Parameter Group

D-H algorithm context token

INPUT; CHAR(8)

The token for the D-H algorithm context.
This must be the token for the algorithm context that was created using the Generate Diffie-Hellman Key Pair (OPM, QC3GENDK; ILE, Qc3GenDHKeyPair) API. The D-H parameters and private key are contained in the context. 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

INPUT; CHAR(*)

The other party's D-H public key.
This is the public key from the party with whom the secret key will be shared

Length of D-H public key

INPUT; BINARY(4)

The length of key specified in the D-H public key parameter.

D-H secret key

OUTPUT; CHAR(*)

The area to store the D-H secret key.
The entire output of the secret key may not be needed and the two parties must agree on which bytes of the secret value will be used.

Length of area provided for D-H secret key

INPUT; BINARY(4)

The length of the D-H secret key parameter in bytes.
The size of the secret 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 and round up to obtain the length of area needed for the D-H secret key.

Length of D-H secret key returned

OUTPUT; BINARY(4)

The length of the D-H secret key returned in the D-H secret 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 secret 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.
CPF9DCA E	Length of D-H (Diffie-Hellman) public key not valid.
CPF9DD6 E	Length of area provided for output data is too small.
CPF9DDA E	Unexpected return code &1.
CPF9DF1 E	The algorithm context token does not reference a valid algorithm context.
CPF9DF2 E	The algorithm context is not found or was previously destroyed.

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.

CPF9DCA E

Length of D-H (Diffie-Hellman) public key not valid.

CPF9DD6 E

Length of area provided for output data is too small.

CPF9DDA E

Unexpected return code &1.

CPF9DF1 E

The algorithm context token does not reference a valid algorithm context.

CPF9DF2 E

The algorithm context is not found or was previously destroyed.

Beth uses Generate Diffie-Hellman Parameters and sends the output to Kathy and Terry.

Beth uses Generate Diffie-Hellman Key Pair to generate a private value (stored in a Diffie-Hellman algorithm context), and a public value B1, which she sends to Kathy.

Kathy uses Generate Diffie-Hellman Key Pair to generate a private value (stored in a Diffie-Hellman algorithm context), and a public value K1, which she sends to Terry.

Terry uses Generate Diffie-Hellman Key Pair to generate a private value (stored in a Diffie-Hellman algorithm context), and a public value T1, which he sends to Beth.

Beth specifies T1 on Calculate Diffie-Hellman Secret Key to create another public value B2, which she sends to Kathy.

Kathy specifies B1 on Calculate Diffie-Hellman Secret Key to create another public value K2, which she sends to Terry.

Terry specifies K1 on Calculate Diffie-Hellman Secret Key to create another public value T2, which he sends to Beth.

Beth specifies T2 on Calculate Diffie-Hellman Secret Key to create the shared secret key, S.

Kathy specifies B2 on Calculate Diffie-Hellman Secret Key to create the shared secret key, S.

Terry specifies K2 on Calculate Diffie-Hellman Secret Key to create the shared secret key, S.