Sign Object (QYDOSGNO, QydoSignObject) 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 | Application identifier | Input | Char(*) |
| 5 | Length of application identifier | Input | Binary(4) |
| 6 | Replace duplicate signature | Input | Char(1) |
| 7 | Multiple objects characteristics | Input | Char(*) |
| 8 | Length of multiple objects characteristics | Input | Binary(4) |
| 9 | Error code | I/O | Char(*) |
Service Program Name: QYDOSGN1
Default Public Authority: *USE
Threadsafe: No
The Sign Object (OPM, QYDOSGNO; ILE, QydoSignObject) API allows the local system to certify that the object being signed is trustworthy as of the time the object is being signed.
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.
Authorities and Locks
- Authority Required
- For objects in a library:
- *OBJOPR and *OBJMGT authority to the object
- *OBJOPR and *EXECUTE authority to the library.
- *R and *OBJMGT authority to the object
- *X authority to each directory in the path
*R for the directory with wildcards (that is, a pattern is specified)
*RX authority to each subdirectory searched if the subdirectories parameter specifies 1.
To use this API, you must be authorized to the object signing applications function associated with your application identifier through System i™ 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.
See the open()--Open File API for the authority needed to the results path name. The file is open for append and is created if it does not already exist.
- Locks
- Object will be locked exclusive no read.
Required Parameter Group
- Object path name
- INPUT; CHAR(*)
The path name of the object you want to sign. 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' if you are using format OBJN0100 object path naming. Also if you are using format OBJN0100 object path naming, this parameter is assumed to be represented in the coded character set identifier (CCSID) currently in effect for the job. If the CCSID of the job is 65535, this parameter is assumed to be represented in the default CCSID of the job.
The path name may contain wildcard characters. '*' represents any number of unknown characters. '?' represents any single unknown character. For example, to specify all the program objects in library MYLIB, using format OBJN0100, you could specify '/QSYS.LIB/MYLIB.LIB/*.PGM'. If you want to sign all signable objects in a library or directory, specify the last part of the path name as simply '*'. For example to sign all signable objects in MYLIB, assuming you are using format OBJN0100, you could specify '/QSYS.LIB/MYLIB.LIB/*'.
If the object is in the QSYS file system, it must an object type *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.
- Application identifier
- INPUT; CHAR(*)
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. User-supplied application IDs should not preface their application ID with QIBM. User-supplied application IDs should start with the company name to eliminate most problems that involve unique names. Application IDs should use an underscore (_) to separate parts of the name (for example, QIBM_OS400_HOSTSERVER). Also, IDs for related applications should start with the same name (for example, QIBM_DIRSRV_SERVER and QIBM_DIRSRV_REPLICATION).
The following characters are allowed in an application ID. The first character of the application ID must be one of the following:
A-Z Uppercase A-Z The remaining characters in the application ID must be made up of the following characters:
A-Z Uppercase A-Z 0-9 Digits 0-9 . Period _ Underscore
- Length of application identifier
- INPUT; BINARY(4)
The length of the specified application identifier. This length must be a value from 1 to 30.
- Replace duplicate signature
- INPUT; CHAR(1)
Whether the old signature is left or replaced if a signature using the same certificate as the application identifier above uses is detected.
0 Leave the old signature and report an error. 1 Replace the old signature.
-
If the object contents have changed since the first time this certificate signed the object, the signature is replaced automatically. This parameter only affects signatures where the content has not changed.
- Multiple objects characteristics
- INPUT; CHAR(*)
How multiple objects specified on the object path name parameter are handled. See Multiple objects characteristics format for details on the format of this parameter. This field may be NULL if the length of multiple objects characteristics is 0.
- Length of multiple objects characteristics
- INPUT; BINARY(4)
The length of the specified multiple objects characteristics. This length may be 0 if you want to use the default values for all these characteristics or 1 or greater to indicate how many bytes of the characteristics should be used.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
Multiple objects characteristics format
The format of the multiple objects characteristics is shown in the following table. For detailed descriptions of the fields in the tables, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(1) | Subdirectories |
| 1 | 1 | CHAR(1) | Stop of first error |
| 2 | 2 | CHAR(1) | Sign only core part of object |
| 3 | 3 | CHAR(5) | Reserved |
| 8 | 8 | BINARY(4) | Offset to results file path name |
| 12 | 0C | BINARY(4) | Length of results file path name |
| 16 | 10 | CHAR(8) | Format of results file path name |
| 24 | 18 | CHAR(8) | Format of contents of the results file |
| CHAR(*) | Results file path name | ||
Field Descriptions
Format of content of the results file. The format of the content of the file containing the results of this call.
| RSLT0100 | The basic information is returned for each object specified by the object path name parameter. |
Format of results path name. The format of the results path name parameter.
| OBJN0100 | The results path name is a simple path name. |
| OBJN0200 | The results path name is an LG-type path name. |
Length of results path name. The length of the results path name. 0 length means no results files are used, and the results path name and format of results path name parameter values are not used. If the format of results path name is OBJN0200, this field must include the QLG path name structure in addition to the path name itself. If the format of results path name is OBJN0100, only the path name itself is included.
Offset to results path name. Offset from the beginning of this structure to the results path name.
Reserved. This field currently is not used. It is filled with binary zeroes.
Results path name. The path name of the object you want to contain the results on this call. This object may not be in a library (that is, it may not be under the /QSYS.LIB directory). The name may be relative to the current directory or may specify the entire path name. For example, to store results in a file called SIGNED.LST in the MYDIR directory, the results path name would be '/MYDIR/SIGNED.LST'. If you are using format OBJN0100, this parameter is assumed to be represented in the coded character set identifier (CCSID) currently in effect for the job. If the CCSID of the job is 65535, this parameter is assumed to be represented in the default CCSID of the job.
If this is an existing file, results are appended to the end of the file. Otherwise, a new file is created.
The default is not to have a results file.
Sign only core part of object. Whether the entire object be signed or not. This value only applies to objects that can have the core part of the object signed. Objects which cannot have only a core part of the object signed will sign the entire object, independent of the value specified here.
Currently, only *CMD objects can have a core part of the object signed.
| 0 | The entire object should be signed. This is the default value. |
| 1 | Only the core part of the object should be signed. |
A value of hex 00 will be treated as the default value for this field. This can happen when a program written in V5R1 (where this field was not defined) is run on V5R2.
Stop on first error. Whether control should be returned on the first error found.
| 0 | Continue processing objects even if some errors are found. |
| 1 | Stop on the first object that detects an error. This is the default value. |
Subdirectories. Whether objects in directories under the directory specified in the object path name parameter should be processed also.
| 0 | Process objects in the directory specified in the object path name parameter only. This is the default value. |
| 1 | Process objects in the directory specified in the object name path parameter and in all directories under that directory. |
RSLT0100 format
The following table describes the order and format of the data returned in the RSLT0100 format. This data is repeated for each object that was attempted to be processed. For detailed descriptions of the fields in the tables, see Field Descriptions.
Note:All data in this file will be in CCSID 13488. New files will be created in this CCSID. If an existing file is named that has a different CCSID, an error will be reported.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(7) | Message identifier |
| 7 | 7 | CHAR(9) | Reserved |
| 16 | 10 | CHAR(8) | Date |
| 24 | 18 | CHAR(8) | Reserved |
| 32 | 20 | CHAR(1) | Operation type |
| 33 | 21 | CHAR(15) | Operation type description |
| 48 | 30 | CHAR(8) | Reserved |
| 56 | 38 | CHAR(*) | Fully qualified object name |
Field Descriptions
Date. The date the operation took place. The format will be YYYYMMDD. For example, June 30, 2002 will be 20020630.
Fully qualified object name. The simple path name from the root to the object being signed. The field will be terminated with a new line character.
Message identifier. The error message used to report failure. This field is blank if no error was detected for this object.
Operation type. The operation that was attempted.
| 0 | Signing operation |
| 1 | Verifying operation |
Operation type description. Short word description of the operation that was attempted.
Reserved. This field currently is not used. It is filled with blanks.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF9803 E | Cannot allocate object &2 in library &3. |
| CPFA085 E | Home directory not found for user &1. |
| CPFA086 E | Matching quote not found in path name. |
| CPFA087 E | Path name contains null character. |
| CPFA088 E | Path name pattern not valid. |
| CPFA089 E | Pattern not allowed in path name. |
| CPFA08B E | Path name cannot begin with *. |
| CPFA08C E | Pattern not allowed in path name directory. |
| CPFA08D E | Request information value is not valid. |
| CPFA08E E | More than one name matches pattern. |
| CPFA091 E | Pattern not allowed in user name. |
| CPFA092 E | Path name not converted. |
| CPFA094 E | Path name not specified. |
| CPFA09C E | Not authorized to object. |
| CPFA0A4 E | Too many open files for process. |
| CPFA0AA E | Error occurred while attempting to obtain space. |
| CPFA0D4 E | File system error occurred. |
| CPFB720 E | No signable object was found. |
| CPFB721 E | Object supports signing, but *TGTRLS prevents signing. |
| CPFB724 E | Option &2 of the operating system is required to work with object signatures. |
| CPFB72B E | Object not found. |
| CPFB72C E | The object cannot currently be signed or verified. |
| CPFB72E E | The parameter for replace duplicate signature is not valid. |
| CPFB731 E | Sign object certificate database does not exist. |
| 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. |
| CPFB73A E | The password for the certificate key database needs to be set. |
| CPFB73F E | The signing application certificate is expired. |
| 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 an invalid value. |
| CPFB743 E | The value for stopping on the first error is not valid. |
| CPFB744 E | The format of the results file for the digital signing API is an incorrect value. |
| 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. |
| CPFB747 E | Object is in a state which is not eligible to be signed. |
| CPFB748 E | Object signed by IBM, not eligible to be signed. |
| CPFB749 E | Object signature operation ended abnormally. &3 objects attempted, &2 objects successfully processed. |
| CPFB74A E | The application identifier on the digital signing API is not in a valid state. |
| CPFB74C E | Object contains no data to sign (it is empty). |
| CPFB74D E | Results file could not be used. |
| CPFBC50 E | No path names match input path names. |
API introduced: V5R1
[ Back to top | Security APIs | APIs by category ]