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

701 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 V5R4 by beth hagemeister 6/29/04 -->
<!-- Change history: -->
<!-- 050321 BILLINGS V5R4 Remove public key parms -->
<!-- end header records -->
<title>Export Key (QC3EXPKY, Qc3ExportKey)</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">Export Key (QC3EXPKY,
Qc3ExportKey)</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%">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 string 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-encrypting key context token</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%">5</td>
<td align="left" valign="top" width="60%">Key-encrypting algorithm context
token</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%">Exported key</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%">7</td>
<td align="left" valign="top" width="60%">Length of area provided for exported
key</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%">8</td>
<td align="left" valign="top" width="60%">Length of exported key returned</td>
<td align="left" valign="top" width="15%">Output</td>
<td align="left" valign="top" width="15%">Binary(4)</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: QC3KYEXP<br>
<!-- iddvc RMBR -->
<br>
&nbsp;Default Public Authority: *EXCLUDE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;Threadsafe: Yes
<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The Export Key (OPM, QC3EXPKY; ILE, Qc3ExportKey) API decrypts a key
encrypted under a master key and re-encrypts it under the specified
key-encrypting key.</p>
<p>Because this API could be used to recover the clear values of keys
stored in key store files, care
should be taken to restrict access to this API.</p>
<br>
<h3>Authorities and Locks</h3>
<dl>
<dt><strong>Required special authority</strong></dt>
<dd>*ALLOBJ and *SECADM
<br>
<br>
</dd>
<dt><strong>Required file authority</strong></dt>
<dd>*OBJOPR, *READ
<br>
<br>
</dd>
</dl>
<br>
<h3>Required Parameter Group</h3>
<dl>
<dt><strong>Key string</strong></dt>
<dd>INPUT; CHAR(*)
<p>A formatted structure identifying a key encrypted under a master key. The
exact format of the key string is specified in the key string format
parameter.</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>
</dd>
<dt><strong>Key string format</strong></dt>
<dd>INPUT; CHAR(1)
<p>Format of the key string parameter.
<br>
Following are the valid values.</p>
<table width="95%">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top" width="5%"><strong>3</strong></td>
<td align="left" valign="top" width="95%">The key string parameter specifies a
key value encrypted under a master key. The key string parameter should contain
the following structure:
</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="left" valign="bottom">Dec</th>
<th align="left" valign="bottom">Hex</th>
</tr>
<tr>
<td align="center" valign="top" width="9%">0</td>
<td align="center" valign="top" width="9%">0</td>
<td align="left" valign="top" width="21%">BINARY(4)</td>
<td align="left" valign="top" width="61%">Master key ID</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="center" valign="top">4</td>
<td align="left" valign="top">CHAR(4)</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">Disallowed function</td>
</tr>
<tr>
<td align="center" valign="top">12</td>
<td align="center" valign="top">C</td>
<td align="left" valign="top">CHAR(20)</td>
<td align="left" valign="top">Master key KVV</td>
</tr>
<tr>
<td align="center" valign="top">32</td>
<td align="center" valign="top">20</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Encrypted key</td>
</tr>
</table>
<dl>
<dt><br><strong>Disallowed function</strong></dt>
<dd>INPUT; BINARY(4)
<p>This parameter specifies the functions that were not allowed to be used with
this key. This value was XOR'd into the master key when the key was encrypted
and therefore must be used in exporting the key. The values listed below can be
added together to disallow multiple functions. For example, if the key only
allowed MACing, this value would be 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>Encrypted key</strong></dt>
<dd>The encrypted key may be a symmetric key or a BER encoded PKCS #8 private
key string encrypted under the specified master key.
<br><br>
</dd>
<dt><strong>Master key ID</strong></dt>
<dd>The master key IDs are
<table width="95%">
<tr>
<td align="left" valign="top" width="5%"><strong>1</strong></td>
<td align="left" valign="top" width="95%">Master key 1</td>
</tr>
<tr>
<td align="left" valign="top"><strong>2</strong></td>
<td align="left" valign="top">Master key 2</td>
</tr>
<tr>
<td align="left" valign="top"><strong>3</strong></td>
<td align="left" valign="top">Master key 3</td>
</tr>
<tr>
<td align="left" valign="top"><strong>4</strong></td>
<td align="left" valign="top">Master key 4</td>
</tr>
<tr>
<td align="left" valign="top"><strong>5</strong></td>
<td align="left" valign="top">Master key 5</td>
</tr>
<tr>
<td align="left" valign="top"><strong>6</strong></td>
<td align="left" valign="top">Master key 6</td>
</tr>
<tr>
<td align="left" valign="top"><strong>7</strong></td>
<td align="left" valign="top">Master key 7</td>
</tr>
<tr>
<td align="left" valign="top"><strong>8</strong></td>
<td align="left" valign="top">Master key 8</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).</dd>
</dl>
</blockquote>
<table width="95%">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top" width="5%"><strong>4</strong></td>
<td align="left" valign="top" width="95%">The key string parameter identifies a
key in 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 key string parameter should contain the
following structure:</td>
</tr>
</table>
<br>
<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="left" valign="bottom">Dec</th>
<th align="left" valign="bottom">Hex</th>
</tr>
<tr>
<td align="center" valign="top" width="9%">0</td>
<td align="center" valign="top" width="9%">0</td>
<td align="left" valign="top" width="19%">CHAR(20)</td>
<td align="left" valign="top" width="66%">Qualified key store file name</td>
</tr>
<tr>
<td align="center" valign="top" width="9%">20</td>
<td align="center" valign="top" width="9%">14</td>
<td align="left" valign="top" width="19%">CHAR(32)</td>
<td align="left" valign="top" width="63%">Record label</td>
</tr>
<tr>
<td align="center" valign="top" width="9%">52</td>
<td align="center" valign="top" width="9%">34</td>
<td align="left" valign="top" width="19%">CHAR(4)</td>
<td align="left" valign="top" width="63%">Reserved</td>
</tr>
</table>
<dl>
<dt><br><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>
<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).
</dd>
</dl>
</blockquote>
</dd>
<dt><strong>Key-encrypting key context token</strong></dt>
<dd>INPUT; CHAR(8)
<p>The token for the key context to use for encrypting the key.
<br>
The key context is created using the <a href="qc3crtkx.htm">Create Key Context
(OPM, QC3CRTKX; ILE, Qc3CreateKeyContext) API</a>.</p>
</dd>
<dt><strong>Key-encrypting algorithm context token</strong></dt>
<dd>INPUT; CHAR(8)
<p>The token for the algorithm context to use for encrypting the key.
<br>
The algorithm context is created using the <a href="qc3crtax.htm">Create
Algorithm Context (OPM, QC3CRTAX; ILE, Qc3CreateAlgorithmContext) API</a>.</p>
</dd>
<dt><strong>Exported key</strong></dt>
<dd>OUTPUT; CHAR(*)
<p>The area to store the exported key. This parameter will contain the exported
symmetric key or the exported PKCS #8 private key string.</p>
</dd>
<dt><strong>Length of area provided for exported key</strong></dt>
<dd>INPUT; BINARY(4)
<p>The length of the exported key parameter.
<br>
Be sure to add any space necessary for padding.
<br>
If the encrypt mode of operation is CFB 1-bit, this length must be specified in
bits, otherwise it must be specified in bytes.</p>
</dd>
<dt><strong>Length of exported key returned</strong></dt>
<dd>OUTPUT; BINARY(4)
<p>The length of the exported key returned in the exported key parameter.
<br>
If the length of area provided for the exported key is too small, an error will
be generated and no data will be returned in the exported key parameter.
<br>
If the encrypt mode of operation is CFB 1-bit, the length will be returned in
bits, otherwise it is returned in bytes.</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%" cellpadding="5">
<!-- cols="15 85" -->
<tr>
<th align="left" valign="top">Message ID</th>
<th align="left" valign="top">Error Message Text</th>
</tr>
<tr>
<td valign="top">CPF222E E</td>
<td valign="top">&amp;1 special authority is required.</td>
</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">CPF9D98 D</td>
<td valign="top">Operation not valid for this key type.</td>
</tr>
<tr>
<td valign="top">CPF9D9F D</td>
<td valign="top">Not authorized to key store file.</td>
</tr>
<tr>
<td valign="top">CPF9DA0 D</td>
<td valign="top">Error occured opening key store file.</td>
</tr>
<tr>
<td valign="top">CPF9DA5 D</td>
<td valign="top">Key store file not found.</td>
</tr>
<tr>
<td valign="top">CPF9DA6 D</td>
<td valign="top">The key store file is not available.</td>
</tr>
<tr>
<td valign="top">CPF9DA7 D</td>
<td valign="top">File is corrupt or not a valid key store file.</td>
</tr>
<tr>
<td valign="top">CPF9DAA D</td>
<td valign="top">A key requires translation.</td>
</tr>
<tr>
<td valign="top">CPF9DAB E</td>
<td valign="top">A key can not be decrypted.</td>
</tr>
<tr>
<td valign="top">CPF9DAC D</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">CPF9DB3 E</td>
<td valign="top">Qualified key store file name not valid.</td>
</tr>
<tr>
<td valign="top">CPF9DB6 E</td>
<td valign="top">Record label not valid.</td>
</tr>
<tr>
<td valign="top">CPF9DB8 E</td>
<td valign="top">Error occured retrieving key record from key store.</td>
</tr>
<tr>
<td valign="top">CPF9DC2 E</td>
<td valign="top">Key-encrypting algorithm context not compatible with key-encrypting key context.</td>
</tr>
<tr>
<td valign="top">CPF9DC3 E</td>
<td valign="top">Unable to decrypt data or key.</td>
</tr>
<tr>
<td valign="top">CPF9DD6 E</td>
<td valign="top">Length of area provided for output data is too small.</td>
</tr>
<tr>
<td valign="top">CPF9DDB E</td>
<td valign="top">The key string or Diffie-Hellman parameter string is not valid.</td>
</tr>
<tr>
<td valign="top">CPF9DDD E</td>
<td valign="top">The key string length is not valid.</td>
</tr>
<tr>
<td valign="top">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>
</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>