friedkiwi/ibm-information-center
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
master
ibm-information-center/dist/eclipse/plugins/i5OS.ic.apis_5.4.0.1/qc3crtax.htm

781 lines
22 KiB
HTML
Raw Permalink Blame History

<!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 5/29/02 -->
<!-- Change history: -->
<!-- 030211 JETAYLOR html cleanup -->
<!-- 031020 BILLINGS Review 3 updates -->
<!-- 040809 BILLINGS V5R4 changes -->
<!-- end header records -->
<title>Create Algorithm Context (QC3CRTAX, Qc3CreateAlgorithmContext)</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>Create Algorithm Context (QC3CRTAX, Qc3CreateAlgorithmContext)</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%">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%">2</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%">3</td>
<td align="left" valign="top" width="60%">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%">4</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: QC3CTX<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 Create Algorithm Context (OPM, QC3CRTAX; ILE,
Qc3CreateAlgorithmContext) API creates a temporary area for holding
the algorithm parameters and the state of the cryptographic operation. The API
returns a token which can be used on subsequent cryptographic APIs. The
algorithm context token can be used to extend a cryptographic operation over
multiple calls. The algorithm context can not be shared between jobs. It should
be destroyed using the <a href="qc3desax.htm">Destroy Algorithm Context (OPM,
QC3DESAX; ILE, Qc3DestroyAlgorithmContext) API</a>. If not explicitly
destroyed, the algorithm context will be destroyed at job end.</p>
<br>
<h3>Authorities and Locks</h3>
<dl>
<dt><strong>None</strong></dt>
</dl>
<br>
<h3>Required Parameter Group</h3>
<dl>
<dt><strong>Algorithm description</strong></dt>
<dd>INPUT; CHAR(*)
<p>The algorithm and associated parameters.<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="#algd0200">ALGD0200</a></strong></dt>
<dd>Block cipher algorithm (DES, Triple DES, AES, and
RC2).<br>
<br>
</dd>
<dt><strong><a href="#algd0300">ALGD0300</a></strong></dt>
<dd>Stream cipher algorithm (RC4-compatible).<br>
<br>
</dd>
<dt><strong><a href="#algd0400">ALGD0400</a></strong></dt>
<dd>Public key algorithm (RSA).<br>
<br>
</dd>
<dt><strong><a href="#algd0500">ALGD0500</a></strong></dt>
<dd>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>Algorithm context token</strong></dt>
<dd>OUTPUT; CHAR(8)
<p>The area to store the token for the created algorithm context.<br>
Each token will contain an authentication value. If the token is used
on a subsequent API but with an incorrect authentication value, the user
will be subjected to a 10 second penalty wait. For each authentication error
in that job, the penalty wait will increase 10 seconds up to a maximum of 10 minutes.</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>
<h3><a name="algs">Algorithm Description Formats</a></h3>
For detailed descriptions of the fields in the tables, see <a href="#algfield">
Algorithm Description Formats Field Descriptions</a>.
<h4><a name="algd0200">ALGD0200 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%">Block cipher algorithm</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">Block 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">Mode</td>
</tr>
<tr>
<td align="center" valign="top">9</td>
<td align="center" valign="top">9</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Pad option</td>
</tr>
<tr>
<td align="center" valign="top">10</td>
<td align="center" valign="top">A</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Pad character</td>
</tr>
<tr>
<td align="center" valign="top">11</td>
<td align="center" valign="top">B</td>
<td align="left" valign="top">CHAR(1)</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">BINARY(4)</td>
<td align="left" valign="top">MAC length</td>
</tr>
<tr>
<td align="center" valign="top">16</td>
<td align="center" valign="top">10</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Effective key size</td>
</tr>
<tr>
<td align="center" valign="top">20</td>
<td align="center" valign="top">14</td>
<td align="left" valign="top">CHAR(32)</td>
<td align="left" valign="top">Initialization vector</td>
</tr>
</table>
<h4><a name="algd0300">ALGD0300 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%">Stream cipher algorithm</td>
</tr>
</table>
<h4><a name="algd0400">ALGD0400 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%">Public key algorithm</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="center" valign="top">4</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">PKA block format</td>
</tr>
<tr>
<td align="center" valign="top">5</td>
<td align="center" valign="top">5</td>
<td align="left" valign="top">CHAR(3)</td>
<td align="left" valign="top">Reserved</td>
</tr>
<tr>
<td align="center" valign="top">8</td>
<td align="center" valign="top">8</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Signing hash algorithm</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>Block cipher algorithm</strong></dt>
<dd>Following are the valid block cipher algorithms:
<table width="95%">
<tr>
<td align="left" valign="top" width="5%"><strong>20</strong></td>
<td align="left" valign="top" width="95%">DES<br>
Documented in FIPS 46-3. DES is no longer considered secure enough for today's fast computers. It should be used for compatibility purposes only.</td>
</tr>
<tr>
<td align="left" valign="top" width="5%"><strong>21</strong></td>
<td align="left" valign="top" width="95%">Triple DES<br>
Documented in FIPS 46-3.</td>
</tr>
<tr>
<td align="left" valign="top" width="5%"><strong>22</strong></td>
<td align="left" valign="top" width="95%">AES<br>
Documented in FIPS 197.</td>
</tr>
<tr>
<td align="left" valign="top" width="5%"><strong>23</strong></td>
<td align="left" valign="top" width="95%">RC2<br>
Documented in RFC 2268.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Block length</strong></dt>
<dd>The algorithm block length. For DES, Triple DES, and RC2, this field must
specify 8. The valid block length values for AES are 16, 24, and 32.
<br><br>
</dd>
<dt><strong>Effective key size</strong></dt>
<dd>For RC2, the number of key bits to use in the cipher operation. Valid
values are from 1 to 1024. If RC2 is not specifed for the block cipher
algorithm, this field must be set to 0.
<br><br>
</dd>
<dt><strong>Hash algorithm</strong></dt>
<dd>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>
<br>
</dd>
<dt><strong>Initialization vector</strong></dt>
<dd>The initialization vector (IV). Refer to the mode standards for an explanation of its
use. For DES, Triple DES, and RC2, the first 8 bytes are used as the IV. For
AES, the length of IV used is that specified by block length. The IV need not
be secret, but it should be unique for each message. If not unique, it may
compromise security. The IV can be any value. To obtain a good random IV value,
use the <a href="qc3genprns.htm">Generate Pseudorandom Numbers (OPM, QC3GENPRN;
ILE, Qc3GenPRNs) API</a>. An IV is not used for mode ECB, and must be
set to NULL (hex 0's).
<br><br>
</dd>
<dt><strong>MAC length</strong></dt>
<dd>The message authentication code length. This field is used only by the <a
href="qc3calma.htm">Calculate MAC (OPM, QC3CALMA; ILE, Qc3CalMAC) API</a>. MAC
length can not exceed the block length value. When calculating a MAC, the
leftmost MAC length bytes from the last block of encrypted data are returned as
the MAC.
<br><br>
</dd>
<dt><strong>Mode</strong></dt>
<dd>The mode of operation. Information on modes can be found in FIPS PUB 81 and
ANSI X9.52. Following are the valid modes:
<table width="95%">
<tr>
<td align="left" valign="top" width="5%"><strong>0</strong></td>
<td align="left" valign="top" width="95%">ECB</td>
</tr>
<tr>
<td align="left" valign="top" width="5%"><strong>1</strong></td>
<td align="left" valign="top" width="95%">CBC</td>
</tr>
<tr>
<td align="left" valign="top" width="5%"><strong>2</strong></td>
<td align="left" valign="top" width="95%">OFB. Not valid with AES or RC2.</td>
</tr>
<tr>
<td align="left" valign="top" width="5%"><strong>3</strong></td>
<td align="left" valign="top" width="95%">CFB 1-bit. Not valid with AES or
RC2.</td>
</tr>
<tr>
<td align="left" valign="top" width="5%"><strong>4</strong></td>
<td align="left" valign="top" width="95%">CFB 8-bit. Not valid with AES or
RC2.</td>
</tr>
<tr>
<td align="left" valign="top" width="5%"><strong>5</strong></td>
<td align="left" valign="top" width="95%">CFB 64-bit. Not valid with AES or
RC2.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Pad character</strong></dt>
<dd>The pad character for pad option 1. Using hex 00 as the pad character is
equivalent to ANSI X9.23 padding.
<br><br>
</dd>
<dt><strong>Pad option</strong></dt>
<dd>Padding, if requested, is performed at the end of the operation. Be sure
the area provided for the encrypted data is large enough to include the pad characters.
The data will be padded up to the next block length byte multiple. For example,
when using DES and and total data to encrypt is 20, the text is padded to 24.
The last byte is filled with a 1-byte binary counter containing the number of
pad characters used. The preceeding pad characters are filled as specified by
this field. Padding is not performed for modes CFB 1-bit and CFB 8-bit. In
these cases, the pad option must be set to 0. Following are the valid pad
options.
<table width="95%">
<tr>
<td align="left" valign="top" width="5%"><strong>0</strong></td>
<td align="left" valign="top" width="95%">No padding is performed.</td>
</tr>
<tr>
<td align="left" valign="top" width="5%"><strong>1</strong></td>
<td align="left" valign="top" width="95%">Use the character specified in the
pad character field for padding.</td>
</tr>
<tr>
<td align="left" valign="top" width="5%"><strong>2</strong></td>
<td align="left" valign="top" width="95%">The pad counter is used as the pad
character. This is equivalent to PKCS #5 padding.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>PKA block format</strong></dt>
<dd>The public key algorithm block format. 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%">PKCS #1 block type 00</td>
</tr>
<tr>
<td align="left" valign="top" width="5%"><strong>1</strong></td>
<td align="left" valign="top" width="95%">PKCS #1 block type 01</td>
</tr>
<tr>
<td align="left" valign="top" width="5%"><strong>2</strong></td>
<td align="left" valign="top" width="95%">PKCS #1 block type 02<br>
This format is allowed on encryption and decryption operations only.</td>
</tr>
<tr>
<td align="left" valign="top" width="5%"><strong>3</strong></td>
<td align="left" valign="top" width="95%">ISO 9796-1<br>
This format is allowed on calculate signature and verify signature operations only. Because of security weaknesses, this format should be used for compatibility purposes only.</td>
</tr>
<tr>
<td align="left" valign="top" width="5%"><strong>4</strong></td>
<td align="left" valign="top" width="95%">Zero pad<br>
This format is allowed on encryption and decryption operations only. The clear data is placed in the low-order bit positions of a string of the same bit-length as the key modulus. All leading bits are set to zero.</td>
</tr>
<tr>
<td align="left" valign="top" width="5%"><strong>5</strong></td>
<td align="left" valign="top" width="95%">ANSI X9.31<br>
This format is allowed on calculate signature and verify signature operations only.</td>
</tr>
<tr><td><img src="delta.gif" alt="Start of change"></td></tr>
<tr>
<td align="left" valign="top" width="5%"><strong>6</strong></td>
<td align="left" valign="top" width="95%">OAEP</td>
</tr>
<tr><td><img src="deltaend.gif" alt="End of change"></td></tr>
</table>
<br>
</dd>
<dt><strong>Public key algorithm</strong></dt>
<dd>Following are the valid public key algorithms:
<table width="95%">
<tr>
<td align="left" valign="top" width="5%"><strong>50</strong></td>
<td align="left" valign="top" width="95%">RSA<br>
Documented in Public-Key Cryptography Standard (PKCS) #1.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Reserved</strong></dt>
<dd>Must be null (binary 0s).
<br><br>
</dd>
<dt><strong>Signing hash algorithm</strong></dt>
<dd>The hash algorithm for a sign or verify operation. Following are the valid
values for the signing hash algorithm:
<table width="95%">
<tr>
<td align="left" valign="top" width="5%"><strong>0</strong></td>
<td align="left" valign="top" width="95%">This algorithm context will not be
used in a sign or verify operation.</td>
</tr>
<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>
</table>
<br>
</dd>
<dt><strong>Stream cipher algorithm</strong></dt>
<dd>Following are the valid stream cipher algorithms:
<table width="95%">
<tr>
<td align="left" valign="top" width="5%"><strong>30</strong></td>
<td align="left" valign="top" width="95%">RC4-compatible</td>
</tr>
</table>
</dd>
</dl>
<h3>Standards Resources</h3>
<ul>
<li>FIPS publications are available from NIST Computer Security Resource Center
at <a href="http://csrc.nist.gov/" target="_blank">http://csrc.nist.gov/</a><img src="www.gif" alt="Link outside Information Center">.</li>
<li>RFC publications are available from IETF at <a href="http://www.ietf.org" target="_blank">
http://www.ietf.org/</a><img src="www.gif" alt="Link outside Information Center">.</li>
<li>PKCS publications are available from RSA Security Inc. web pages.</li>
<li>ANSI and ISO publications are available from the ANSI eStandards store at
<a href=
"http://webstore.ansi.org/ansidocstore/" target="_blank">http://webstore.ansi.org/ansidocstore/</a><img src="www.gif" alt="Link outside Information Center">.</li>
<li>ISO publications are available from the ISO Store at <a href=
"http://www.iso.org/iso/en/prods-services/ISOstore/store.html" target="_blank">http://www.iso.org/iso/en/prods-services/ISOstore/store.html</a><img src="www.gif" alt="Link outside Information Center">.</li>
</ul>
<h3>Error Messages</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">CPF9DD2 E</td>
<td valign="top">Algorithm description format name not valid.</td>
</tr>
<tr>
<td valign="top">CPF9DD9 E</td>
<td valign="top">Effective key size 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">CPF9DDE E</td>
<td valign="top">Cipher algorithm not valid.</td>
</tr>
<tr>
<td valign="top">CPF9DDF E</td>
<td valign="top">Block length not valid.</td>
</tr>
<tr>
<td valign="top">CPF9DE0 E</td>
<td valign="top">Hash algorithm not valid.</td>
</tr>
<tr>
<td valign="top">CPF9DE1 E</td>
<td valign="top">Initialization vector not valid.</td>
</tr>
<tr>
<td valign="top">CPF9DE2 E</td>
<td valign="top">MAC (message authentication code) length not valid.</td>
</tr>
<tr>
<td valign="top">CPF9DE3 E</td>
<td valign="top">Mode not valid.</td>
</tr>
<tr>
<td valign="top">CPF9DE4 E</td>
<td valign="top">Pad option not valid.</td>
</tr>
<tr>
<td valign="top">CPF9DE5 E</td>
<td valign="top">PKA (public key algorithm) block format not valid.</td>
</tr>
<tr>
<td valign="top">CPF9DE6 E</td>
<td valign="top">Public key algorithm not valid.</td>
</tr>
<tr>
<td valign="top">CPF9DEE E</td>
<td valign="top">Reserved field not null.</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>
Reference in New Issue View Git Blame Copy Permalink