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

730 lines
18 KiB
HTML
Raw 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 V5R4 by beth hagemeister 3/22/05 -->
<!-- Change history: -->
<!-- end header records -->
<title>Extract Public Key (QC3EXTPB, Qc3ExtractPublicKey)</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">Extract Public Key (QC3EXTPB,
Qc3ExtractPublicKey)</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 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%">5</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%">6</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%">7</td>
<td align="left" valign="top" width="60%">Public 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%">8</td>
<td align="left" valign="top" width="60%">Length of area provided for public
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%">9</td>
<td align="left" valign="top" width="60%">Length of public 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%">10</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: QC3PBEXT
<br>
<!-- iddvc RMBR -->
<br>
&nbsp;Default Public Authority: *USE
<br>
<!-- iddvc RMBR -->
<br>
&nbsp;Threadsafe: Yes
<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The Extract Public Key (OPM, QC3EXTPB; ILE, Qc3ExtractPublicKey) API extracts
a public key from a BER encoded PKCS #8 string or from a key record containing a
public or private PKA key.</p>
<br>
<h3>Authorities and Locks</h3>
<dl>
<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 BER encoded PKCS #8 string, or a formatted structure identifying a key
record in key store. 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>1</strong></td>
<td align="left" valign="top" width="95%">BER string. 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.
</td>
</tr>
<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:
<br>
<br>
<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="10%">0</td>
<td align="center" valign="top" width="10%">0</td>
<td align="left" valign="top" width="20%">CHAR(20)</td>
<td align="left" valign="top" width="60%">Qualified key store file name</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">Record label</td>
</tr>
<tr>
<td align="center" valign="top">52</td>
<td align="center" valign="top">34</td>
<td align="left" valign="top">CHAR(4)</td>
<td align="left" valign="top">Reserved</td>
</tr>
</table>
<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>
<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>
</td>
</tr>
</table>
</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 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. This option is only allowed
with key string format 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
string format 1 (BER string.)
</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>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>
<dl>
<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 decrypting the key string.
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="10%"><strong>0</strong></td>
<td align="left" valign="top" width="85%">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 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="15%"><strong>1</strong></td>
<td align="left" valign="top">Master key 1</td>
</tr>
<tr>
<td align="left" valign="top" width="15%"><strong>2</strong></td>
<td align="left" valign="top">Master key 2</td>
</tr>
<tr>
<td align="left" valign="top" width="15%"><strong>3</strong></td>
<td align="left" valign="top">Master key 3</td>
</tr>
<tr>
<td align="left" valign="top" width="15%"><strong>4</strong></td>
<td align="left" valign="top">Master key 4</td>
</tr>
<tr>
<td align="left" valign="top" width="15%"><strong>5</strong></td>
<td align="left" valign="top">Master key 5</td>
</tr>
<tr>
<td align="left" valign="top" width="15%"><strong>6</strong></td>
<td align="left" valign="top">Master key 6</td>
</tr>
<tr>
<td align="left" valign="top" width="15%"><strong>7</strong></td>
<td align="left" valign="top">Master key 7</td>
</tr>
<tr>
<td align="left" valign="top" width="15%"><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).
<br><br>
</dd>
</dl>
</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>Public key</strong></dt>
<dd>OUTPUT; CHAR(*)
<p>The area to store the public key. This parameter will contain the extracted
public key in BER encoded X.509 SubjectPublicKeyInfo format.
</p>
</dd>
<dt><strong>Length of area provided for public key</strong></dt>
<dd>INPUT; BINARY(4)
<p>The length of the public key parameter.
</p>
</dd>
<dt><strong>Length of public key returned</strong></dt>
<dd>OUTPUT; BINARY(4)
<p>The length of the extracted public key returned in the public key parameter.
<br>
If the length of area provided for the public key is too small, an error will
be generated and no data will be returned in the public key parameter.
</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><a name="header_9">Error Messages</a></h3>
<table width="100%">
<tr>
<th align="left" valign="top">Message ID</th>
<th align="left" valign="top">Error Message Text</th>
</tr>
<tr>
<td 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">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">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 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">CPF9DB8 E</td>
<td valign="top">Error occured retrieving key record from key store.</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">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">CPF9DC6 E</td>
<td valign="top">Algorithm not valid for encrypting or decrypting a key.</td>
</tr>
<tr>
<td valign="top">CPF9DCE E</td>
<td valign="top">A data length is not valid.</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">CPF9DD7 E</td>
<td valign="top">The key-encrypting key context for the specified key is not valid or was previously destroyed.</td>
</tr>
<tr>
<td valign="top">CPF9DD8 E</td>
<td valign="top">The key-encrypting algorithm context for the specified key is not valid or was previously destroyed.</td>
</tr>
<tr>
<td valign="top">CPF9DDA E</td>
<td valign="top">Unexpected return code &amp;1.</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">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">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">CPF9DFC E</td>
<td valign="top">The key-encrypting algorithm or key context token is not valid.</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>
Reference in New Issue View Git Blame Copy Permalink