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

712 lines
19 KiB
HTML
Raw Permalink Normal View History

Add readme and dist folders
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">
<title>Retrieve Object Signatures (QYDORTVO, QydoRetrieveDigitalSignatures)
API</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. -->
<!--File Edited April 2001 -->
<!-- QYDORTVO SCR A converted by B2H R4.1 (346) (CMS) by V2CDIJAB at -->
<!-- RCHVMW2 on 17 Oct 2000 at 12:54:16 -->
<!-- End Header Records -->
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
</head>
<body>
<!-- Java sync-link -->
<script language="Javascript" src="../rzahg/synch.js" type="text/javascript">
</script>
<a name="Top_Of_Page"></a>
<h2>Retrieve Object Signatures (QYDORTVO, QydoRetrieveDigitalSignatures)API</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%">Object path name</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">Length of object path name</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">3</td>
<td align="left" valign="top">Format of object path name</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(8)</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="left" valign="top">Receiver</td>
<td align="left" valign="top">Output</td>
<td align="left" valign="top">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">5</td>
<td align="left" valign="top">Length of receiver variable</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">Format of receiver variable</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(8)</td>
</tr>
<tr>
<td align="center" valign="top">7</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: QYDORTV1<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 Retrieve Object Signatures (OPM, QYDORTVO; ILE,
QydoRetrieveDigitalSignatures) API retrieves certificate information from a
signed iSeries object.</p>
<br>
<h3>Authorities and Locks</h3>
<dl>
<dt><strong>Authority Required</strong></dt>
<dd>For objects in a library:
<ul>
<li>*READ authority to the object</li>
<li>*OBJOPR and *EXECUTE authority to the library.</li>
</ul>
For objects in a directory:
<ul>
<li>*R authority to the object</li>
<li>*X authority to each directory in the path.</li>
</ul>
</dd>
<dt><strong>Locks</strong></dt>
<dd>Object will be locked shared allow read.</dd>
</dl>
<br>
<h3>Required Parameter Group</h3>
<dl>
<dt><strong>Object path name</strong></dt>
<dd>INPUT; CHAR(*)</dd>
<dd>
<p>The name of the object from which you want to retrieve signatures. If the
object is not in a library, the name may be relative to the current directory
or may specify the entire path name. If the object is in a library, the name
must be in the form '/QSYS.LIB/libname.LIB/objname.objtype' if you are using
format OBJN0100 object path naming. For example, to sign a program named
NEWEMPL in library PAYROLL, the qualified object name would be
'/QSYS.LIB/PAYROLL.LIB/NEWEMPL.PGM'. Also, this parameter is assumed to be
represented in the coded character set identifier (CCSID) currently in effect
for the job if you are using format OBJN0100 object path naming. If the CCSID
of the job is 65535, this parameter is assumed to be represented in the default
CCSID of the job.</p>
<p>If the object is in the QSYS file system, the object type must be *PGM,
*SRVPGM, *MODULE, *SQLPKG, *FILE (save file), or *CMD.</p>
</dd>
<dt><strong>Length of object path name</strong></dt>
<dd>INPUT; BINARY(4)</dd>
<dd>
<p>The length of the object path name. If the format of object path name is
OBJN0200, this field must include the QLG path name structure in addition to
the path name itself. If the format of object path name is OBJN0100, only the
path name itself is included.</p>
</dd>
<dt><strong>Format of object path name</strong></dt>
<dd>INPUT; CHAR(8)</dd>
<dd>
<p>The format of the object path name parameter</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>OBJN0100</em></td>
<td align="left" valign="top">The object path name is a simple path name.</td>
</tr>
<tr>
<td align="left" valign="top"><em>OBJN0200</em></td>
<td align="left" valign="top">The object path name is an LG-type path
name.</td>
</tr>
</table>
<br>
<br>
</dd>
<dt><strong>Receiver</strong></dt>
<dd>OUTPUT; CHAR(*)</dd>
<dd>
<p>The structure that returns one or more blocks of certificate information
from a digitally signed object.</p>
</dd>
<dt><strong>Length of receiver</strong></dt>
<dd>INPUT; BINARY(4)</dd>
<dd>
<p>Size (in bytes) of the receiver available for signatures to be returned.</p>
</dd>
<dt><strong>Format of receiver</strong></dt>
<dd>INPUT; CHAR(8)</dd>
<dd>
<p>The format of certificate fields returned in the receiver.</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>CERT0200</em></td>
<td align="left" valign="top">All certificate text fields are translated from
the ASCII format into the job CCSID.</td>
</tr>
<tr>
<td align="left" valign="top"><em>CERT0210</em></td>
<td align="left" valign="top">All certificate fields are returned in the
original certificate ASCII format.</td>
</tr>
</table>
<br>
<br>
</dd>
<dt><strong>Error code</strong></dt>
<dd>I/O; CHAR(*)</dd>
<dd>
<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>Receiver Structure</h3>
<p>The receiver structure is comprised of:</p>
<ol>
<li>A header section</li>
<li>An array of subheader sections called signature sections</li>
<li>For each subheader section, a Certificate Format CERT0200 (or CERT0210) as
documented in the Parse Certificate (QSYPARSEC, QsyParserCertificate) API.</li>
</ol>
<br>
<h3>Header</h3>
<h3>Receiver Header area</h3>
<p>For a description of the fields, see <a href="#offset_field_descrip">Field
Descriptions.</a></p>
<table border width="100%">
<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%">Bytes_Returned</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">Bytes_Available</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_Sections</td>
</tr>
<tr>
<td align="center" valign="top">12</td>
<td align="center" valign="top">12</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Length_Of_Section</td>
</tr>
<tr>
<td align="center" valign="top">16</td>
<td align="center" valign="top">10</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Number_Of_Sections</td>
</tr>
<tr>
<td align="center" valign="top">20</td>
<td align="center" valign="top">14</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Number_Signatures_Returned</td>
</tr>
<tr>
<td align="center" valign="top">24</td>
<td align="center" valign="top">18</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Number_Signatures_Available</td>
</tr>
<tr>
<td align="center" valign="top">28</td>
<td align="center" valign="top">1C</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Composite_Object</td>
</tr>
<tr>
<td align="center" valign="top">32</td>
<td align="center" valign="top">20</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Version</td>
</tr>
<tr>
<td align="center" valign="top">36</td>
<td align="center" valign="top">24</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">IBM_Signed</td>
</tr>
<tr>
<td align="center" valign="top">40</td>
<td align="center" valign="top">28</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Core Signed</td>
</tr>
<tr>
<td align="center" valign="top">41</td>
<td align="center" valign="top">29</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Entire Signed</td>
</tr>
<tr>
<td align="center" valign="top">42</td>
<td align="center" valign="top">30</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Compressed Signature Exists</td>
</tr>
<tr>
<td align="center" valign="top">43</td>
<td align="center" valign="top">31</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Decompressed Signature Exists</td>
</tr>
<tr>
<td align="center" valign="top">44</td>
<td align="center" valign="top">2C</td>
<td align="left" valign="top">CHAR(24)</td>
<td align="left" valign="top">Reserved for future use</td>
</tr>
</table>
<br>
<br>
<h3><a name="offset_field_descrip">Field Descriptions</a></h3>
<p><strong>Bytes_Returned.</strong> Number of bytes returned by the API into
the receiver.</p>
<p><strong>Bytes_Available.</strong> Number of bytes available from the API</p>
<p><strong>Offset_To_Sections.</strong> Offset from beginning of struct to the
first signature section</p>
<p><strong>Length_Of_Section.</strong> Length of an individual signature
section</p>
<p><strong>Number_Of_Sections.</strong> The number of signature sections in the
array of signature sections</p>
<p><strong>Number_Signatures_Returned.</strong> How many signatures were
returned</p>
<p><strong>Number_Signatures_Available.</strong> How many signatures were
available</p>
<p><strong>Composite_Object.</strong> Composite object indicator. 0 if not
composite; nonzero if composite.</p>
<p><strong>Version.</strong> V5R1 value is zero.&nbsp; V5R2 value of 1 added to
indicate added fields.</p>
<p><strong>IBM_Signed.</strong> Whether IBM i5/OS signed. 1 if IBM i5/OS
signed.</p>
<p><strong>Core Signed.</strong>
If Version is 0, Reserved.<br>
"Core" is applicable to *CMD objects only.<br>
'1' if there is a "Core" signature for some certificate. '0' if there is no
"Core" signature on the object.</p>
<p><strong>Entire Signed.</strong> If Version is 0, Reserved.<br>
'1' if there is an "Entire" signature for some certificate. '0' if there is no
"Entire" signature on the object.</p>
<p><strong>Compressed Signature Exists.</strong> If Version is 0, Reserved.<br>
'1' indicates the object has a digital signature for the compressed object for
some certificate. '0' indicates the object has no digital signature for the
compressed object.</p>
<p><strong>Decompressed Signature Exists.</strong> If Version is 0,
Reserved.<br>
'1' indicates the object has a digital signature for the decompressed object
for some certificate. '0' indicates the object has a digital signature for the
decompressed object.</p>
<br>
<h3>Signature Section</h3>
<p>For a description of the fields, see <a href="#sign_field_descript">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_Cert_Info</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_Cert_Info</td>
</tr>
<tr>
<td align="center" valign="top">8</td>
<td align="center" valign="top">8</td>
<td align="left" valign="top">CHAR(8)</td>
<td align="left" valign="top">Certificate_Format</td>
</tr>
<tr>
<td align="center" valign="top">16</td>
<td align="center" valign="top">10</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Reserved1</td>
</tr>
<tr>
<td align="center" valign="top">17</td>
<td align="center" valign="top">11</td>
<td align="left" valign="top">CHAR(7)</td>
<td align="left" valign="top">Parse_Msg_ID</td>
</tr>
<tr>
<td align="center" valign="top">24</td>
<td align="center" valign="top">18</td>
<td align="left" valign="top">CHAR(14)</td>
<td align="left" valign="top">Date_Signed</td>
</tr>
<tr>
<td align="center" valign="top">38</td>
<td align="center" valign="top">26</td>
<td align="left" valign="top">CHAR</td>
<td align="left" valign="top">Signature_Scope</td>
</tr>
<tr>
<td align="center" valign="top">39</td>
<td align="center" valign="top">27</td>
<td align="left" valign="top">CHAR</td>
<td align="left" valign="top">Compressed_Signature;</td>
</tr>
<tr>
<td align="center" valign="top">40</td>
<td align="center" valign="top">28</td>
<td align="left" valign="top">CHAR</td>
<td align="left" valign="top">Decompressed_Signature;</td>
</tr>
<tr>
<td align="center" valign="top">41</td>
<td align="center" valign="top">29</td>
<td align="left" valign="top">CHAR(23)</td>
<td align="left" valign="top">Reserved2</td>
</tr>
</table>
<br>
<br>
<h3><a name="#sign_field_descript">Field Descriptions</a></h3>
<p><strong>Offset_Cert_Info.</strong> Offset from beginning of receiver to the
certificate information</p>
<p><strong>Length_Cert_Info.</strong> Length of the certificate information</p>
<p><strong>Certificate_Format.</strong> Format of the parsed certificate.
Format is CERT0210 or CERT0200 per input request or CERT0000 if not parsed.</p>
<p><strong>Reserved1.</strong> Reserved byte</p>
<p><strong>Parse_Msg_ID.</strong> Message result, if any, from parsing the
certificate</p>
<p><strong>Date_Signed.</strong> YYYYMMDDhhmmss format where YYYY represents
the year, MM the month, hh the hour, mm the minutes, and ss the seconds.</p>
<p><strong>Signature_Scope.</strong> If Version is 0,
Reserved.<br>
'E' if there is an "Entire" signature for some certificate. 'C' if there is a
"Core" signature on the object.</p>
<p><strong>Compressed_Signature;.</strong> If Version is 0, Reserved.<br>
'1' indicates the object has a digital signature for the compressed object for
this certificate. '0' indicates the object has no digital signature for the
compressed object for this certificate.</p>
<p><strong>Decompressed_Signature;.</strong> If Version is 0, Reserved.<br>
'1' indicates the object has a digital signature for the decompressed object
for this certificate. '0' indicates the object has no digital signature for the
decompressed object for this certificate.</p>
<p><strong>Reserved2.</strong> RESERVED bytes</p>
<br>
<h3>Certificate Format CERT0200 (or CERT0210)</h3>
<p>Each subheader section provides a receiver-start relative offset to a
certificate format CERT0200 (or CERT0210) as documented in the Parse
Certificate (QSYPARSEC, QsyParserCertificate) API.</p>
<p>The certificate format has offsets relative to a beginning offset of its own
structure under the heading "Certificate Format CERT0200 (Plain Text)" in the
API for Parse Certificate. These are retained in the API. These structure
offsets are thus displacements relative to the certificate format beginning
within the receiver.</p>
<p>If a message is issued when using the interface to parse the certificate,
the message ID will be copied into the signature section (the subheader) field
Parse_Msg_ID.</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 align="left" width="15%">CPFA0A9 E</td>
<td align="left" width="85%">Object not found.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB720 E</td>
<td align="left" valign="top">Object type does not support signing.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB722 E</td>
<td align="left" valign="top">Object not signed.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB724 E</td>
<td align="left" valign="top">Option &amp;2 of the operating system is required to work with object signatures.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB735 E</td>
<td align="left" valign="top">The digital signing API parameter &amp;1 is not
large enough.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB736 E</td>
<td align="left" valign="top">The digital signing API parameter &amp;1 is not
small enough.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB737 E</td>
<td align="left" valign="top">The digital signing API parameter &amp;1 is a
null pointer.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB738 E</td>
<td align="left" valign="top">The digital signing API parameter &amp;1 is not a
valid format type.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB739 E</td>
<td align="left" valign="top">The digital signing API parameter &amp;1 is out
of range.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB740 E</td>
<td align="left" valign="top">The format name for the pathname is not
valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB741 E</td>
<td align="left" valign="top">The length of the path name parameter is not
valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB742 E</td>
<td align="left" valign="top">The subdirectory option is not a valid
value.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB743 E</td>
<td align="left" valign="top">The value for stopping on the first error is
not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB745 E</td>
<td align="left" valign="top">The format name for the results file path name is
not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB746 E</td>
<td align="left" valign="top">The results file path name length is not large
enough.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB749 E</td>
<td align="left" valign="top">Object signature operation ended abnormally.
&amp;3 objects attempted, &amp;2 objects successfully processed.</td>
</tr>
</table>
<br>
<hr>
API introduced: V5R1
<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>
Reference in New Issue Copy Permalink