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

685 lines
19 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">
<title>Sign Buffer (QYDOSGNB, QydoSignBuffer)</title>
<!-- 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. -->
<!-- Change History: -->
<!-- YYMMDD USERID Change description -->
<!-- created by Harold Romo for V5R2 -->
<!-- End Header Records -->
<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>Sign Buffer (QYDOSGNB, QydoSignBuffer)</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="50%">Buffer to sign</td>
<td align="left" valign="top" width="20%">Input</td>
<td align="left" valign="top" width="20%">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">2</td>
<td align="left" valign="top">Description of buffer to sign</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">3</td>
<td align="left" valign="top">Number of descriptions of buffer to sign</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="left" valign="top">Application identifier</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">5</td>
<td align="left" valign="top">Length of application identifier</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">6</td>
<td align="left" valign="top">Resulting signature</td>
<td align="left" valign="top">Output</td>
<td align="left" valign="top">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">7</td>
<td align="left" valign="top">Length of resulting signature provided</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">8</td>
<td align="left" valign="top">Format of resulting signature</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(8)</td>
</tr>
<tr>
<td align="center" valign="top">9</td>
<td align="left" valign="top">Error Code</td>
<td align="left" valign="top">I/O</td>
<td align="left" valign="top">Char(*)</td>
</tr>
</table>
<br>
&nbsp;&nbsp;Service Program Name: QYDOBUFFER<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: No<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The Sign Buffer (OPM, QYDOSGNB; ILE, QydoSignBuffer) API allows the local
system to certify that the series of bytes being signed is trustworthy. It does
this by generating a digital signature for those bytes and returning this
signature to the caller.</p>
<p>The application identifier will be used to find the certificate needed to
sign this object. The certificate will be used later to verify the contents of
this object have not changed and this certificate will be reported as having
signed this object.</p>
<br>
<h3>Authorities and Locks</h3>
<dl>
<dt><em>API Public Authority</em></dt>
<dd>*USE.<br>
<br>
</dd>
<dt><em>Authority Required</em></dt>
<dd>To use this API, you must be authorized to the object signing applications
function associated with your application identifier through iSeries
Navigator's application administration support. The Change Function Usage
Information(QSYCHFUI) API, with a function ID of the same name as the
application identifier, also can be used to change the list of users that are
allowed to use this application identifier.</dd>
</dl>
<br>
<h3>Required Parameter Group</h3>
<dl>
<dt><strong>Buffer to sign</strong></dt>
<dd>INPUT; CHAR(*)
<p>The buffer of data to be signed. Only the part of the object described in
the Description of buffer to sign will be signed.</p>
</dd>
<dt><strong>Description of buffer to sign</strong></dt>
<dd>INPUT; CHAR(*)
<p>Array of offsets and lengths to the data to be signed. The API will treat
these bytes as if they were a contiguous stream of bytes. The offset is from
the start of the buffer.</p>
<p>The format of the description of the data to sign is in the following table.
For detailed descriptions of the fields in this table, see <a href=
"#HDRfield">Field Descriptions</a>.</p>
<table border width="80%">
<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%">Offset to start of first series of bytes to
sign</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">Length of first series of bytes to sign</td>
</tr>
<tr>
<td align="center" valign="top">n</td>
<td align="center" valign="top">n</td>
<td align="left" valign="top">Binary(4)</td>
<td align="left" valign="top">Offset to start of next series of bytes to
sign</td>
</tr>
<tr>
<td align="center" valign="top">n+4</td>
<td align="center" valign="top">n+10</td>
<td align="left" valign="top">Binary(4)</td>
<td align="left" valign="top">Length of next series of bytes to sign</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Number of descriptions of buffer to sign</strong></dt>
<dd>INPUT; BINARY(4)
<p>Number of offsets and lengths needed to describe what parts of the buffer
should be signed.</p>
</dd>
<dt><strong>Application identifier</strong></dt>
<dd>INPUT; CHAR(*)
<p>The user-supplied application ID to sign objects with. The application type
must be 4 (object signing) and it must be assigned to a valid certificate
label.</p>
</dd>
<dt><strong>Length of application identifier</strong></dt>
<dd>INPUT; BINARY(4)
<p>The length of the specified application identifier. This length must be a
value from 1 to 30.</p>
</dd>
<dt><strong>Resulting signature</strong></dt>
<dd>OUTPUT; CHAR(*)
<p>Area to contain the signature to be returned by the API. See <a href=
"#HDRSGNP1">Resulting signature formats</a> for details on the format of this
parameter. This field may be NULL if the length of resulting signature provided
is 0.</p>
</dd>
<dt><strong>Length of resulting signature provided</strong></dt>
<dd>INPUT; BINARY(4)
<p>The length of the area provided to contain the returned signature.</p>
</dd>
<dt><strong>Format of resulting signature</strong></dt>
<dd>INPUT; CHAR(8)
<p>The format of the results of the signing operation.</p>
<table cellpadding="5">
<!-- cols="30 70" -->
<tr>
<td align="left" valign="top"><em><a href="#SGNB0100">SGNB0100</a></em></td>
<td align="left" valign="top">Just the signature itself is returned. The
signature will be in PKCS #1 block type 01 format.</td>
</tr>
<tr>
<td align="left" valign="top"><em><a href="#SGNB0200">SGNB0200</a></em></td>
<td align="left" valign="top">The signature itself and the certificate label
needed to verify the signature are returned. The signature will be in PKCS #1
block type 01 format.</td>
</tr>
<tr>
<td align="left" valign="top"><em><a href="#SGNB0300">SGNB0300</a></em></td>
<td align="left" valign="top">The signature itself and the ASN.1 encoded
certificate itself needed to verify the signature are returned. The signature
will be in PKCS #1 block type 01 format.</td>
</tr>
<tr>
<td align="left" valign="top"><em><a href="#SGNB0400">SGNB0400</a></em></td>
<td align="left" valign="top">The signature itself and the distinguished name
of the certificate needed to verify the signature are returned. The signature
will be in PKCS #1 block type 01 format.</td>
</tr>
</table>
<br>
</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="HDRfield">Field Descriptions</a></h3>
<p><strong>Length of first series of bytes to sign</strong> The number of
bytes, including the first byte in the series, to be included in the
signature.</p>
<p><strong>Length of next series of bytes to sign</strong> The number of bytes,
including the first byte in the series, to be included in the signature.</p>
<p><strong>Offset to start of first series of bytes to sign.</strong> An offset
to the first byte of a series of 1 or more bytes of data to be included in the
signature.</p>
<p><strong>Offset to start of next series of bytes to sign.</strong> An offset
to the first byte of a series of 1 or more bytes of data to be included in the
signature.<br>
</p>
<h3><a name="HDRSGNP1">Resulting signature formats</a></h3>
<p>For detailed descriptions of the fields in the tables, see <a href=
"#HDRSGNP2">Field Descriptions</a>.</p>
<h3><a name="SGNB0100">SGNB0100 format</a></h3>
<table border width="80%">
<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%">Offset to start of signature</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">Length of signature</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Signature</td>
</tr>
</table>
<br>
<br>
<h3><a name="SGNB0200">SGNB0200 format</a></h3>
<table border width="80%">
<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%">Offset to start of signature</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">Length of signature</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">Offset to start of certificate label</td>
</tr>
<tr>
<td align="center" valign="top">12</td>
<td align="center" valign="top">0C</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Length of certificate label</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Signature</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Certificate label</td>
</tr>
</table>
<br>
<br>
<h3><a name="SGNB0300">SGNB0300 format</a></h3>
<table border width="80%">
<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%">Offset to start of signature</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">Length of signature</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">Offset to start of certificate</td>
</tr>
<tr>
<td align="center" valign="top">12</td>
<td align="center" valign="top">0C</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Length of certificate</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Signature</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Certificate</td>
</tr>
</table>
<br>
<br>
<h3><a name="SGNB0400">SGNB0400 format</a></h3>
<table border width="80%">
<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%">Offset to start of signature</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">Length of signature</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">Offset to start of distinguished name</td>
</tr>
<tr>
<td align="center" valign="top">12</td>
<td align="center" valign="top">0C</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Length of distinguished name</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Signature</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Distinguished name</td>
</tr>
</table>
<br>
<br>
<h3><a name="HDRSGNP2">Field Descriptions</a></h3>
<p><strong>Certificate.</strong> The ASN.1 encoded certificate that is needed
to verify the signature.</p>
<p><strong>Certificate label.</strong> The label of the certificate that is
needed to verify the signature. This is the label of the certificate in the
*OBJECTSIGNING certificate store on the local system. This certificate will
need to be exported to the system that will verify this signature.</p>
<p><strong>Distinguished name.</strong> The distinguished name of the
certificate that is needed to verify the signature.</p>
<p><strong>Length of certificate.</strong> Number of bytes needed to contain
the ASN.1 encoded certificate.</p>
<p><strong>Length of certificate label.</strong> Number of bytes needed to
contain the certificate label.</p>
<p><strong>Length of distinguished name.</strong> Number of bytes needed to
contain the distinguished name.</p>
<p><strong>Length of signature.</strong> Number of bytes needed to contain the
signature.</p>
<p><strong>Offset to start of certificate.</strong> Offset from the beginning
of this structure to the certificate.</p>
<p><strong>Offset to start of certificate label.</strong> Offset from the
beginning of this structure to the certificate label.</p>
<p><strong>Offset to start of distinguished name.</strong> Offset from the
beginning of this structure to the distinguished name.</p>
<p><strong>Offset to start of signature.</strong> Offset from the beginning of
this structure to the signature.</p>
<p><strong>Signature.</strong> The encrypted hash of the bytestream that was
passed in to this API. This can be used later to see if the bytestream has
changed.</p>
<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 width="15%" valign="top">CPFB724 E</td>
<td width="85%" valign="top">Option &amp;2 of the operating system is required
to work with object signatures.</td>
</tr>
<tr>
<td valign="top">CPFB731 E</td>
<td valign="top">Certificate store not found.</td>
</tr>
<tr>
<td valign="top">CPFB735 E</td>
<td valign="top">The digital signing API parameter &amp;1 is not large
enough.</td>
</tr>
<tr>
<td valign="top">CPFB736 E</td>
<td valign="top">The digital signing API parameter &amp;1 is not small
enough.</td>
</tr>
<tr>
<td valign="top">CPFB737 E</td>
<td valign="top">The digital signing API parameter &amp;1 is a null
pointer.</td>
</tr>
<tr>
<td valign="top">CPFB738 E</td>
<td valign="top">The digital signing API parameter &amp;1 is not a valid format
type.</td>
</tr>
<tr>
<td valign="top">CPFB739 E</td>
<td valign="top">The digital signing API parameter &amp;1 is out of range.</td>
</tr>
<tr>
<td valign="top">CPFB73A E</td>
<td valign="top">The password for the certificate key database needs to be
set.</td>
</tr>
<tr>
<td valign="top">CPFB73F E</td>
<td valign="top">The signing application certificate is expired.</td>
</tr>
<tr>
<td valign="top">CPFB74A E</td>
<td valign="top">The application identifier on the digital signing API is not
in a valid state.</td>
</tr>
<tr>
<td valign="top">CPF9EA0 E</td>
<td valign="top">Length of resulting signature area is too small to hold
results.</td>
</tr>
<tr>
<td valign="top">CPF9EAF E</td>
<td valign="top">Attempt to sign or verify buffers failed with unexpected
return code &amp;1.</td>
</tr>
</table>
<br>
<hr>
API introduced: V5R2
<hr>
<center>
<table cellpadding="2" cellspacing="2">
<tr align="center">
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href=
"sec.htm">Security APIs</a> | <a href="aplist.htm">APIs by category</a></td>
</tr>
</table>
</center>
</body>
</html>