Retrieve Object Signatures (QYDORTVO, QydoRetrieveDigitalSignatures)API

The Retrieve Object Signatures (OPM, QYDORTVO; ILE, QydoRetrieveDigitalSignatures) API retrieves certificate information from a signed iSeries object.

Authorities and Locks

Authority Required

For objects in a library:

• *READ authority to the object
• *OBJOPR and *EXECUTE authority to the library.

For objects in a directory:

• *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:

1. A header section
2. An array of subheader sections called signature sections
3. 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.

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 i5/OS signed. 1 if IBM i5/OS 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.

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