329 lines
9.3 KiB
HTML
329 lines
9.3 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>Calculate Diffie-Hellman Secret Key (QC3CALDS, Qc3CalculateDHSecretKey)</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>Calculate Diffie-Hellman Secret Key (QC3CALDS, Qc3CalculateDHSecretKey)</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 algorithm context token</td>
|
||
|
|
<td align="left" valign="top" width="15%">Input</td>
|
||
|
|
<td align="left" valign="top" width="15%">Char(8)</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top" width="10%">2</td>
|
||
|
|
<td align="left" valign="top" width="60%">D-H public key</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%">3</td>
|
||
|
|
<td align="left" valign="top" width="60%">Length of 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%">4</td>
|
||
|
|
<td align="left" valign="top" width="60%">D-H secret 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%">5</td>
|
||
|
|
<td align="left" valign="top" width="60%">Length of area provided for D-H
|
||
|
|
secret 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%">6</td>
|
||
|
|
<td align="left" valign="top" width="60%">Length of D-H secret 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%">7</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. 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.</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 algorithm context token</strong><br>
|
||
|
|
</dt>
|
||
|
|
|
||
|
|
<dd>INPUT; CHAR(8)
|
||
|
|
|
||
|
|
<p>The token for the D-H algorithm context.<br>
|
||
|
|
This must be the token for the algorithm context that was created using the <a href=
|
||
|
|
"qc3gendk.htm">Generate Diffie-Hellman Key Pair (OPM, QC3GENDK; ILE,
|
||
|
|
Qc3GenDHKeyPair) API</a>. 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 <a href="qc3desax.htm">Destroy Algorithm
|
||
|
|
Context (OPM, QC3DESAX; ILE, Qc3DestroyAlgorithmContext) API</a>.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>D-H public key</strong></dt>
|
||
|
|
|
||
|
|
<dd>INPUT; CHAR(*)
|
||
|
|
|
||
|
|
<p>The other party's D-H public key.<br>
|
||
|
|
This is the public key from the party with whom the secret key will be
|
||
|
|
shared</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Length of D-H public key</strong></dt>
|
||
|
|
|
||
|
|
<dd>INPUT; BINARY(4)
|
||
|
|
|
||
|
|
<p>The length of key specified in the D-H public key parameter.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>D-H secret key</strong></dt>
|
||
|
|
|
||
|
|
<dd>OUTPUT; CHAR(*)
|
||
|
|
|
||
|
|
<p>The area to store the D-H secret key.<br>
|
||
|
|
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.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Length of area provided for D-H secret key</strong></dt>
|
||
|
|
|
||
|
|
<dd>INPUT; BINARY(4)
|
||
|
|
|
||
|
|
<p>The length of the D-H secret key parameter in bytes.<br>
|
||
|
|
The size of the secret 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 and round up to obtain the length of area needed for the
|
||
|
|
D-H secret key.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Length of D-H secret key returned</strong></dt>
|
||
|
|
|
||
|
|
<dd>OUTPUT; BINARY(4)
|
||
|
|
|
||
|
|
<p>The length of the D-H secret key returned in the D-H secret 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 secret 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><a name="header_9">Error Messages</a></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">CPF3CF2 E</td>
|
||
|
|
<td valign="top">Error(s) occurred during running of &1 API.</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">CPF9DCA E</td>
|
||
|
|
<td valign="top">Length of D-H (Diffie-Hellman) public key 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">CPF9DF1 E</td>
|
||
|
|
<td valign="top">The algorithm context token does not reference a valid algorithm context.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top">CPF9DF2 E</td>
|
||
|
|
<td valign="top">The algorithm context is not found or was previously destroyed.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3><a name="header_10">Example of Three-Party Shared Secret Key
|
||
|
|
Exchange</a></h3>
|
||
|
|
|
||
|
|
<ol>
|
||
|
|
<li>Beth uses Generate Diffie-Hellman Parameters and sends the output to Kathy
|
||
|
|
and Terry.</li>
|
||
|
|
|
||
|
|
<li>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.</li>
|
||
|
|
|
||
|
|
<li>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.</li>
|
||
|
|
|
||
|
|
<li>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.</li>
|
||
|
|
|
||
|
|
<li>Beth specifies T1 on Calculate Diffie-Hellman Secret Key to create another
|
||
|
|
public value B2, which she sends to Kathy.</li>
|
||
|
|
|
||
|
|
<li>Kathy specifies B1 on Calculate Diffie-Hellman Secret Key to create another
|
||
|
|
public value K2, which she sends to Terry.</li>
|
||
|
|
|
||
|
|
<li>Terry specifies K1 on Calculate Diffie-Hellman Secret Key to create another
|
||
|
|
public value T2, which he sends to Beth.</li>
|
||
|
|
|
||
|
|
<li>Beth specifies T2 on Calculate Diffie-Hellman Secret Key to create the
|
||
|
|
shared secret key, S.</li>
|
||
|
|
|
||
|
|
<li>Kathy specifies B2 on Calculate Diffie-Hellman Secret Key to create the
|
||
|
|
shared secret key, S.</li>
|
||
|
|
|
||
|
|
<li>Terry specifies K2 on Calculate Diffie-Hellman Secret Key to create the
|
||
|
|
shared secret key, S.</li>
|
||
|
|
</ol>
|
||
|
|
|
||
|
|
<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>
|
||
|
|
|