1359 lines
35 KiB
HTML
1359 lines
35 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 -->
|
||
|
|
<!-- 030826 BILLINGS updated -->
|
||
|
|
<!-- 031015 BILLINGS changes to KEYD0200 format -->
|
||
|
|
<!-- 040706 BILLINGS V5R4 changes -->
|
||
|
|
<!-- 050315 BILLINGS message updates -->
|
||
|
|
<!-- end header records -->
|
||
|
|
<title>Calculate HMAC (QC3CALHM, Qc3CalculateHMAC)</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 HMAC (QC3CALHM, Qc3CalculateHMAC)</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%">Input data</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 input data</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%">Input data format name</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%">4</td>
|
||
|
|
<td align="left" valign="top" width="60%">Algorithm description</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%">5</td>
|
||
|
|
<td align="left" valign="top" width="60%">Algorithm description format
|
||
|
|
name</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%">6</td>
|
||
|
|
<td align="left" valign="top" width="60%">Key description</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%">7</td>
|
||
|
|
<td align="left" valign="top" width="60%">Key description format name</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%">8</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%">9</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%">10</td>
|
||
|
|
<td align="left" valign="top" width="60%">HMAC</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%">11</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: QC3HMAC<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
Default Public Authority: *USE<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
Threadsafe: Yes<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<p>The Calculate HMAC (OPM, QC3CALHM; ILE Qc3CalculateHMAC)
|
||
|
|
API uses a one-way hash function and a secret shared key to produce an
|
||
|
|
authentication value. The HMAC function is documented in RFC 2104.</p>
|
||
|
|
|
||
|
|
<p>Information on cryptographic standards can be found in the <a href=
|
||
|
|
"qc3crtax.htm">Create Algorithm Context (OPM, QC3CRTAX; ILE,
|
||
|
|
Qc3CreateAlgorithmContext) API</a> documentation.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Authorities and Locks</h3>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
|
||
|
|
<dt><strong>Required device description authority</strong></dt>
|
||
|
|
|
||
|
|
<dd>*USE<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><img src="delta.gif" alt="Start of change"></dt>
|
||
|
|
<dt><strong>Required file authority</strong></dt>
|
||
|
|
|
||
|
|
<dd>*OBJOPR, *READ<br>
|
||
|
|
</dd>
|
||
|
|
<dt><img src="deltaend.gif" alt="End of change"></dt>
|
||
|
|
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Required Parameter Group</h3>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><strong>Input data</strong></dt>
|
||
|
|
|
||
|
|
<dd>INPUT; CHAR(*)
|
||
|
|
|
||
|
|
<p>The data to hash.<br>
|
||
|
|
The format of the input data is specified in the input data format name
|
||
|
|
parameter</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Length of input data</strong></dt>
|
||
|
|
|
||
|
|
<dd>INPUT; BINARY(4)
|
||
|
|
|
||
|
|
<p>For input data format DATA0100, this is the length of the data to hash.<br>
|
||
|
|
For input data format DATA0200, this is the number of entries in the array.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Input data format name</strong></dt>
|
||
|
|
|
||
|
|
<dd>INPUT; CHAR(8)
|
||
|
|
|
||
|
|
<p>The format of the input data parameter.<br>
|
||
|
|
The possible format names follow.</p>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><strong>DATA0100</strong></dt>
|
||
|
|
|
||
|
|
<dd>The input data parameter contains the data to hash.<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong><a href="#data0200">DATA0200</a></strong></dt>
|
||
|
|
|
||
|
|
<dd>The input data parameter contains an array of pointers and lengths to the
|
||
|
|
data to hash.<br>
|
||
|
|
See <a href="#inputdata">Input Data Formats</a> for a description of this
|
||
|
|
format.</dd>
|
||
|
|
</dl>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Algorithm description</strong><br>
|
||
|
|
</dt>
|
||
|
|
|
||
|
|
<dd>INPUT; CHAR(*)
|
||
|
|
|
||
|
|
<p>The algorithm and associated parameters for hashing the data.<br>
|
||
|
|
The format of the algorithm description is specified in the algorithm
|
||
|
|
description format name parameter.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Algorithm description format name</strong></dt>
|
||
|
|
|
||
|
|
<dd>INPUT; CHAR(8)
|
||
|
|
|
||
|
|
<p>The format of the algorithm description.<br>
|
||
|
|
The possible format names follow.</p>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><strong><a href="#algd0100">ALGD0100</a></strong></dt>
|
||
|
|
|
||
|
|
<dd>The token for an algorithm context. This format must be used when
|
||
|
|
performing the HMAC operation over multiple calls. After the last call (when
|
||
|
|
the final operation flag is on), the context will reset to its initial state
|
||
|
|
and can be used in another API.<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong><a href="#algd0500">ALGD0500</a></strong></dt>
|
||
|
|
|
||
|
|
<dd>Parameters for a hash algorithm (MD5, SHA-1
|
||
|
|
<img src="delta.gif" alt="Start of change">
|
||
|
|
, SHA-256, SHA-384, or SHA512)
|
||
|
|
<img src="deltaend.gif" alt="End of change">
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<p>See <a href="#algs">Algorithm Description Formats</a> for a description of
|
||
|
|
these formats.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Key description</strong></dt>
|
||
|
|
|
||
|
|
<dd>INPUT; CHAR(*)
|
||
|
|
|
||
|
|
<p>The key and associated parameters for the HMAC operation.<br>
|
||
|
|
The format of the key description is specified in the key description format
|
||
|
|
name parameter.<br>
|
||
|
|
If the HMAC operation extends over multiple calls (see ALGD0100 description above), only the key description from the first call will be used. Therefore, on subsequent calls, you may set the pointer to this parameter to NULL.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Key description format name</strong></dt>
|
||
|
|
|
||
|
|
<dd>INPUT; CHAR(8)
|
||
|
|
|
||
|
|
<p>The format of the key description.<br>
|
||
|
|
If the pointer to the key description parameter is NULL, this parameter will be ignored.<br>
|
||
|
|
The possible format names follow.</p>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><strong><a href="#keyd0100">KEYD0100</a></strong></dt>
|
||
|
|
|
||
|
|
<dd>The token for a key context. This format identifies a key context. A key
|
||
|
|
context is used to store a key value so it need not be recreated or retrieved
|
||
|
|
every time it is used. To create a key context, use the
|
||
|
|
<a href="qc3crtkx.htm">Create Key Context (OPM, QC3CRTKX;
|
||
|
|
ILE, Qc3CreateKeyContext)</a> API.<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong><a href="#keyd0200">KEYD0200</a></strong></dt>
|
||
|
|
|
||
|
|
<dd>Key parameters.<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><img src="delta.gif" alt="Start of change"></dt>
|
||
|
|
|
||
|
|
<dt><strong><a href="#keyd0400">KEYD0400</a></strong></dt>
|
||
|
|
<dd>Key store label. This format identifies a key from key store.
|
||
|
|
For more information on cryptographic services key store, refer to the
|
||
|
|
<a href="qc3KeyStore.htm">Cryptographic Services Key Store</a> article.<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong><a href="#keyd0500">KEYD0500</a></strong></dt>
|
||
|
|
<dd>PKCS5 passphrase. This format derives a key using RSA Data Security,
|
||
|
|
Inc. Public-Key Cryptography Standard (PKCS) #5.<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><img src="deltaend.gif" alt="End of change"></dt>
|
||
|
|
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<p>See <a href="#keys">Key Description Formats</a> for a description of these
|
||
|
|
formats.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Cryptographic service provider</strong></dt>
|
||
|
|
|
||
|
|
<dd>INPUT; CHAR(1)
|
||
|
|
|
||
|
|
<p>The cryptographic service provider (CSP) that will perform the decryption
|
||
|
|
operation.</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 HMAC operation.</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 HMAC operation 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 HMAC operation 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>
|
||
|
|
<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>HMAC</strong></dt>
|
||
|
|
|
||
|
|
<dd>OUTPUT; CHAR(*)
|
||
|
|
|
||
|
|
<p>The area to store the HMAC. The length of HMAC is defined by the hash
|
||
|
|
algorithm.</p>
|
||
|
|
|
||
|
|
<table width="95%">
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top" width="10%"><strong>MD5</strong></td>
|
||
|
|
<td align="left" valign="top" width="90%">16 bytes</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top" width="10%"><strong>SHA-1</strong></td>
|
||
|
|
<td align="left" valign="top" width="90%">20 bytes</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr><td><img src="delta.gif" alt="Start of change"></td></tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top" width="10%"><strong>SHA-256</strong></td>
|
||
|
|
<td align="left" valign="top" width="90%">32 bytes</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top" width="10%"><strong>SHA-384</strong></td>
|
||
|
|
<td align="left" valign="top" width="90%">48 bytes</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top" width="10%"><strong>SHA-512</strong></td>
|
||
|
|
<td align="left" valign="top" width="90%">64 bytes</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr><td><img src="deltaend.gif" alt="End of change"></td></tr>
|
||
|
|
|
||
|
|
</table>
|
||
|
|
<br>
|
||
|
|
</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="inputdata">Input Data Formats</a></h3>
|
||
|
|
|
||
|
|
For detailed descriptions of the table fields, see <a href="#inputfield">Input
|
||
|
|
Data Formats Field Descriptions</a>.
|
||
|
|
|
||
|
|
<h4><a name="data0200">DATA0200 format</a></h4>
|
||
|
|
|
||
|
|
<table border width="70%">
|
||
|
|
<!-- cols="10 10 20 60" -->
|
||
|
|
<tr>
|
||
|
|
<th align="center" valign="bottom" colspan="2">Offset</th>
|
||
|
|
<th align="left" valign="bottom" rowspan="2">Type</th>
|
||
|
|
<th align="left" valign="bottom" rowspan="2">Field</th>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<th align="center" valign="bottom">Dec</th>
|
||
|
|
<th align="center" valign="bottom">Hex</th>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top" rowspan="3" colspan="2" width="20%">These fields repeat.</td>
|
||
|
|
<td align="left" valign="top" width="20%">PTR(SPP)</td>
|
||
|
|
<td align="left" valign="top" width="60%">Input data pointer</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">BINARY(4)</td>
|
||
|
|
<td align="left" valign="top">Input data length</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CHAR(12)</td>
|
||
|
|
<td align="left" valign="top">Reserved</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<h4><a name="inputfield"><strong>Input Data Formats Field
|
||
|
|
Descriptions</strong></a></h4>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><strong>Input data length</strong></dt>
|
||
|
|
|
||
|
|
<dd>The length of data to hash.</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><strong>Input data pointer</strong></dt>
|
||
|
|
|
||
|
|
<dd>A space pointer to the data to hash.</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><strong>Reserved</strong></dt>
|
||
|
|
|
||
|
|
<dd>Must be null (binary 0s).</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3><a name="algs">Algorithm Description Formats</a></h3>
|
||
|
|
|
||
|
|
For detailed descriptions of the table fields, see <a href="#algfield">
|
||
|
|
Algorithm Description Formats Field Descriptions</a>.
|
||
|
|
|
||
|
|
<h4><a name="algd0100">ALGD0100 format</a></h4>
|
||
|
|
|
||
|
|
<table border width="70%">
|
||
|
|
<tr>
|
||
|
|
<th align="center" valign="bottom" colspan="2">Offset</th>
|
||
|
|
<th align="left" valign="bottom" rowspan="2">Type</th>
|
||
|
|
<th align="left" valign="bottom" rowspan="2">Field</th>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<th align="center" valign="bottom">Dec</th>
|
||
|
|
<th align="center" valign="bottom">Hex</th>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top" width="10%">0</td>
|
||
|
|
<td align="center" valign="top" width="10%">0</td>
|
||
|
|
<td align="left" valign="top" width="20%">CHAR(8)</td>
|
||
|
|
<td align="left" valign="top" width="60%">Algorithm context token</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">8</td>
|
||
|
|
<td align="center" valign="top">8</td>
|
||
|
|
<td align="left" valign="top">CHAR(1)</td>
|
||
|
|
<td align="left" valign="top">Final operation flag</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<h4><a name="algd0500">ALGD0500 format</a></h4>
|
||
|
|
|
||
|
|
<table border width="70%">
|
||
|
|
<tr>
|
||
|
|
<th align="center" valign="bottom" colspan="2">Offset</th>
|
||
|
|
<th align="left" valign="bottom" rowspan="2">Type</th>
|
||
|
|
<th align="left" valign="bottom" rowspan="2">Field</th>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<th align="center" valign="bottom">Dec</th>
|
||
|
|
<th align="center" valign="bottom">Hex</th>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top" width="10%">0</td>
|
||
|
|
<td align="center" valign="top" width="10%">0</td>
|
||
|
|
<td align="left" valign="top" width="20%">BINARY(4)</td>
|
||
|
|
<td align="left" valign="top" width="60%">Hash algorithm</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<h4><a name="algfield"><strong>Algorithm Description Formats Field
|
||
|
|
Descriptions</strong></a></h4>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><strong>Algorithm context token</strong></dt>
|
||
|
|
|
||
|
|
<dd>A token for an algorithm context. The algorithm context is created using
|
||
|
|
the <a href="qc3crtax.htm">Create Algorithm Context (OPM, QC3CRTAX; ILE,
|
||
|
|
Qc3CreateAlgorithmContext) API</a>.
|
||
|
|
<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Final operation flag</strong></dt>
|
||
|
|
|
||
|
|
<dd>The final processing indicator.<br>
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<table width="95%">
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top" width="5%"><strong>0</strong></td>
|
||
|
|
<td align="left" valign="top" width="95%">Continue.<br>
|
||
|
|
The system will not perform final processing and the algorithm context will
|
||
|
|
maintain the state of the operation. The algorithm context can be used on
|
||
|
|
future calls to this API to continue the HMAC operation. The pointer to the
|
||
|
|
HMAC parameter may be set to NULL because the HMAC value will
|
||
|
|
not be returned until the final operation flag is set on.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><strong>1</strong></td>
|
||
|
|
<td align="left" valign="top">Final.<br>
|
||
|
|
The system will perform final processing. The HMAC value will be returned and
|
||
|
|
the algorithm context will reset to its initial state. The algorithm context
|
||
|
|
can then be used to begin a new cryptographic operation (hash, HMAC etc.).
|
||
|
|
When performing a final operation, the pointer to the input data parameter
|
||
|
|
may be set to NULL and the length of input data parameter set to 0.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Hash algorithm</strong></dt>
|
||
|
|
|
||
|
|
<dd>The hash algorithm. Following are the valid hash algorithms.
|
||
|
|
|
||
|
|
<table width="95%">
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top" width="5%"><strong>1</strong></td>
|
||
|
|
<td align="left" valign="top" width="95%">MD5<br>
|
||
|
|
Documented in RFC 1321.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top" width="5%"><strong>2</strong></td>
|
||
|
|
<td align="left" valign="top" width="95%">SHA-1<br>
|
||
|
|
Documented in FIPS 180-2.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr><td><img src="delta.gif" alt="Start of change"></td></tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top" width="5%"><strong>3</strong></td>
|
||
|
|
<td align="left" valign="top" width="95%">SHA-256<br>
|
||
|
|
Documented in FIPS 180-2.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top" width="5%"><strong>4</strong></td>
|
||
|
|
<td align="left" valign="top" width="95%">SHA-384<br>
|
||
|
|
Documented in FIPS 180-2.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top" width="5%"><strong>5</strong></td>
|
||
|
|
<td align="left" valign="top" width="95%">SHA-512<br>
|
||
|
|
Documented in FIPS 180-2.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr><td><img src="deltaend.gif" alt="End of change"></td></tr>
|
||
|
|
|
||
|
|
</table>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dd><br>
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3><a name="keys">Key Description Formats</a></h3>
|
||
|
|
|
||
|
|
For detailed descriptions of the table fields, see <a href="#keyfield">Key
|
||
|
|
Description Formats Field Descriptions</a>.
|
||
|
|
|
||
|
|
<h4><a name="keyd0100">KEYD0100 format</a></h4>
|
||
|
|
|
||
|
|
<table border width="70%">
|
||
|
|
<tr>
|
||
|
|
<th align="center" valign="bottom" colspan="2">Offset</th>
|
||
|
|
<th align="left" valign="bottom" rowspan="2">Type</th>
|
||
|
|
<th align="left" valign="bottom" rowspan="2">Field</th>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<th align="center" valign="bottom">Dec</th>
|
||
|
|
<th align="center" valign="bottom">Hex</th>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top" width="10%">0</td>
|
||
|
|
<td align="center" valign="top" width="10%">0</td>
|
||
|
|
<td align="left" valign="top" width="20%">CHAR(8)</td>
|
||
|
|
<td align="left" valign="top" width="60%">Key context token</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<h4><a name="keyd0200">KEYD0200 format</a></h4>
|
||
|
|
|
||
|
|
<table border width="70%">
|
||
|
|
<tr>
|
||
|
|
<th align="center" valign="bottom" colspan="2">Offset</th>
|
||
|
|
<th align="left" valign="bottom" rowspan="2">Type</th>
|
||
|
|
<th align="left" valign="bottom" rowspan="2">Field</th>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<th align="center" valign="bottom">Dec</th>
|
||
|
|
<th align="center" valign="bottom">Hex</th>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top" width="10%">0</td>
|
||
|
|
<td align="center" valign="top" width="10%">0</td>
|
||
|
|
<td align="left" valign="top" width="20%">BINARY(4)</td>
|
||
|
|
<td align="left" valign="top" width="60%">Key type</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">4</td>
|
||
|
|
<td align="center" valign="top">4</td>
|
||
|
|
<td align="left" valign="top">BINARY(4)</td>
|
||
|
|
<td align="left" valign="top">Key string length</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">8</td>
|
||
|
|
<td align="center" valign="top">8</td>
|
||
|
|
<td align="left" valign="top">CHAR(1)</td>
|
||
|
|
<td align="left" valign="top">Key format</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">9</td>
|
||
|
|
<td align="center" valign="top">9</td>
|
||
|
|
<td align="left" valign="top">CHAR(3)</td>
|
||
|
|
<td align="left" valign="top">Reserved</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">12</td>
|
||
|
|
<td align="center" valign="top">C</td>
|
||
|
|
<td align="left" valign="top">CHAR(*)</td>
|
||
|
|
<td align="left" valign="top">Key string</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
<br>
|
||
|
|
|
||
|
|
<img src="delta.gif" alt="Start of change">
|
||
|
|
|
||
|
|
<h4><a name="keyd0400">KEYD0400 format</a></h4>
|
||
|
|
|
||
|
|
<table border width="70%">
|
||
|
|
<tr>
|
||
|
|
<th align="center" valign="bottom" colspan="2">Offset</th>
|
||
|
|
<th align="left" valign="bottom" rowspan="2">Type</th>
|
||
|
|
<th align="left" valign="bottom" rowspan="2">Field</th>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<th align="left" valign="bottom">Dec</th>
|
||
|
|
<th align="left" valign="bottom">Hex</th>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top" width="9%">0</td>
|
||
|
|
<td align="center" valign="top" width="9%">0</td>
|
||
|
|
<td align="left" valign="top" width="19%">CHAR(20)</td>
|
||
|
|
<td align="left" valign="top" width="66%">Qualified key store file name</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top" width="9%">20</td>
|
||
|
|
<td align="center" valign="top" width="9%">14</td>
|
||
|
|
<td align="left" valign="top" width="19%">CHAR(32)</td>
|
||
|
|
<td align="left" valign="top" width="66%">Record label</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top" width="9%">52</td>
|
||
|
|
<td align="center" valign="top" width="9%">34</td>
|
||
|
|
<td align="left" valign="top" width="19%">CHAR(4)</td>
|
||
|
|
<td align="left" valign="top" width="66%">Reserved</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
</table>
|
||
|
|
<br>
|
||
|
|
|
||
|
|
<h4><a name="keyd0500">KEYD0500 format</a></h4>
|
||
|
|
|
||
|
|
<table border width="70%">
|
||
|
|
<tr>
|
||
|
|
<th align="center" valign="bottom" colspan="2">Offset</th>
|
||
|
|
<th align="left" valign="bottom" rowspan="2">Type</th>
|
||
|
|
<th align="left" valign="bottom" rowspan="2">Field</th>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<th align="left" valign="bottom">Dec</th>
|
||
|
|
<th align="left" valign="bottom">Hex</th>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top" width="9%">0</td>
|
||
|
|
<td align="center" valign="top" width="9%">0</td>
|
||
|
|
<td align="left" valign="top" width="19%">BINARY(4)</td>
|
||
|
|
<td align="left" valign="top" width="63%">Key type</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top" width="9%">4</td>
|
||
|
|
<td align="center" valign="top" width="9%">4</td>
|
||
|
|
<td align="left" valign="top" width="19%">BINARY(4)</td>
|
||
|
|
<td align="left" valign="top" width="66%">Derived key length</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top" width="9%">8</td>
|
||
|
|
<td align="center" valign="top" width="9%">8</td>
|
||
|
|
<td align="left" valign="top" width="19%">BINARY(4)</td>
|
||
|
|
<td align="left" valign="top" width="66%">Iteration count</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top" width="9%">12</td>
|
||
|
|
<td align="center" valign="top" width="9%">C</td>
|
||
|
|
<td align="left" valign="top" width="19%">BINARY(4)</td>
|
||
|
|
<td align="left" valign="top" width="66%">Salt length</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top" width="9%">16</td>
|
||
|
|
<td align="center" valign="top" width="9%">10</td>
|
||
|
|
<td align="left" valign="top" width="19%">CHAR(16)</td>
|
||
|
|
<td align="left" valign="top" width="66%">Salt</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top" width="9%">32</td>
|
||
|
|
<td align="center" valign="top" width="9%">20</td>
|
||
|
|
<td align="left" valign="top" width="19%">BINARY(4)</td>
|
||
|
|
<td align="left" valign="top" width="66%">Passphrase CCSID</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top" width="9%">36</td>
|
||
|
|
<td align="center" valign="top" width="9%">24</td>
|
||
|
|
<td align="left" valign="top" width="19%">BINARY(4)</td>
|
||
|
|
<td align="left" valign="top" width="66%">Passphrase length</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top" width="9%">40</td>
|
||
|
|
<td align="center" valign="top" width="9%">28</td>
|
||
|
|
<td align="left" valign="top" width="19%">CHAR(*)</td>
|
||
|
|
<td align="left" valign="top" width="66%">Passphrase</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<img src="deltaend.gif" alt="End of change">
|
||
|
|
<br>
|
||
|
|
|
||
|
|
<h4><a name="keyfield"><strong>Key Description Formats Field
|
||
|
|
Descriptions</strong></a></h4>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
|
||
|
|
<dt><img src="delta.gif" alt="Start of change">
|
||
|
|
</dt>
|
||
|
|
|
||
|
|
<dt><strong>Derived key length</strong></dt>
|
||
|
|
|
||
|
|
<dd>The length of key requested. The minimum allowed length is 1.
|
||
|
|
<br><br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Iteration count</strong></dt>
|
||
|
|
|
||
|
|
<dd>Used to greatly increase the cost of an exhaustive search while modestly
|
||
|
|
increasing the cost of key derivation. The minimum allowed value is 1.
|
||
|
|
The standard recommends a minimum of 1000.
|
||
|
|
The maximum allowed length is 100,000.
|
||
|
|
<br><br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><img src="deltaend.gif" alt="End of change">
|
||
|
|
</dt>
|
||
|
|
|
||
|
|
<dt><strong>Key context token</strong></dt>
|
||
|
|
|
||
|
|
<dd>A token for a key context. The key context is created using the <a href=
|
||
|
|
"qc3crtkx.htm">Create Key Context (OPM, QC3CRTKX; ILE, Qc3CreateKeyContext)
|
||
|
|
API</a>.
|
||
|
|
<br><br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Key format</strong></dt>
|
||
|
|
|
||
|
|
<dd>The format of the key string field. Following are the valid values.
|
||
|
|
|
||
|
|
<table width="95%">
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top" width="5%"><strong>0</strong></td>
|
||
|
|
<td align="left" valign="top" width="95%">Binary string.<br>
|
||
|
|
The key is specified as a binary value. To obtain a good random key value, use
|
||
|
|
the <a href="qc3genprns.htm">Generate Pseudorandom Numbers (OPM, QC3GENPRN;
|
||
|
|
ILE, Qc3GenPRNs) API</a>.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Key string</strong></dt>
|
||
|
|
|
||
|
|
<dd>The key to use in the HMAC operation.
|
||
|
|
<br><br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Key string length</strong></dt>
|
||
|
|
|
||
|
|
<dd>Length of the key string specified in the key string field. Refer to the
|
||
|
|
key type field for more information.
|
||
|
|
<br><br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Key type</strong></dt>
|
||
|
|
|
||
|
|
<dd>The type of key. Following are the valid values.
|
||
|
|
|
||
|
|
<table width="95%">
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top" width="5%"><strong>1</strong></td>
|
||
|
|
<td align="left" valign="top" width="95%">MD5<br>
|
||
|
|
The minimum length for an MD5 HMAC key is 16 bytes.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top" width="5%"><strong>2</strong></td>
|
||
|
|
<td align="left" valign="top" width="95%">SHA-1<br>
|
||
|
|
The minimum length for an SHA-1 HMAC key is 20 bytes.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td>
|
||
|
|
<img src="delta.gif" alt="Start of change">
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top" width="5%"><strong>3</strong></td>
|
||
|
|
<td align="left" valign="top" width="95%">SHA-256<br>
|
||
|
|
The minimum length for an SHA-256 HMAC key is 32 bytes.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top" width="5%"><strong>4</strong></td>
|
||
|
|
<td align="left" valign="top" width="95%">SHA-384<br>
|
||
|
|
The minimum length for an SHA-384 HMAC key is 48 bytes.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top" width="5%"><strong>3</strong></td>
|
||
|
|
<td align="left" valign="top" width="95%">SHA-512<br>
|
||
|
|
The minimum length for an SHA-512 HMAC key is 64 bytes.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td>
|
||
|
|
<img src="deltaend.gif" alt="End of change">
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
</table>
|
||
|
|
<p>A key longer than the minimum length does not significantly increase the
|
||
|
|
function strength unless the randomness of the key is considered weak.
|
||
|
|
A key longer than 64 bytes
|
||
|
|
<img src="delta.gif" alt="Start of change">
|
||
|
|
for MD5, SHA-1, and SHA-256, or longer the 128 bytes for SHA-384 and SHA-512,
|
||
|
|
<img src="deltaend.gif" alt="End of change">
|
||
|
|
will be hashed before it is used.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><img src="delta.gif" alt="Start of change">
|
||
|
|
</dt>
|
||
|
|
|
||
|
|
<dt><strong>Passphrase</strong></dt>
|
||
|
|
|
||
|
|
<dd>A text string.
|
||
|
|
<br><br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Passphrase CCSID</strong></dt>
|
||
|
|
|
||
|
|
<dd>INPUT; BINARY(4)
|
||
|
|
|
||
|
|
<p>The CCSID of the passphrase. The passphrase will be converted from the
|
||
|
|
specified CCSID to Unicode before calling the PKCS5 algorithm.</p>
|
||
|
|
|
||
|
|
<table width="95%">
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top" width="15%"><strong>0</strong></td>
|
||
|
|
<td align="left" valign="top">The CCSID of the job is used to determine the
|
||
|
|
CCSID of the data to be converted. If the job CCSID is 65535, the CCSID from
|
||
|
|
the default CCSID (DFTCCSID) job attribute is used.</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top" width="15%"><strong>1-65533</strong></td>
|
||
|
|
<td align="left" valign="top">A valid CCSID in this range is used. For a list of valid CCSIDs,
|
||
|
|
see the <a href="../nls/rbagsglobalmain.htm">Globalization</a> topic in the
|
||
|
|
iSeries Information Center.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Passphrase length</strong></dt>
|
||
|
|
|
||
|
|
<dd>The length of passphrase. The length must be in the range of 1 to 256.
|
||
|
|
<br><br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Qualified key store file name</strong></dt>
|
||
|
|
|
||
|
|
<dd>The key store file where the key is stored. Key store files are created
|
||
|
|
using the <a href="qc3crtks.htm">Create Key Store (OPM, QC3CRTKS;
|
||
|
|
ILE, Qc3CreateKeyStore)</a> API. The first 10 characters contain the file name.
|
||
|
|
The second 10 characters contain the name of the library
|
||
|
|
where the key store file is located. You can use the following special values
|
||
|
|
for the library name.
|
||
|
|
|
||
|
|
<table>
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><strong>*CURLIB</strong></td>
|
||
|
|
<td valign="top">The job's current library is used to locate the
|
||
|
|
key store file. If no library is specified as the current library for the
|
||
|
|
job, the QGPL library is used.</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><strong>*LIBL</strong></td>
|
||
|
|
<td align="left" valign="top">The job's library list is searched for the first
|
||
|
|
occurence of the specified file name.
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong> Record label</strong></dt>
|
||
|
|
<dd>The label of a key record in a key store file.
|
||
|
|
The label will be converted from the job CCSID, or if 65535, the job default
|
||
|
|
CCSID (DFTCCSID) job attribute to CCSID 1200 (Unicode UTF-16).
|
||
|
|
Key records are created
|
||
|
|
using the <a href="qc3wrtkr.htm">Write Key Record (OPM, QC3WRTKR;
|
||
|
|
ILE, Qc3WriteKeyRecord)</a> or <a href="qc3genkr.htm">Generate Key
|
||
|
|
Record (OPM, QC3GENKR; ILE, Qc3GenKeyRecord)</a> API.
|
||
|
|
<br><br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><img src="deltaend.gif" alt="End of change">
|
||
|
|
</dt>
|
||
|
|
|
||
|
|
<dt><strong>Reserved</strong></dt>
|
||
|
|
|
||
|
|
<dd>Must be null (binary 0s).<br><br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><img src="delta.gif" alt="Start of change"></dt>
|
||
|
|
|
||
|
|
<dt><strong>Salt</strong></dt>
|
||
|
|
|
||
|
|
<dd>Used to help thwart attacks by producing a large set
|
||
|
|
of keys for each passphrase. The standard recommends the salt be
|
||
|
|
generated at random and be at least 8 bytes long. You may use the
|
||
|
|
<a href="qc3genprns.htm">Generate Pseudorandom Numbers (OPM, QC3GENPRN;
|
||
|
|
ILE, Qc3GenPRNs)</a> API to obtain a random value. Additionally,
|
||
|
|
data that distinguishes between various operations can be added to the salt
|
||
|
|
for additional security. Refer to the standard for more information.
|
||
|
|
<br><br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Salt length</strong></dt>
|
||
|
|
|
||
|
|
<dd>The length of salt. The length must be in the range of 1 to 16.
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><img src="deltaend.gif" alt="End of change"></dt>
|
||
|
|
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3><a name="header_9">Error Messages</a></h3>
|
||
|
|
|
||
|
|
|
||
|
|
<table width="100%">
|
||
|
|
<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 align="left" valign="top">CPF3CF2 E</td>
|
||
|
|
<td align="left" 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"><img src="delta.gif" alt="Start of change"></td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top">CPF9D9C E</td>
|
||
|
|
<td valign="top">Function is disallowed with specified key context.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top">CPF9D9F E</td>
|
||
|
|
<td valign="top">Not authorized to key store file.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top">CPF9DA0 E</td>
|
||
|
|
<td valign="top">Error occured opening key store file.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top">CPF9DA1 E</td>
|
||
|
|
<td valign="top">Key record not found.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top">CPF9DA5 E</td>
|
||
|
|
<td valign="top">Key store file not found.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top">CPF9DA6 E</td>
|
||
|
|
<td valign="top">The key store file is not available.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top">CPF9DA7 E</td>
|
||
|
|
<td valign="top">File is corrupt or not a valid key store file.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top">CPF9DAA D</td>
|
||
|
|
<td valign="top">A key requires translation.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top">CPF9DAB E</td>
|
||
|
|
<td valign="top">A key can not be decrypted.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top">CPF9DB1 E</td>
|
||
|
|
<td valign="top">The CCSID is not valid.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top">CPF9DB3 E</td>
|
||
|
|
<td valign="top">Qualified key store file name not valid.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top">CPF9DB6 E</td>
|
||
|
|
<td valign="top">Record label not valid.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top">CPF9DB8 E</td>
|
||
|
|
<td valign="top">Error occured retrieving key record from key store.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top">CPF9DBA E</td>
|
||
|
|
<td valign="top">Derived key length not valid.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top">CPF9DBB E</td>
|
||
|
|
<td valign="top">Iteration count not valid.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top">CPF9DBC E</td>
|
||
|
|
<td valign="top">Salt length not valid.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top">CPF9DBD E</td>
|
||
|
|
<td valign="top">Passphrase length not valid.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top">CPF9DC2 E</td>
|
||
|
|
<td valign="top">Key-encrypting algorithm context not compatible with key-encrypting key context.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top">CPF9DC3 E</td>
|
||
|
|
<td valign="top">Unable to decrypt data or key.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top">CPF9DC6 E</td>
|
||
|
|
<td valign="top">Algorithm not valid for encrypting or decrypting a key.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top">CPF9DC7 E</td>
|
||
|
|
<td valign="top">The output data parameter specifies a NULL pointer.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top">CPF9DC8 E</td>
|
||
|
|
<td valign="top">The input data parameter specifies a NULL pointer.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><img src="deltaend.gif" alt="End of change"></td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top">CPF9DC9 E</td>
|
||
|
|
<td valign="top">The total length of data in the input data array is not valid.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top">CPF9DCE E</td>
|
||
|
|
<td valign="top">A data length is not valid.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top">CPF9DCF E</td>
|
||
|
|
<td valign="top">A data pointer is not valid.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top">CPF9DD1 E</td>
|
||
|
|
<td valign="top">Input data format name not valid.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top">CPF9DD2 E</td>
|
||
|
|
<td valign="top">Algorithm description format name not valid.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top">CPF9DD3 E</td>
|
||
|
|
<td valign="top">Key description format name not valid.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top">CPF9DD5 E</td>
|
||
|
|
<td valign="top">Length of input data not valid.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top">CPF9DD7 E</td>
|
||
|
|
<td valign="top">The key-encrypting key context for the specified key is not valid or was previously destroyed.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top">CPF9DD8 E</td>
|
||
|
|
<td valign="top">The key-encrypting algorithm context for the specified key is not valid or was previously destroyed.</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">CPF9DDD E</td>
|
||
|
|
<td valign="top">The key string length is not valid.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top">CPF9DE0 E</td>
|
||
|
|
<td valign="top">Hash algorithm not valid.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top">CPF9DE7 E</td>
|
||
|
|
<td valign="top">Key type not valid.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top">CPF9DE9 E</td>
|
||
|
|
<td valign="top">Key format 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">CPF9DED E</td>
|
||
|
|
<td valign="top">Final operation flag not valid.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top">CPF9DEE E</td>
|
||
|
|
<td valign="top">Reserved field not null.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top">CPF9DF0 E</td>
|
||
|
|
<td valign="top">Operation, algorithm, or mode not available on the requested CSP (cryptographic service provider).</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>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top">CPF9DF3 E</td>
|
||
|
|
<td valign="top">Algorithm in algorithm context not valid for requested operation.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top">CPF9DF4 E</td>
|
||
|
|
<td valign="top">The key context token does not reference a valid key context.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top">CPF9DF5 E</td>
|
||
|
|
<td valign="top">The key context is not found or was previously destroyed.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top">CPF9DF7 E</td>
|
||
|
|
<td valign="top">Algorithm context not compatible with key context.</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">CPF9DFB E</td>
|
||
|
|
<td valign="top">Cryptographic service provider (CSP) conflicts with the key context CSP.</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>
|
||
|
|
|