1109 lines
32 KiB
HTML
1109 lines
32 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 5/23/02 -->
|
|
<!-- Change history: -->
|
|
<!-- 030211 JETAYLOR html cleanup -->
|
|
<!-- 031020 BILLINGS Review 3 updates -->
|
|
<!-- 040621 BILLINGS V5R4 changes -->
|
|
<!-- end header records -->
|
|
<title>Create Key Context (QC3CRTKX, Qc3CreateKeyContext)</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 Key Context (QC3CRTKX, Qc3CreateKeyContext)</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%">Key string</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 key string</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%">Key format</td>
|
|
<td align="left" valign="top" width="15%">Input</td>
|
|
<td align="left" valign="top" width="15%">Char(1)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top" width="10%">4</td>
|
|
<td align="left" valign="top" width="60%">Key type</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%">5</td>
|
|
<td align="left" valign="top" width="60%">Key form</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%">6</td>
|
|
<td align="left" valign="top" width="60%">Key-encrypting 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%">7</td>
|
|
<td align="left" valign="top" width="60%">Key-encrypting algorithm</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%">Key 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%">9</td>
|
|
<td align="left" valign="top" width="60%">Error code</td>
|
|
<td align="left" valign="top" width="15%">I/O</td>
|
|
<td align="left" valign="top" width="15%">Char(*)</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<br>
|
|
Service Program Name: QC3CTX<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
Default Public Authority: *USE<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
Threadsafe: Yes<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
</div>
|
|
|
|
<p>The Create Key Context (OPM, QC3CRTKX; ILE, Qc3CreateKeyContext)
|
|
API creates a temporary area for holding a cryptographic key. The API
|
|
returns a token which can be used on subsequent cryptographic APIs when
|
|
specifying a key. The key context can not be shared between jobs. It should be
|
|
destroyed using the <a href="qc3deskx.htm">Destroy Key Context (OPM, QC3DESKX;
|
|
ILE, Qc3DestroyKeyContext) API</a>. If the key context is not destroyed before
|
|
relinquishing control, it could be used by other users of the job. If not
|
|
explicitly destroyed, the key context will be destroyed at job end.</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><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>Key string</strong></dt>
|
|
|
|
<dd>INPUT; CHAR(*)
|
|
|
|
<p><img src="delta.gif" alt="Start of change">A binary string, a formatted structure containing the
|
|
key, or a reference to the location of the key. The exact format of the key
|
|
string is specified in the key format parameter.<img src="deltaend.gif" alt="End of change">
|
|
</p>
|
|
</dd>
|
|
|
|
<dt><strong>Length of key string</strong></dt>
|
|
|
|
<dd>INPUT; BINARY(4)
|
|
|
|
<p>Length of the key string specified in the key string parameter.</p>
|
|
<p><img src="delta.gif" alt="Start of change">
|
|
Note this is not the same thing as key length. Key length is determined
|
|
based on the other parameters. Following are some examples:</p>
|
|
<ul>
|
|
<li>If key format is 0 (binary string) and
|
|
<ul>
|
|
<li>the key form is 0 (clear) then the key length equals the length of key string.</li>
|
|
<li>the key form is 1 (encrypted) then
|
|
the key length will be the decrypted key string length.</li>
|
|
</ul>
|
|
<li>If key format is 1 (BER string) then the key length will be the length
|
|
specified within the BER string.</li>
|
|
<li>If key format is 4 (a stored key) then the key length is obtained from the
|
|
stored key record.</li>
|
|
<li>If key format is 5 (a PKCS5 key) then the key length is the specified
|
|
derived key length.</li>
|
|
<li>If key format is 6 (PEM certificate) then the key length will be the length
|
|
specified in the certificate.</li>
|
|
<li>If key format is 7 or 8 (a key from certificate store) then the key length
|
|
will be the length stored in the certificate.</li>
|
|
</ul>
|
|
<br>Most algorithms have key length requirements. Refer to the key type
|
|
parameter for restrictions on key length.
|
|
<img src="deltaend.gif" alt="End of change">
|
|
<br><br>
|
|
</dd>
|
|
|
|
<dt><strong>Key format</strong></dt>
|
|
|
|
<dd>INPUT; CHAR(1)
|
|
|
|
<p>Format of the key string parameter.<br>
|
|
Following are the valid values.</p>
|
|
|
|
<table width="95%">
|
|
<tr>
|
|
<td align="left" valign="top" width="5%"><strong>0</strong></td>
|
|
<td align="left" valign="top" width="95%">Binary string. The key is specified
|
|
as a binary value. To obtain a good random key value, use the <a href=
|
|
"qc3gensk.htm">Generate Symmetric Key (OPM, QC3GENSK; ILE,
|
|
Qc3GenSymmetricKey)</a>, or <a href="qc3genprns.htm">Generate Pseudorandom
|
|
Numbers (OPM, QC3GENRN; ILE, Qc3GenPRNs)</a> API.
|
|
<br><br>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top" width="5%"><strong>1</strong></td>
|
|
<td align="left" valign="top" width="95%">BER string. If the key type field
|
|
specifies 50 (RSA public), the key may be specified in BER encoded X.509
|
|
<img src="delta.gif" alt="Start of change">
|
|
Certificate or
|
|
<img src="deltaend.gif" alt="End of change">
|
|
SubjectPublicKeyInfo
|
|
format. For specifications of these formats, refer to
|
|
RFC 3280. If the key type field specifies 51 (RSA private), the key must be
|
|
specified in BER encoded PKCS #8 format. For specifications of this format,
|
|
refer to RSA Security Inc. Public-Key Cryptography Standards. To generate a
|
|
PKA key pair, use the <a href="qc3genpk.htm">Generate PKA Key Pair (OPM, QC3GENPK;
|
|
ILE, Qc3GenPKAKeyPair)</a> API.
|
|
<br><br>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><img src="delta.gif" alt="Start of change"></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top" width="5%"><strong>4</strong></td>
|
|
<td align="left" valign="top" width="95%">Key store label. The key string
|
|
parameter identifies a key from key store. To create a key in key store, use
|
|
the <a href="qc3genkr.htm">Generate Key Record (OPM, QC3GENKR;
|
|
ILE, Qc3GenKeyRecord)</a> or
|
|
<a href="qc3wrtkr.htm">Write Key Record (OPM, QC3WRTKR;
|
|
ILE, Qc3WriteKeyRecord)</a> API.
|
|
The length of key string parameter must specify 56.
|
|
The key string parameter should contain the
|
|
following structure:
|
|
<br><br>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<blockquote>
|
|
<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="9%">0</td>
|
|
<td align="center" valign="top" width="9%">0</td>
|
|
<td align="left" valign="top" width="22%">CHAR(20)</td>
|
|
<td align="left" valign="top" width="60%">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="22%">CHAR(32)</td>
|
|
<td align="left" valign="top" width="60%">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="22%">CHAR(4)</td>
|
|
<td align="left" valign="top" width="60%">Reserved<br></td>
|
|
</tr>
|
|
|
|
</table><br>
|
|
<dl>
|
|
|
|
<dt><strong>Qualified key store file name</strong></dt>
|
|
|
|
<dd>The key store file where the key is stored. 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>
|
|
<!-- cols="15 85" -->
|
|
<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 the key record.
|
|
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).
|
|
<br><br>
|
|
</dd>
|
|
|
|
<dt><strong>Reserved</strong></dt>
|
|
|
|
<dd>Must be null (binary 0s).
|
|
<br><br>
|
|
</dd>
|
|
|
|
</dl></blockquote>
|
|
|
|
<table width="95%">
|
|
<tr>
|
|
<td align="left" valign="top" width="5%"><strong>5</strong></td>
|
|
<td align="left" valign="top" width="95%">PKCS5 passphrase.
|
|
A key is derived using RSA Data Security, Inc. Public-Key Cryptography Standard
|
|
(PKCS) #5.
|
|
The length of key string parameter must be in the range of 41 to 296.
|
|
The key string parameter should contain the following structure:
|
|
<br><br>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<blockquote>
|
|
<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="9%">0</td>
|
|
<td align="center" valign="top" width="9%">0</td>
|
|
<td align="left" valign="top" width="24%">CHAR(4)</td>
|
|
<td align="left" valign="top" width="58%">Reserved</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">BINARY(4)</td>
|
|
<td align="left" valign="top">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">BINARY(4)</td>
|
|
<td align="left" valign="top">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">BINARY(4)</td>
|
|
<td align="left" valign="top">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">CHAR(16)</td>
|
|
<td align="left" valign="top">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">BINARY(4)</td>
|
|
<td align="left" valign="top">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">BINARY(4)</td>
|
|
<td align="left" valign="top">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">CHAR(*)</td>
|
|
<td align="left" valign="top">Passphrase</td>
|
|
</tr>
|
|
|
|
</table><br>
|
|
<dl>
|
|
|
|
<dt><strong>Reserved</strong></dt>
|
|
|
|
<dd>Must be null (binary 0s).
|
|
<br><br>
|
|
</dd>
|
|
|
|
<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 1,000.
|
|
The maximum allowed length is 100,000.
|
|
<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.
|
|
<br><br>
|
|
</dd>
|
|
|
|
<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>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>Passphrase</strong></dt>
|
|
|
|
<dd>A text string.
|
|
<br><br>
|
|
</dd>
|
|
</dl>
|
|
</blockquote>
|
|
<table width="95%">
|
|
<tr>
|
|
<td align="left" valign="top" width="5%"><strong>6</strong></td>
|
|
<td align="left" valign="top" width="95%">PEM certificate. The key string
|
|
parameter contains an ASCII encoded PEM based certificate.<img src="deltaend.gif" alt="End of change">
|
|
</td>
|
|
</tr>
|
|
|
|
</table>
|
|
<br>
|
|
</dd>
|
|
|
|
<dt><strong>Key type</strong></dt>
|
|
|
|
<dd>INPUT; BINARY(4)
|
|
|
|
<p>The type of key.<br>
|
|
Following are the valid values.</p>
|
|
|
|
<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 key format must be 0
|
|
<img src="delta.gif" alt="Start of change">
|
|
4, or 5.
|
|
<img src="deltaend.gif" alt="End of change">
|
|
An MD5 key is used for HMAC (hash message
|
|
authentication code) operations. The minimum length for an MD5 HMAC key is 16
|
|
bytes. A key longer than 16 bytes does not significantly increase the function
|
|
strength unless the randomness of the key is considered weak. A key longer than
|
|
64 bytes will be hashed before it is used.</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 key format must be 0
|
|
<img src="delta.gif" alt="Start of change">
|
|
4, or 5.
|
|
<img src="deltaend.gif" alt="End of change">
|
|
An SHA-1 key is used for HMAC (hash message
|
|
authentication code) operations. The minimum length for an SHA-1 HMAC key is 20
|
|
bytes. A key longer than 20 bytes does not significantly increase the function
|
|
strength unless the randomness of the key is considered weak. A key longer than
|
|
64 bytes will be hashed before it is used.</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 key format must be 0, 4, or 5.
|
|
An SHA-256 key is used for HMAC (hash message
|
|
authentication code) operations. The minimum length for an SHA-256 HMAC key is
|
|
32 bytes. A key longer than 32 bytes does not significantly increase the
|
|
function strength unless the randomness of the key is considered weak. A key
|
|
longer than 64 bytes will be hashed before it is used.</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 key format must be 0, 4, or 5.
|
|
An SHA-384 key is used for HMAC (hash message
|
|
authentication code) operations. The minimum length for an SHA-384 HMAC key is
|
|
48 bytes. A key longer than 48 bytes does not significantly increase the
|
|
function strength unless the randomness of the key is considered weak. A key
|
|
longer than 128 bytes will be hashed before it is used.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top" width="5%"><strong>5</strong></td>
|
|
<td align="left" valign="top" width="95%">SHA-512<br>
|
|
The key format must be 0, 4, or 5.
|
|
An SHA-512 key is used for HMAC (hash message
|
|
authentication code) operations. The minimum length for an SHA-512 HMAC key is
|
|
64 bytes. A key longer than 64 bytes does not significantly increase the
|
|
function strength unless the randomness of the key is considered weak. A key
|
|
longer than 128 bytes will be hashed before it is used.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>
|
|
<img src="deltaend.gif" alt="End of change">
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top" width="5%"><strong>20</strong></td>
|
|
<td align="left" valign="top" width="95%">DES<br>
|
|
The key format must be 0
|
|
<img src="delta.gif" alt="Start of change">
|
|
4, or 5.
|
|
<img src="deltaend.gif" alt="End of change">
|
|
The key must be 8 bytes in length. Only 7 bits of each
|
|
byte are used as the actual key. The rightmost bit of each byte is used to set
|
|
parity. Some cryptographic service providers require that a DES key have odd
|
|
parity in every byte. Others ignore parity.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top" width="5%"><strong>21</strong></td>
|
|
<td align="left" valign="top" width="95%">Triple DES<br>
|
|
The key format must be 0
|
|
<img src="delta.gif" alt="Start of change">
|
|
4, or 5.
|
|
<img src="deltaend.gif" alt="End of change">
|
|
The key must be 8, 16, or 24 bytes in length. Triple DES
|
|
operates on an encryption block by doing a DES encrypt, followed by a DES
|
|
decrypt, and then another DES encrypt. Therefore, it actually uses three 8-byte
|
|
DES keys. If 24 bytes are supplied in the key string, the first 8 bytes are
|
|
used for key 1, the second 8 bytes for key 2, and the third 8 bytes for key 3.
|
|
If 16 bytes are supplied, the first 8 bytes are used for key 1 and key 3, and
|
|
the second 8 bytes for key 2. If only 8 bytes are supplied, it will be used for
|
|
all 3 keys (essentially making the operation equivalent to a single DES
|
|
operation). Only 7 bits of each byte are used as the actual key. The rightmost
|
|
bit of each byte is used to set parity. Some cryptographic service providers
|
|
require that a Triple DES key have odd parity in every byte. Others ignore
|
|
parity.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top" width="5%"><strong>22</strong></td>
|
|
<td align="left" valign="top" width="95%">AES<br>
|
|
The key format must be 0
|
|
<img src="delta.gif" alt="Start of change">
|
|
4, or 5.
|
|
<img src="deltaend.gif" alt="End of change">
|
|
The key must be 16, 24, or 32 bytes in length.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top" width="5%"><strong>23</strong></td>
|
|
<td align="left" valign="top" width="95%">RC2<br>
|
|
The key format must be 0
|
|
<img src="delta.gif" alt="Start of change">
|
|
4, or 5.
|
|
<img src="deltaend.gif" alt="End of change">
|
|
The key must be from 1 to 128 bytes in length.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top" width="5%"><strong>30</strong></td>
|
|
<td align="left" valign="top" width="95%">RC4-compatible<br>
|
|
The key format must be 0
|
|
<img src="delta.gif" alt="Start of change">
|
|
4, or 5.
|
|
<img src="deltaend.gif" alt="End of change">
|
|
The key must be from 1 to 256 bytes in length. Because of
|
|
the nature of the RC4-compatible operation, using the same key for more than
|
|
one message will severely compromise security.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top" width="5%"><strong>50</strong></td>
|
|
<td align="left" valign="top" width="95%">RSA public<br>
|
|
The key format must be 1
|
|
<img src="delta.gif" alt="Start of change">
|
|
4, or 6.
|
|
<img src="deltaend.gif" alt="End of change">
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top" width="5%"><strong>51</strong></td>
|
|
<td align="left" valign="top" width="95%">RSA private<br>
|
|
The key format must be 1
|
|
<img src="delta.gif" alt="Start of change">
|
|
or 4.
|
|
<img src="deltaend.gif" alt="End of change">
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
</dd>
|
|
|
|
<dt><strong>Key form</strong></dt>
|
|
|
|
<dd>INPUT; CHAR(1)
|
|
|
|
<p>An indicator specifying if the key string parameter is in encrypted form.</p>
|
|
|
|
<table width="95%">
|
|
<tr>
|
|
<td align="left" valign="top" width="5%"><strong>0</strong></td>
|
|
<td align="left" valign="top" width="95%">Clear.<br>
|
|
The key string is not encrypted.</td>
|
|
</tr>
|
|
|
|
<tr><td><img src="delta.gif" alt="Start of change"></td></tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><strong>1</strong></td>
|
|
<td align="left" valign="top">Encrypted with a KEK<br>
|
|
The key string is encrypted with a key-encrypting key.
|
|
Tokens are specified in the key-encrypting key and key-encrypting algorithm
|
|
parameters and are used to decrypt the key string when a cryptographic operation
|
|
is performed. This option is only allowed with key formats 0 (binary string)
|
|
and 1 (BER string.)
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top" width="5%"><strong>2</strong></td>
|
|
<td align="left" valign="top" width="95%">Encrypted with a master key<br>
|
|
The key string is encrypted with a master key. The master key is specified
|
|
in the key-encrypting key parameter. This option is only allowed with key
|
|
formats 0 (binary string) and 1 (BER string.)
|
|
</td>
|
|
</tr>
|
|
|
|
<tr><td><img src="deltaend.gif" alt="End of change"></td></tr>
|
|
|
|
</table>
|
|
<br>
|
|
</dd>
|
|
|
|
<dt><strong>Key-encrypting key</strong></dt>
|
|
|
|
<dd>INPUT; CHAR(*)
|
|
<p>The key under which the key string parameter is encrypted</p>
|
|
<p>For key form 0 (clear), this parameter must be set to blanks or the pointer
|
|
to this parameter set to NULL.</p>
|
|
<p>For key form 1 (encrypted), this parameter specifies the 8-byte key context
|
|
token to use for decrypting the key string parameter.</p>
|
|
<p><img src="delta.gif" alt="Start of change"></p>
|
|
<p>For key form 2 (encrypted with a master key), this parameter has the
|
|
following structure:</p>
|
|
<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="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%">Master key ID</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%">CHAR(4)</td>
|
|
<td align="left" valign="top" width="63%">Reserved</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="63%">Disallowed function</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%">CHAR(20)</td>
|
|
<td align="left" valign="top" width="63%">Master key KVV</td>
|
|
</tr>
|
|
|
|
</table>
|
|
<br><br>
|
|
<dl>
|
|
<dt><strong>Master key ID</strong></dt>
|
|
|
|
<dd>The master key to use for decrypting the key string parameter.
|
|
The master key IDs are<br><br>
|
|
<table width="95%">
|
|
<tr>
|
|
<td align="left" valign="top" width="5%"><strong>1</strong></td>
|
|
<td align="left" valign="top">Master key 1</td>
|
|
</tr>
|
|
<tr>
|
|
<td align="left" valign="top" width="5%"><strong>2</strong></td>
|
|
<td align="left" valign="top">Master key 2</td>
|
|
</tr>
|
|
<tr>
|
|
<td align="left" valign="top" width="5%"><strong>3</strong></td>
|
|
<td align="left" valign="top">Master key 3</td>
|
|
</tr>
|
|
<tr>
|
|
<td align="left" valign="top" width="5%"><strong>4</strong></td>
|
|
<td align="left" valign="top">Master key 4</td>
|
|
</tr>
|
|
<tr>
|
|
<td align="left" valign="top" width="5%"><strong>5</strong></td>
|
|
<td align="left" valign="top">Master key 5</td>
|
|
</tr>
|
|
<tr>
|
|
<td align="left" valign="top" width="5%"><strong>6</strong></td>
|
|
<td align="left" valign="top">Master key 6</td>
|
|
</tr>
|
|
<tr>
|
|
<td align="left" valign="top" width="5%"><strong>7</strong></td>
|
|
<td align="left" valign="top">Master key 7</td>
|
|
</tr>
|
|
<tr>
|
|
<td align="left" valign="top" width="5%"><strong>8</strong></td>
|
|
<td align="left" valign="top">Master key 8</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
</dd>
|
|
|
|
<dt><strong>Disallowed function</strong></dt>
|
|
|
|
<dd>INPUT; BINARY(4)
|
|
|
|
<p>This parameter specifies the functions that are not allowed to be used with
|
|
this key. This value was XOR'd into the master key when this key was encrypted
|
|
and therefore must be used when creating a key context for this key.
|
|
The values listed below can be added together to disallow multiple functions.
|
|
For example, to disallow everything but MACing, set the value to 11.</p>
|
|
|
|
<table width="95%">
|
|
<tr>
|
|
<td align="left" valign="top" width="5%"><strong>0</strong></td>
|
|
<td align="left" valign="top" width="95%">No functions are disallowed.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><strong>1</strong></td>
|
|
<td align="left" valign="top">Encryption is disallowed.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><strong>2</strong></td>
|
|
<td align="left" valign="top">Decryption is disallowed.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><strong>4</strong></td>
|
|
<td align="left" valign="top">MACing is disallowed.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><strong>8</strong></td>
|
|
<td align="left" valign="top">Signing is disallowed.</td>
|
|
</tr>
|
|
|
|
</table>
|
|
<br>
|
|
</dd>
|
|
|
|
<dt><strong>Master key KVV</strong></dt>
|
|
|
|
<dd>The master key verification value. The master key version with a KVV that
|
|
matches this value will be used to decrypt the key. If this value is
|
|
null, the current version of the master key will be used.
|
|
<br><br>
|
|
</dd>
|
|
|
|
<dt><strong>Reserved</strong></dt>
|
|
|
|
<dd>Must be null (binary 0s).
|
|
<br><br>
|
|
</dd>
|
|
|
|
</dl>
|
|
<p><img src="deltaend.gif" alt="End of change"></p>
|
|
</dd>
|
|
|
|
<dt><strong>Key-encrypting algorithm</strong></dt>
|
|
|
|
<dd>INPUT; CHAR(8)
|
|
|
|
<p>For key form 0 (clear) and 2 (encrypted with a master key), this parameter
|
|
must be set to blanks or the pointer to this parameter set to NULL.</p>
|
|
<p>For key form 1 (encrypted), this parameter specifies the algorithm context
|
|
token to use for decrypting the key string parameter.
|
|
</p>
|
|
</dd>
|
|
|
|
<dt><strong>Key context token</strong></dt>
|
|
|
|
<dd>OUTPUT; CHAR(8)
|
|
|
|
<p>The area to store the token for the created key 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.<br>
|
|
</p>
|
|
</dd>
|
|
|
|
<dt><strong>Error code</strong></dt>
|
|
|
|
<dd>I/O; CHAR(*)
|
|
|
|
<p>The structure in which to return error information.<br>
|
|
For the format of the structure, see <a href="../apiref/error.htm#hdrerrcod">Error Code
|
|
Parameter</a>.</p>
|
|
</dd>
|
|
|
|
</dl>
|
|
|
|
<br>
|
|
|
|
|
|
<h3>Error Messages</h3>
|
|
|
|
<table width="100%">
|
|
<tr>
|
|
<th align="left" valign="top">Message ID</th>
|
|
<th align="left" valign="top">Error Message Text</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td width="15%" valign="top">CPF24B4 E</td>
|
|
<td width="85%" valign="top">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"><img src="delta.gif" alt="Start of change"></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">CPF9DAC E</td>
|
|
<td valign="top">Disallowed function value not valid.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top">CPF9DAD E</td>
|
|
<td valign="top">The master key ID is not valid.</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 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"><img src="deltaend.gif" alt="End of change"></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top">CPF9DDA E</td>
|
|
<td valign="top">Unexpected return code &1.</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">CPF9DE7 E</td>
|
|
<td valign="top">Key type not valid.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top">CPF9DE8 E</td>
|
|
<td valign="top">Key form not valid.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top">CPF9DE9 E</td>
|
|
<td valign="top">Key format not valid.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top">CPF9DEE E</td>
|
|
<td valign="top">Reserved field not null.</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">CPF9DFC E</td>
|
|
<td valign="top">The key-encrypting algorithm or key context token is not valid.</td>
|
|
</tr>
|
|
|
|
</table>
|
|
<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>
|
|
|