ibm-information-center/dist/eclipse/plugins/i5OS.ic.apis_5.4.0.1/qc3calha.htm

680 lines
17 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/05/02 -->
<!-- Change history: -->
<!-- 030211 JETAYLOR html cleanup -->
<!-- 030826 BILLINGS updates -->
<!-- end header records -->
<title>Calculate Hash (QC3CALHA, Qc3CalculateHash)</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 Hash (QC3CALHA, Qc3CalculateHash)</h2>
<div class="box" style="width: 80%;">
<br>
&nbsp;&nbsp;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%">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%">7</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%">8</td>
<td align="left" valign="top" width="60%">Hash</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%">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>
&nbsp;&nbsp;Service Program Name: QC3HASH<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: Yes<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The Calculate Hash (OPM, QC3CALHA; ILE, Qc3CalculateHash)
API uses a one-way hash function to produce a fixed-length output
string from a variable-length input string. For all practical purposes, one-way
hashes are irreversible. This property makes them useful for authentication
purposes.</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 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>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 hash 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, SHA-256, SHA-384,
SHA-512).<br>
<br>
</dd>
</dl>
<p>See <a href="#algs">Algorithm 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 hash
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 hash 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 hash 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 hash 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>Hash</strong></dt>
<dd>OUTPUT; CHAR(*)
<p>The area to store the hash. The length of hash is defined by the hash
algorithm.</p>
<table width="95%">
<tr>
<td align="left" valign="top" width="15%"><strong>MD5</strong></td>
<td align="left" valign="top" width="85%">16 bytes</td>
</tr>
<tr>
<td align="left" valign="top" width="15%"><strong>SHA-1</strong></td>
<td align="left" valign="top" width="85%">20 bytes</td>
</tr>
<tr>
<td align="left" valign="top" width="15%"><strong>SHA-256</strong></td>
<td align="left" valign="top" width="85%">32 bytes</td>
</tr>
<tr>
<td align="left" valign="top" width="15%"><strong>SHA-384</strong></td>
<td align="left" valign="top" width="85%">48 bytes</td>
</tr>
<tr>
<td align="left" valign="top" width="15%"><strong>SHA-512</strong></td>
<td align="left" valign="top" width="85%">64 bytes</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>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 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>
</table>
</dd>
<dd><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 hash operation. The pointer to the
hash parameter may be set to NULL because the hash 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 hash 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.</td>
</tr>
</table>
</dd>
</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 &amp;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 &amp;1 in library &amp;2 ended. Reason code &amp;3.</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">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">CPF9DD5 E</td>
<td valign="top">Length of input data not valid.</td>
</tr>
<tr>
<td valign="top">CPF9DDA E</td>
<td valign="top">Unexpected return code &amp;1.</td>
</tr>
<tr>
<td valign="top">CPF9DE0 E</td>
<td valign="top">Hash algorithm 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">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>