368 lines
10 KiB
HTML
368 lines
10 KiB
HTML
<!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>
|
|
|