Retrieve Object Signatures (QYDORTVO, QydoRetrieveDigitalSignatures)API
Required Parameter Group:
| 1 | Object path name | Input | Char(*) |
| 2 | Length of object path name | Input | Binary(4) |
| 3 | Format of object path name | Input | Char(8) |
| 4 | Receiver | Output | Char(*) |
| 5 | Length of receiver variable | Input | Binary(4) |
| 6 | Format of receiver variable | Input | Char(8) |
| 7 | Error code | I/O | Char(*) |
Service Program Name: QYDORTV1
Default Public Authority: *USE
Threadsafe: No
The Retrieve Object Signatures (OPM, QYDORTVO; ILE, QydoRetrieveDigitalSignatures) API retrieves certificate information from a signed IBM® i object.
Authorities and Locks
- Authority Required
- For objects in a library:
- *READ authority to the object
- *OBJOPR and *EXECUTE authority to the library.
- *R authority to the object
- *X authority to each directory in the path.
- Locks
- Object will be locked shared allow read.
Required Parameter Group
- Object path name
- INPUT; CHAR(*)
-
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.
If the object is in the QSYS file system, the object type must be *PGM, *SRVPGM, *MODULE, *SQLPKG, *FILE (save file), or *CMD.
- Length of object path name
- INPUT; BINARY(4)
-
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.
- Format of object path name
- INPUT; CHAR(8)
-
The format of the object path name parameter
OBJN0100 The object path name is a simple path name. OBJN0200 The object path name is an LG-type path name.
- Receiver
- OUTPUT; CHAR(*)
-
The structure that returns one or more blocks of certificate information from a digitally signed object.
- Length of receiver
- INPUT; BINARY(4)
-
Size (in bytes) of the receiver available for signatures to be returned.
- Format of receiver
- INPUT; CHAR(8)
-
The format of certificate fields returned in the receiver.
CERT0200 All certificate text fields are translated from the ASCII format into the job CCSID. CERT0210 All certificate fields are returned in the original certificate ASCII format.
- Error code
- I/O; CHAR(*)
-
The structure in which to return error information. For the format of the structure, see Error code parameter.
Receiver Structure
The receiver structure is comprised of:
- A header section
- An array of subheader sections called signature sections
- For each subheader section, a Certificate Format CERT0200 (or CERT0210) as documented in the Parse Certificate (QSYPARSEC, QsyParserCertificate) API.
Header
Receiver Header area
For a description of the fields, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes_Returned |
| 4 | 4 | BINARY(4) | Bytes_Available |
| 8 | 8 | BINARY(4) | Offset_To_Sections |
| 12 | 12 | BINARY(4) | Length_Of_Section |
| 16 | 10 | BINARY(4) | Number_Of_Sections |
| 20 | 14 | BINARY(4) | Number_Signatures_Returned |
| 24 | 18 | BINARY(4) | Number_Signatures_Available |
| 28 | 1C | BINARY(4) | Composite_Object |
| 32 | 20 | BINARY(4) | Version |
| 36 | 24 | BINARY(4) | IBM_Signed |
| 40 | 28 | CHAR(1) | Core Signed |
| 41 | 29 | CHAR(1) | Entire Signed |
| 42 | 30 | CHAR(1) | Compressed Signature Exists |
| 43 | 31 | CHAR(1) | Decompressed Signature Exists |
| 44 | 2C | CHAR(24) | Reserved for future use |
Field Descriptions
Bytes_Returned. Number of bytes returned by the API into the receiver.
Bytes_Available. Number of bytes available from the API
Offset_To_Sections. Offset from beginning of struct to the first signature section
Length_Of_Section. Length of an individual signature section
Number_Of_Sections. The number of signature sections in the array of signature sections
Number_Signatures_Returned. How many signatures were returned
Number_Signatures_Available. How many signatures were available
Composite_Object. Composite object indicator. 0 if not composite; nonzero if composite.
Version. V5R1 value is zero. V5R2 value of 1 added to indicate added fields.
IBM_Signed. Whether IBM® i signed. 1 if IBM i signed.
Core Signed.
If Version is 0, Reserved.
"Core" is applicable to *CMD objects only.
'1' if there is a "Core" signature for some certificate. '0' if there is no
"Core" signature on the object.
Entire Signed. If Version is 0, Reserved.
'1' if there is an "Entire" signature for some certificate. '0' if there is no
"Entire" signature on the object.
Compressed Signature Exists. If Version is 0, Reserved.
'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.
Decompressed Signature Exists. If Version is 0,
Reserved.
'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.
Signature Section
For a description of the fields, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Offset_Cert_Info |
| 4 | 4 | BINARY(4) | Length_Cert_Info |
| 8 | 8 | CHAR(8) | Certificate_Format |
| 16 | 10 | CHAR(1) | Reserved1 |
| 17 | 11 | CHAR(7) | Parse_Msg_ID |
| 24 | 18 | CHAR(14) | Date_Signed |
| 38 | 26 | CHAR | Signature_Scope |
| 39 | 27 | CHAR | Compressed_Signature; |
| 40 | 28 | CHAR | Decompressed_Signature; |
| 41 | 29 | CHAR(23) | Reserved2 |
Field Descriptions
Offset_Cert_Info. Offset from beginning of receiver to the certificate information
Length_Cert_Info. Length of the certificate information
Certificate_Format. Format of the parsed certificate. Format is CERT0210 or CERT0200 per input request or CERT0000 if not parsed.
Reserved1. Reserved byte
Parse_Msg_ID. Message result, if any, from parsing the certificate
Date_Signed. YYYYMMDDhhmmss format where YYYY represents the year, MM the month, hh the hour, mm the minutes, and ss the seconds.
Signature_Scope. If Version is 0,
Reserved.
'E' if there is an "Entire" signature for some certificate. 'C' if there is a
"Core" signature on the object.
Compressed_Signature;. If Version is 0, Reserved.
'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.
Decompressed_Signature;. If Version is 0, Reserved.
'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.
Reserved2. RESERVED bytes
Certificate Format CERT0200 (or CERT0210)
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.
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.
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.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPFA0A9 E | Object not found. |
| CPFB720 E | Object type does not support signing. |
| CPFB722 E | Object not signed. |
| CPFB724 E | Option &2 of the operating system is required to work with object signatures. |
| CPFB735 E | The digital signing API parameter &1 is not large enough. |
| CPFB736 E | The digital signing API parameter &1 is not small enough. |
| CPFB737 E | The digital signing API parameter &1 is a null pointer. |
| CPFB738 E | The digital signing API parameter &1 is not a valid format type. |
| CPFB739 E | The digital signing API parameter &1 is out of range. |
| CPFB740 E | The format name for the pathname is not valid. |
| CPFB741 E | The length of the path name parameter is not valid. |
| CPFB742 E | The subdirectory option is not a valid value. |
| CPFB743 E | The value for stopping on the first error is not valid. |
| CPFB745 E | The format name for the results file path name is not valid. |
| CPFB746 E | The results file path name length is not large enough. |
| CPFB749 E | Object signature operation ended abnormally. &3 objects attempted, &2 objects successfully processed. |
API introduced: V5R1
[ Back to top | Security APIs | APIs by category ]