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

534 lines
16 KiB
HTML
Raw Normal View History

2024-04-02 14:02:31 +00:00
<!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 V5R4 by beth hagemeister 7/12/04 -->
<!-- Change history: -->
<!-- end header records -->
<title>Generate Key Record (QC3GENKR, Qc3GenKeyRecord)</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><img src="delta.gif" alt="Start of change">Generate Key Record
(QC3GENKR, Qc3GenKeyRecord)</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%">Qualified key store file name</td>
<td align="left" valign="top" width="15%">Input</td>
<td align="left" valign="top" width="15%">Char(20)</td>
</tr>
<tr>
<td align="center" valign="top" width="10%">2</td>
<td align="left" valign="top" width="60%">Record label</td>
<td align="left" valign="top" width="15%">Input</td>
<td align="left" valign="top" width="15%">Char(32)</td>
</tr>
<tr>
<td align="center" valign="top" width="10%">3</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%">4</td>
<td align="left" valign="top" width="60%">Key size</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%">Public key exponent</td>
<td align="left" valign="top" width="15%">Input</td>
<td align="left" valign="top" width="15%">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top" width="10%">6</td>
<td align="left" valign="top" width="60%">Disallowed function</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%">7</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%">8</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%">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;Service Program Name: QC3KRGEN<br>
<!-- iddvc RMBR -->
<br>
&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;Threadsafe: Yes<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The Generate Key Record (OPM, QC3GENKR; ILE,
Qc3GenKeyRecord) API generates a random key or key pair and stores it in a key store file.
</p>
<p>For more information about cryptographic services key store, refer to
<a href="qc3KeyStore.htm">Cryptographic Services Key Store</a>e.
</p>
<br>
<h3>Authorities and Locks</h3>
<dl>
<dt><strong>Required file authority</strong></dt>
<dd>*OBJOPR, *READ, *ADD<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>Qualified key store file name</strong></dt>
<dd>INPUT; CHAR(20)
<p>The key store file where the key will be 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.</p>
</dd>
<dt><strong>Record label</strong></dt>
<dd>INPUT; CHAR(32)
<p>The label for 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).
</p>
</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%">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top" width="5%"><strong>1</strong></td>
<td align="left" valign="top" width="95%">MD5<br>
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>
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 align="left" valign="top" width="5%"><strong>3</strong></td>
<td align="left" valign="top" width="95%">SHA-256<br>
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>
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>
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 align="left" valign="top" width="5%"><strong>20</strong></td>
<td align="left" valign="top" width="95%">DES<br>
Only 7 bits of each byte are used as the actual key. The rightmost bit of each byte will be set to odd parity because some cryptographic service providers require that a DES key have odd parity in every byte.<br>
The key size parameter must specify 8.</td>
</tr>
<tr>
<td align="left" valign="top" width="5%"><strong>21</strong></td>
<td align="left" valign="top" width="95%">Triple DES<br>
Only 7 bits of each byte are used as the actual key. The rightmost bit of each byte will be set to odd parity because some cryptographic service providers require that a DES key have odd parity in every byte. <br>
The key size can be 8, 16, or 24. 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 the key is 24 bytes in length, 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 the key is 16 bytes in length, the first 8 bytes are used for key 1 and key 3, and the second 8 bytes for key 2. If the key is only 8 bytes in length, it will be used for all 3 keys (essentially making the operation equivalent to a single DES operation).</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 size can be 16, 24, or 32.</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 size can be 1 - 128.</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 size can be 1 - 256. 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<br>
The key size specifies the modulus length in bits and
must be an even number in the range 512 - 2048.
Both the RSA public and private key parts are stored in the key record.
</td>
</tr>
</table>
</dd>
<dt><strong>Key size</strong></dt>
<dd>INPUT; BINARY(4)
<p>The length of key to generate. For RSA keys this length is specified in
bits. For all other keys it is specified in bytes.<br>
Refer to the key type parameter for restrictions.
</p>
</dd>
<dt><strong>Public key exponent</strong></dt>
<dd>INPUT; BINARY(4)
<p>This parameter is valid when key type parameter specifies 50 (RSA).
Otherwise, this parameter must be set to 0.
To maximize performance, the public key exponent is limited to the following
two values.</p>
<table width="95%">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top" width="8%"><strong>3</strong></td>
<td align="left" valign="top" width="92%">Or hex &nbsp; 00 00 00 03.</td>
</tr>
<tr>
<td align="left" valign="top" width="8%"><strong>65,537</strong></td>
<td align="left" valign="top" width="92%">Or hex &nbsp; 00 01 00 01.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Disallowed function</strong></dt>
<dd>INPUT; BINARY(4)
<p>This parameter specifies the functions that cannot be used with this key
record. 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%">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top" width="10%"><strong>0</strong></td>
<td align="left" valign="top" width="90%">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>Cryptographic service provider</strong></dt>
<dd>INPUT; CHAR(1)
<p>The cryptographic service provider (CSP) that will perform the key generate operation.</p>
<table width="95%">
<!-- cols="5 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 key generate 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 key generate operation using software.</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 key generate operation using cryptographic hardware. If the requested key type can not be generated 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>Error code</strong></dt>
<dd>I/O; CHAR(*)
<p>The structure in which to return error information.
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 &amp;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 &amp;1
API.</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">CPF9D9E E</td>
<td valign="top">Record label already exists.</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">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">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">CPF9DB7 E</td>
<td valign="top">Error occured writing to key store.</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">CPF9DDA E</td>
<td valign="top">Unexpected return code &amp;1.</td>
</tr>
<tr>
<td valign="top">CPF9DE7 E</td>
<td valign="top">Key type not valid.</td>
</tr>
<tr>
<td valign="top">CPF9DEA E</td>
<td valign="top">Key size not valid.</td>
</tr>
<tr>
<td valign="top">CPF9DEB E</td>
<td valign="top">Public key exponent 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">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">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>
<img src="deltaend.gif" alt="End of change"><br>
<hr>
API introduced: V5R4
<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>