Generate Elliptic Curve Diffie-Hellman Key Pair (QC3GENECDK, Qc3GenECDHKeyPair) API
Required Parameter Group:
| 1 | Domain parameters | Input | Char(*) |
| 2 | Length of domain parameters | Input | Binary(4) |
| 3 | Algorithm type | Input | Binary(4) |
| 4 | Cryptographic service provider | Input | Char(1) |
| 5 | Cryptographic device name | Input | Char(10) |
| 6 | ECDH algorithm context token | Output | Char(8) |
| 7 | ECDH public key | Output | Char(*) |
| 8 | Length of area provided for ECDH public key | Input | Binary(4) |
| 9 | Length of ECDH public key returned | Output | Binary(4) |
| 10 | Error code | I/O | Char(*) |
Service Program Name: QC3DH
Default Public Authority: *USE
Threadsafe: Yes
Elliptic Curve Diffie-Hellman (D-H) is a public key algorithm used for producing a shared secret key. It is documented in Standards for Efficient Cryptography, SEC1: Elliptic Curve Cryptography and ANSI X9.63. ECDH is an elliptic curve varient of the standard Diffie-Hellamn key agreement protocol described in RFC 2631 and Public Key Cryptography Standard (PKCS) #3. The Generate Elliptic Curve Diffie-Hellman Key Pair (OPM, QC3GENECDK; ILE, Qc3GenECDHKeyPair) 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.
ECDH is specified as two primitives, the Elliptic Curve Diffie-Hellman primitive (ECDH) and the Elliptic Curve Cofactor Diffie-Hellman primitive (ECDH_Cofactor), such that ECDH is the direct analogue of the the Diffie-Hellman key agreement protocol, and ECDH_Cofactor also uses the cofactor of the curve to increase the overall security.
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
- Domain parameters
- INPUT; CHAR(*)
The ASN.1 BER encoded domain parameters.
Domain parameters are used to create 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. - Length of domain parameters
- INPUT; BINARY(4)
The length of the domain parameters.
- Algorithm type
- INPUT; BINARY(4)
The ECDH Algorithm primitive type:
53 ECDH
Direct analogue of the standard Diffie-Hellman Key Agreement protocol.54 ECDH_Cofactor
Utilizes the curve cofactor parameter in computing the shared secret key.
- Cryptographic service provider
- INPUT; CHAR(1)
The cryptographic service provider (CSP) that will perform the ECDH operations.
0 Any CSP.
The system will choose an appropriate CSP to perform the D-H operations.1 Software CSP.
The system will perform the ECDH operations using software. If the requested algorithm is not available in software, an error is returned.2 Hardware CSP.
Not supported.
- Cryptographic device name
- INPUT; CHAR(10)
This parameter must be blanks or the pointer to this parameter set to NULL.
- ECDH algorithm context token
- OUTPUT; CHAR(8)
The area to store the token for the created ECDH algorithm context. The domain 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.
- ECDH public key
- OUTPUT; CHAR(*)
The area to store the ECDH public key.
The ECDH public key must be given to the party with whom the secret key will be shared. - Length of area provided for ECDH public key
- INPUT; BINARY(4)
The length of the ECDH public key parameter in bytes.
The number of bytes provided for the public key parameter. - Length of ECDH public key returned
- OUTPUT; BINARY(4)
The length of the generated ECDH public key returned in the ECDH 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 ECDH 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. |
| 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. |
| 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: V7R2
[ Back to top | Cryptographic Services APIs | APIs by category ]