Calculate Diffie-Hellman Secret Key (QC3CALDS, Qc3CalculateDHSecretKey) API

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.

ECDH and ECDH_Cofactor, documented in FIPS PUB 186-3, is an elliptic curve analog to the standard Diffie-Hellman Key Agreement protocol. Domain parameters are used to create the key pairs and specify attributes that define the elliptic curve on which to perform operations. The current supported named curves are the NIST named curves defined in the Digital Signature Standard (FIPS PUB 186-3) and the set of BRAINPOOL curves defined in RFC 5639. The domain parameters are passed to the API Generate EC Diffie-Hellman Key Pair (QC3GENECDK, Qc3GenECDHKeyPair) along with the type of ECDH Key Agreement protocol. Finally, the algorithm context token containing the ECDH key pair is passed to this API to compute the shared secret key.

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 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 by using the Generate Diffie-Hellman Key Pair (OPM, QC3GENDK; ILE, Qc3GenDHKeyPair) API or Generate Elliptic Curve Diffie-Hellman Key Pair (OPM, QC3GENECDK; ILE, Qc3GenECDHKeyPair) 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.

Error Messages

Example of Three-Party Shared Secret Key Exchange

1. Beth uses Generate Diffie-Hellman Parameters and sends the output to Kathy and Terry.
2. 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.
3. 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.
4. 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.
5. Beth specifies T1 on Calculate Diffie-Hellman Secret Key to create another public value B2, which she sends to Kathy.
6. Kathy specifies B1 on Calculate Diffie-Hellman Secret Key to create another public value K2, which she sends to Terry.
7. Terry specifies K1 on Calculate Diffie-Hellman Secret Key to create another public value T2, which he sends to Beth.
8. Beth specifies T2 on Calculate Diffie-Hellman Secret Key to create the shared secret key, S.
9. Kathy specifies B2 on Calculate Diffie-Hellman Secret Key to create the shared secret key, S.
10. Terry specifies K2 on Calculate Diffie-Hellman Secret Key to create the shared secret key, S.

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