<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> <meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation"> <!-- Begin Header Records --> <!-- All rights reserved. Licensed Materials Property of IBM --> <!-- US Government Users Restricted Rights --> <!-- Use, duplication or disclosure restricted by --> <!-- GSA ADP Schedule Contract with IBM Corp. --> <!-- Created for V5R3 by beth hagemeister 6/19/02 --> <!-- Change history: --> <!-- 030211 JETAYLOR html cleanup --> <!-- 031021 BILLINGS Review 3 updates --> <!-- end header records --> <title>Generate Diffie-Hellman Key Pair (QC3GENDK, Qc3GenDHKeyPair)</title> <link rel="stylesheet" type="text/css" href="../rzahg/ic.css"> </head> <body> <a name="Top_Of_Page"></a> <!--Java sync-link--> <script type="text/javascript" language="Javascript" src="../rzahg/synch.js"> </script> <h2>Generate Diffie-Hellman Key Pair (QC3GENDK, Qc3GenDHKeyPair)</h2> <div class="box" style="width: 80%;"> <br> Required Parameter Group:<br> <!-- iddvc RMBR --> <br> <table width="100%"> <tr> <td align="center" valign="top" width="10%">1</td> <td align="left" valign="top" width="60%">D-H parameters</td> <td align="left" valign="top" width="15%">Input</td> <td align="left" valign="top" width="15%">Char(*)</td> </tr> <tr> <td align="center" valign="top" width="10%">2</td> <td align="left" valign="top" width="60%">Length of D-H parameters</td> <td align="left" valign="top" width="15%">Input</td> <td align="left" valign="top" width="15%">Binary(4)</td> </tr> <tr> <td align="center" valign="top" width="10%">3</td> <td align="left" valign="top" width="60%">Cryptographic service provider</td> <td align="left" valign="top" width="15%">Input</td> <td align="left" valign="top" width="15%">Char(1)</td> </tr> <tr> <td align="center" valign="top" width="10%">4</td> <td align="left" valign="top" width="60%">Cryptographic device name</td> <td align="left" valign="top" width="15%">Input</td> <td align="left" valign="top" width="15%">Char(10)</td> </tr> <tr> <td align="center" valign="top" width="10%">5</td> <td align="left" valign="top" width="60%">D-H algorithm context token</td> <td align="left" valign="top" width="15%">Output</td> <td align="left" valign="top" width="15%">Char(8)</td> </tr> <tr> <td align="center" valign="top" width="10%">6</td> <td align="left" valign="top" width="60%">D-H public key</td> <td align="left" valign="top" width="15%">Output</td> <td align="left" valign="top" width="15%">Char(*)</td> </tr> <tr> <td align="center" valign="top" width="10%">7</td> <td align="left" valign="top" width="60%">Length of area provided for D-H public key</td> <td align="left" valign="top" width="15%">Input</td> <td align="left" valign="top" width="15%">Binary(4)</td> </tr> <tr> <td align="center" valign="top" width="10%">8</td> <td align="left" valign="top" width="60%">Length of D-H public key returned</td> <td align="left" valign="top" width="15%">Output</td> <td align="left" valign="top" width="15%">Binary(4)</td> </tr> <tr> <td align="center" valign="top" width="10%">9</td> <td align="left" valign="top" width="60%">Error code</td> <td align="left" valign="top" width="15%">I/O</td> <td align="left" valign="top" width="15%">Char(*)</td> </tr> </table> <br> Service Program Name: QC3DH<br> <!-- iddvc RMBR --> <br> Default Public Authority: *USE<br> <!-- iddvc RMBR --> <br> Threadsafe: Yes<br> <!-- iddvc RMBR --> <br> </div> <p>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 <a href="qc3calds.htm">Calculate Diffie-Hellman Secret Key (OPM, QC3CALDS; ILE, Qc3CalculateDHSecretKey) API</a>. The key pair can not be used for data encryption or signing.</p> <p>Information on cryptographic standards can be found in the <a href= "qc3crtax.htm">Create Algorithm Context (OPM, QC3CRTAX; ILE, Qc3CreateAlgorithmContext)</a> API documentation.</p> <br> <h3>Authorities and Locks</h3> <dl> <dt><strong>Required API authority</strong></dt> <dd>*USE<br> <br> </dd> <dt><strong>Required device description authority</strong></dt> <dd>*USE<br> <br> </dd> </dl> <br> <h3>Required Parameter Group</h3> <dl> <dt><strong>D-H parameters</strong></dt> <dd>INPUT; CHAR(*) <p>The ASN.1 BER encoded D-H parameters.<br> These parameters are obtained from the <a href="qc3gendp.htm">Generate Diffie-Hellman Parameters (OPM, QC3GENDP; ILE, Qc3GenDHParms) API</a> or from another party.</p> </dd> <dt><strong>Length of D-H parameters</strong></dt> <dd>INPUT; BINARY(4) <p>The length of the D-H parameters.</p> </dd> <dt><strong>Cryptographic service provider</strong></dt> <dd>INPUT; CHAR(1) <p>The cryptographic service provider (CSP) that will perform the D-H operations (both generate D-H key pair and calucalte D-H secret key).</p> <table width="95%"> <tr> <td align="left" valign="top" width="5%"><strong>0</strong></td> <td align="left" valign="top" width="95%">Any CSP.<br> The system will choose an appropriate CSP to perform the D-H operations.</td> </tr> <tr> <td align="left" valign="top"><strong>1</strong></td> <td align="left" valign="top">Software CSP.<br> The system will perform the D-H operations using software. If the requested algorithm is not available in software, an error is returned.</td> </tr> <tr> <td align="left" valign="top"><strong>2</strong></td> <td align="left" valign="top">Hardware CSP.<br> 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.</td> </tr> </table> </dd> <dd><br> </dd> <dt><strong>Cryptographic device name</strong></dt> <dd>INPUT; CHAR(10) <p>The name of a cryptographic device description.<br> 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.</p> </dd> <dt><strong>D-H algorithm context token</strong><br> </dt> <dd>OUTPUT; CHAR(8) <p>The area to store the token for the created D-H algorithm context.<br> 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 <a href= "qc3calds.htm">Calculate Diffie-Hellman Secret Key (OPM, QC3CALDS; ILE, Qc3CalculateDHSecretKey) API</a>. Once the D-H secret key has been calculated, you should destroy the D-H algorithm context using the <a href="qc3desax.htm">Destroy Algorithm Context (OPM, QC3DESAX; ILE, Qc3DestroyAlgorithmContext) API</a>.</p> </dd> <dt><strong>D-H public key</strong></dt> <dd>OUTPUT; CHAR(*) <p>The area to store the D-H public key.<br> The D-H public key must be given to the party with whom the secret key will be shared.</p> </dd> <dt><strong>Length of area provided for D-H public key</strong></dt> <dd>INPUT; BINARY(4) <p>The length of the D-H public key parameter in bytes.<br> The size of the public key will be no greater than the key size. (See <a href= "qc3gendp.htm">Generate Diffie-Hellman Parameters (OPM, QC3GENDP; ILE, Qc3GenDHParms) API</a>.) 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.</p> </dd> <dt><strong>Length of D-H public key returned</strong></dt> <dd>OUTPUT; BINARY(4) <p>The length of the generated D-H public key returned in the D-H public key parameter.<br> 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.</p> </dd> <dt><strong>Error code</strong></dt> <dd>I/O; CHAR(*) <p>The structure in which to return error information.<br> For the format of the structure, see <a href="../apiref/error.htm#hdrerrcod">Error Code Parameter</a>.</p> </dd> </dl> <br> <h3>Error Messages</h3> <table cellpadding="5"> <tr> <th align="left" valign="top">Message ID</th> <th align="left" valign="top">Error Message Text</th> </tr> <tr> <td valign="top" width="15%">CPF24B4 E</td> <td valign="top" width="85%">Severe error while addressing parameter list.</td> </tr> <tr> <td valign="top">CPF3C1E E</td> <td valign="top">Required parameter &1 omitted.</td> </tr> <tr> <td valign="top">CPF3CF1 E</td> <td valign="top">Error code parameter not valid.</td> </tr> <tr> <td valign="top">CPF9872 E</td> <td valign="top">Program or service program &1 in library &2 ended. Reason code &3.</td> </tr> <tr> <td valign="top">CPF9DCB E</td> <td valign="top">Length of D-H (Diffie-Hellman) parameters not valid.</td> </tr> <tr> <td valign="top">CPF9DD6 E</td> <td valign="top">Length of area provided for output data is too small.</td> </tr> <tr> <td valign="top">CPF9DDA E</td> <td valign="top">Unexpected return code &1.</td> </tr> <tr> <td valign="top">CPF9DDB E</td> <td valign="top">The key string or Diffie-Hellman parameter string is not valid.</td> </tr> <tr> <td valign="top">CPF9DDC E</td> <td valign="top">D-H (Diffie-Hellman) parameters not valid.</td> </tr> <tr> <td valign="top">CPF9DEC E</td> <td valign="top">Cryptographic service provider not valid.</td> </tr> <tr> <td valign="top">CPF9DF8 E</td> <td valign="top">Cryptographic device name not valid.</td> </tr> <tr> <td valign="top">CPF9DF9 E</td> <td valign="top">Cryptographic device not found.</td> </tr> <tr> <td valign="top">CPF9DFD E</td> <td valign="top">Not authorized to device.</td> </tr> <tr> <td valign="top">CPF9DFE E</td> <td valign="top">Cryptographic device not available.</td> </tr> </table> <br> <br> <hr> API introduced: V5R3 <hr> <center> <table cellpadding="2" cellspacing="2"> <tr align="center"> <td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href= "catcrypt.htm">Cryptographic Services APIs</a> | <a href="aplist.htm">APIs by category</a></td> </tr> </table> </center> </body> </html>