IEWSIGN: Sign, unsign, and report load modules

IEWSIGN, the signing utility on z/OS, provides the following functions:

Sign a load module in a partitioned data set (PDS). The utility adds a signature to the load module and marks it as signed.
Unsign a load module in a PDS. The utility removes the signature from the load module and marks it as un-signed.
Report on a load module in a PDS. The utility reports signing-related information, such as the time the load module was signed, the signing algorithm, and the certificate fingerprint.

IEWSIGN must be invoked by either JCL that uses EXEC PGM=xxx, call, or LINK.

It resides in SYS1.SIEAMIGE.

Usage notes

The following list contains usage notes for the signed load module:

To copy a signed load module from one PDS to another PDS, IEBCOPY with the control statement COPY should be used. Do not use IEBCOPY with the control statement COPYMOD, which causes the signature in the destination load module to become invalid. Do not use the z/OS UNIX command cp, which causes the destination load module to become unsigned.
Copying a signed load module from a PDS to a PDSE causes the destination program to become unsigned.
Relinking a signed load module causes the resultant program to become unsigned.
Reprocessing a signed load module with the binder API SAVEW causes the resultant program to become unsigned.
Renaming a signed load module causes its signature to become invalid.

Parameters of IEWSIGN

Parameters of IEWSIGN have the following rules:

For JCL, parameters can be provided by PARM=’..’ or by PARMDD=xx with the data within the xx DD.
For call or LINK, parameters consist of a halfword length followed by the parameter string, as the first parameter pointed to by the parameter list located by the PARAM keyword (and thus located by register 1 on entry to the target routine).
Parameters are of the form keyword=value, separated from one another by a single comma.
Parameters can be in any order.
Optional parameters need not be provided.

The following table lists the parameters of IEWSIGN along with their descriptions:

Table 1. Parameters of IEWSIGN
Parameter name	Description
Action	Specifies the action to be run. There is no default value. It must be specified explicitly. Its eligible values are as follows: Sign Unsign Report
State	For Action=Sign and Action=Report, it determines which name-matched members will be processed. For Action=Unsign, this parameter is ignored, since only signed load modules are processed. Its eligible values are as follows: Unsigned Only unsigned name-matched members will be processed. Signed Only signed name-matched members will be processed. All All name-matched members will be processed. This is the default value. When Action=Sign and State is Signed or All, existing signed modules will be re-signed.
RC4LIM/ RC8LIM	This integer specifies the limits for return code 4 / return code 8. Valid range is from 1 to 2147483647. If any limit is reached, this utility will terminate. The default value of RC4LIM is 2147483647. The default value of RC8LIM is 1 for ACTION=SIGN and ACTION=UNSIGN, and 2147483647 for ACTION=REPORT. This utility will terminate immediately if a return code 12 or higher occurs.
Verbose	Specifies the content that is provided in SYSPRINT. Yes Specifying this option provides more detailed content. No Specifying this option provides less detailed content. .
ReportLevel	Specifies the level of checking/printed information when ACTION=REPORT. 1 Only check whether a load module is signed. This is the default value. 2 Includes all reports for ReportLevel=1, and the text size, link time, signing time, binder version, hash algorithm, signing algorithm, certificate fingerprint. 3 Includes all reports for ReportLevel=2, and whether the hash in signature is valid.

The utility’s processing of all parameters is not case-sensitive.

Parameters in the PARM string are separated by commas.

Data definitions (DD) of IEWSIGN

The following table lists the IEWSIGN data definitions and their descriptions:

Table 2. IEWSIGN data definitions
DD name	Description
SYSPRINT	This is a required DD. It is valid for all Action values. This data set contains the IEWSIGN processing messages or reports. The specification for the data set is as follows: `//SYSPRINT DD SYSOUT=*` If DCB attributes are expected, the following recommendation is provided: `LRECL RECFM 121 FBA`
INFILE	This is a required DD. It is valid for all Action values. This DD specifies the source PDS library where load modules are read from. Concatenation of multiple data sets is not allowed. IEWSIGN will fail if the data set is not a PDS.
OUTFILE	When Action=Sign or Action=Unsign, this DD is required. When Action=Report, this DD is not required. This DD specifies the destination PDS library where load modules are written to. Concatenation of multiple data sets is not allowed. The signing utility will fail if the data set is not a PDS. In-place signing is supported by specifying the same DSN in the INFILE and OUTFILE. If the blocksize of OUTFILE is not 0, it must be equal to or larger than the blocksize of INFILE. Additionally, it must be equal to or larger than 1024. The maximum value can be 32760. If the blocksize of OUTFILE is 0, the IEWSIGN utility will set it to the blocksize of the INFILE data set.
INCLUDE	This is an optional DD. It is valid for all Action values. This DD specifies members to be included from INFILE. If this DD is unspecified, all members in INFILE will be included. The standard specification for this data set is as follows: `//INCLUDE DD *` If a regular data set is provided, it needs to be RECFM=FB and LRECL=80.
EXCLUDE	This is an optional DD. It is valid for all Action values. This DD specifies members to be excluded from INFILE. If this DD is unspecified, no members in INFILE will be excluded. The standard specification for this data set is as follows: `//EXCLUDE DD *` If a regular data set is provided, it needs to be RECFM=FB and LRECL=80.

Both INFILE and OUTFILE must be a PDS whose record format is U. In addition, the IEWSIGN utility will not process a member in INFILE if any of the following are true:

It is not a load module.
It is a load module with an overlay attribute.
It is a load module without TEXT.

Rules for INCLUDE and EXCLUDE

Both INCLUDE and EXCLUDE specify one or multiple names, which are used to match primary members and aliases in INFILE. The following rules apply:

A name must obey PDS member naming rules.
Multiple names are not allowed on a single line.
A name must not be continued to the next line.
Blank characters are allowed before and after a name.
Comments are supported with the following conditions:
- A line will be treated as a comment if the first nonblank character is “#”.
- A blank line, where all characters are space (its hex value is 0x40), is acceptable.
Wildcards are supported. Both “*” and “?” can be used in a name. . “*” matches “0 or more characters” and “?” matches “exactly one character”. The following are some examples:
- *
- ABC*
- ABC??DEF
- X*YYY
Only the first 72 characters in a line are parsed.

IEWSIGN uses the following steps to determine which members should be processed (for example, signed, unsigned or reported).

Table 3. Steps for IEWSIGN member processing
Step number	Step instructions
Step 1	Retrieve a list of names of all primary members of INFILE whose signing state is the one required by parameter STATE.
Step 2	If INCLUDE is not specified, skip this step. If INCLUDE is specified, remove a primary member from this list if both of the following are true: The name of the primary member does not match any name specified in INCLUDE, and None of its alias names matches any name specified in INCLUDE.
Step 3	If EXCLUDE is not specified, skip this step. If EXCLUDE is specified, remove a primary member from this list if either of the following are true: The name of the primary member matches any name specified in EXCLUDE, or One of its alias names matches any name specified in EXCLUDE.
Step 4	All primary members remaining in the list are processed.

Note: For Action=Sign, when a primary member is being signed, in addition to adding load module signing records, IEWSIGN will update the directory entries of the primary member and all its aliases. Therefore, when a primary member becomes signed, all its aliases also become signed. For Action=Unsign, analogous processing is performed.

A detailed example of INCLUDE/EXCLUDE is provided in next section as Example 1.

Examples

The following provides an example of INCLUDE/EXCLUDE processing. The conditions for this example are as such:
- A PDS has 4 primary members: M1, M2, M3 and M4.
  - M1 has one alias A11;
  - M2 has two aliases A21 and A22;
  - M3 and M4 have no alias.
  - M1, M2 and M3 are unsigned.
  - M4 is signed.
- IEWSIGN is called with parameter Action=Sign,State=Unsigned.
- INCLUDE has two lines
```
M1
A21
```
- EXCLUDE has one line:
```
A11
```
Results of the processing are as follows:

Step 1 results

IEWSIGN receives a name list of all unsigned primary members of INFILE. At the end of step 1, M1, M2, M3 are in the list.

Step 2 results

M1 is kept, as its name matches a filter specified at the first line of INCLUDE. M2 is kept, as its alias A21 matches a filter specified on the second line of INCLUDE. M3 is removed, as it and all its aliases don’t match any filters in INCLUDE. At the end of step 2, M1,M2 are in the list.

Step 3 results

M1 is removed, as its alias A11 matches a filter specified at the first line of EXCLUDE. M2 is kept, as it and all its aliases do not match any filters in EXCLUDE. At the end of step 3, M2 is in the list.

Step 4 results

IEWSIGN begins to sign M2. In this step, a signature is added to the load module records of M2. In addition, the directory entries of M2, A21 and A22 are all updated together. Therefore, M2, A21 and A22 all become signed.
The following is a JCL example that signs all load modules in place. In this example, both INFILE and OUTFILE use the same DSN. As a result, signed modules will be saved into its original PDS.
```
//SIGN EXEC PGM=IEWSIGN,PARM='Action=Sign'
//STEPLIB  DD DISP=SHR,DSN=SYS1.SIEAMIGE
//SYSPRINT DD SYSOUT=*
//INFILE   DD DSN=SYS1.LPALIB,DISP=SHR
//OUTFILE  DD DSN=SYS1.LPALIB,DISP=SHR
```
Note: In-place signing requires the OUTFILE data set to have room for both the original modules and for the updated versions of those modules, since the storage space of the original modules cannot be reused during the processing.

The following is a JCL example that signs all unsigned load modules specified by INCLUDE/EXCLUDE:


//SIGN EXEC PGM=IEWSIGN,PARM='Action=Sign,State=Unsigned'
//STEPLIB  DD DISP=SHR,DSN=SYS1.SIEAMIGE
//SYSPRINT DD SYSOUT=*
//INFILE    DD DSN=SYS1.LINKLIB,DISP=SHR
//OUTFILE   DD DSN=SYS1.SIGN.LIB,DISP=(NEW,PASS),DSNTYPE=PDS,
//             SPACE=(CYL,(500,500,5)),UNIT=3390
//INCLUDE   DD *
# this is a comment line
AMBLIST
IEHMVE*
//EXCLUDE    DD *
IEHMVE2

For example, if INFILE has the following six unsigned members: AMBLIST, AMBLIST2, IEHMVE1, IEHMVE2, IEHMVE3, IEHMVE4, then the matched members are as follows: AMBLIST, IEHMVE1, IEHMVE3, IEHMVE4.

The following is a JCL example that unsigns all signed load modules in-place:

//UNSIGN EXEC PGM=IEWSIGN,PARM='Action=Unsign'
//STEPLIB  DD DISP=SHR,DSN=SYS1.SIEAMIGE
//SYSPRINT DD SYSOUT=*
//INFILE    DD DSN=SYS1.LINKLIB,DISP=SHR
//OUTFILE   DD DSN=SYS1.LINKLIB,DISP=SHR

The following is a JCL example that reports all load modules:

//REPORT EXEC PGM=IEWSIGN,PARM='Action=Report’
//STEPLIB  DD DISP=SHR,DSN=SYS1.SIEAMIGE
//SYSPRINT DD SYSOUT=*
//INFILE   DD DSN=SYS1.LINKLIB,DISP=SHR

The following is a JCL example that reports load modules specified by INCLUDE or EXCLUDE:

//REPORT EXEC PGM=IEWSIGN,PARM='Action=Report,Verbose=YES'
//STEPLIB  DD DISP=SHR,DSN=SYS1.SIEAMIGE
//SYSPRINT DD SYSOUT=*
//INFILE   DD DSN=SYS1.LINKLIB,DISP=SHR
//INCLUDE    DD *
AMBLIST
IEHMVE*
//EXCLUDE    DD *
IEHMVE2

The following two examples show the use of SYSPRINT with Action=Sign. To better understand these examples, know that the contents of SYSPRINT consists of two parts:

A selection part, which indicates which members will be selected by INCLUDE or EXCLUDE from INFILE. This part is the same for all ACTION values.

A processing part, which displays the results of actions such as signing, unsigning, and reporting. This part is different for each ACTION value.

The following is an example of the selection part for Action=Sign:

Note: In the selection part of the example, report lines in italic type are printed only when Verbose=Yes. (in the example, the italicized section starts with the line

Member/Alias(es) in INFILE with
STATE=UNSIGNED

and goes to the end of the example)

Invocation parameters: ACTION=SIGN,STATE=UNSIGNED,VERBOSE=YES
Execution  Parameters: ACTION=SIGN,STATE=UNSIGNED,VERBOSE=YES,RC4LIM=2147483647,RC8LIM=1,REPORTLEVEL=1

DD        Data Set Name                               Volume        Block Size
INFILE    SYS1.LPALIB                                 BPX111        32760
OUTFILE   SYS1.LPALIB                                 BPX222        32760

INFILE summary:                                                                                         
          Unsigned primary members      1                                                               
          Unsigned aliases              2                                                                
          Signed   primary members      0                                                               
          Signed   aliases              0                                                                
          Non-LM   members              1                                                               
          Overlay       LM              0                                                               
          Zero-TEXT     LM              0   
 
Member/Alias(es) in INFILE with STATE=UNSIGNED
Member      Alias(es)
ASM         AL1      AL2

Including members specified in INCLUDE ...
<NONE>
 
Member/Alias(es) selected after INCLUDing
Member      Alias(es)
ASM         AL1      AL2

Excluding members specified in EXCLUDE ...
<NONE>
 
Member/Alias(es) selected after EXCLUDing
Member      Alias(es)
ASM         AL1      AL2

Each line in SYSPRINT is one of the two types:

Report line: This line has no message ID. The text is provided for informational purposes.
Message line: This line has a message ID. These lines are only for warning and error messages. These messages are documented in z/OS MVS System Messages, Vol 8 (IEF-IGD).

The following is an example of the processing part for Action=Sign:

Signing results:
ASM      Successful

OUTFILE summary:                                                                                         
          Unsigned primary members      0                                                               
          Unsigned aliases              0                                                                
          Signed   primary members      1                                                               
          Signed   aliases              2                                                                
          Non-LM   members              0                                                               
          Overlay       LM              0                                                               
          Zero-TEXT     LM              0   

Processing summary of selected primary members:
          Selected                      1
          Processed                     1
          Processed successfully        1
          Processed with error          0 

IEW6007W SYSCATLG in INFILE is excluded. It is not a load module.

Task completed with RC=4.

The following example shows the result of SYSPRINT for Action=Report,Verbose=No,ReporLevel=1:

Note: The selection part is not provided here, as it is the same as in Example 7a.

Name      Signed
BPXMIDMX  No
M1        Yes
M2        Yes
M3        Yes
M41ST     Yes
M4111     Yes
M4112     Yes
YM1       Yes
YM2       Yes
ZM1       Yes 

Processing summary of selected primary members:
          Selected                      10
          Processed                     10
          Processed successfully        10
          Processed with error          0
 
IEW6007W SYSCATLG in INFILE is excluded. It is not a load module.

IEWSIGN exits with return code 4.

The following example shows the result of SYSPRINT for Action=Report,Verbose=No,ReporLevel=3:

Note: The selection part is not provided here, as it is the same as in Example 7a. Also, since the report formats for ReporLevel=2 and ReporLevel=3 are identical, only an example for ReporLevel=3 is provided.

Name      Size     Link date/time      Rel  Signed ErrorID Sign date/time      ALG  Cert-Index
BPXMIDMX  00002218 2021-08-02 14:03:50 0205 No
M1        00000008 2022-09-14 08:29:45 0205 Yes    ERR01
M2        00000008 2022-09-14 08:29:45 0205 Yes    ERR01
M3        00000008 2022-09-14 08:29:45 0205 Yes    ERR01
M41ST     00000008 2022-09-14 08:29:45 0205 Yes    ERR01
M4111     00000008 2022-09-14 08:29:45 0205 Yes    ERR01
M4112     00000008 2022-09-14 08:29:45 0205 Yes    ERR01
YM1       00000008 2022-09-30 22:19:28 0205 Yes    ERR09
YM2       00000008 2022-10-02 21:19:09 0205 Yes    ERR09
ZM1       00000008 2022-10-13 15:11:32 0205 Yes            2022-10-13 15:11:32 0202 INDEX001
 

ErrorID   Number    Error explanations
ERR01          6    Signing records lost or incomplete.
ERR09          2    Signature length is invalid.
 
Algorithm ID        Hash algorithm                Sign algorithm
0202                SHA2-512                      ECDSA-P521
 
Certificate summary:
Cert-Index:         INDEX001
Subject KeyID:      21CC95D0 8A12F9FE 5AA01598 430EF6A0 8D58DFDE
Cert Fingerprint:   0CED78C4 802B2B9A 3D190F75 8A79F005 87EF2294 69D680A0 C63B2FEE D3120D83

Processing summary of selected primary members:
          Selected                      10
          Processed                     10
          Processed successfully        2
          Processed with error          8
 
IEW6007W SYSCATLG in INFILE is excluded. It is not a load module.
IEW6027E 8 reported load modules have errors.
 
IEWSIGN exits with return code 8.

The following is an explanation of the contents in this example.

The terms in the first table of the example are described as follows:

Size: The size of the load module's code in bytes.
Link date/time: When the load module was built. It will be blank if the link time is unavailable.
Rel: The binder version that linked the load module.
Signed: Indicates whether the module is signed.
ErrorID: Indicates whether there is a signature error. Blank means no error. Use this error ID to find an error description.
Sign date/time: Indicates when the load module was signed.
ALG: The algorithm of hash and sign. Use this ID to find an algorithm description.
Cert-Index: An index assigned by IEWSIGN. Use this index to find a certificate displayed in “Certificate summary”, which signed this load module.

The table with heading “ErrorID Number Error explanations” provides the number of each error, along with a brief explanation for the error.

The following table provides a brief explanation and a detailed explanation for each ErrorID:

Table 4. ErrorID explanations
ErrorID	Brief explanation	Detailed explanation
ERR01	Signing records lost or incomplete.	The sign flag in the directory is on, but the signing records are lost or incomplete. This error is usually caused by some tools that are able to read and write regular records in load modules, but will discard the new signing records. For example, IEBCOPY with COPYMOD will cause this error.
ERR02	Subtype of signing record is invalid.	A field in the signing record is invalid. The signing record has been modified by unknown tools.
ERR03	Version of signing record is invalid.	A field in the signing record is invalid. The signing record has been modified by unknown tools.
ERR04	Flags of the signing record are invalid.	A field in the signing record is invalid. The signing record has been modified by unknown tools.
ERR05	Length of signing record is invalid.	A field in the signing record is invalid. The signing record has been modified by unknown tools.
ERR06	Reserved field of signing record is invalid.	A field in the signing record is invalid. The signing record has been modified by unknown tools.
ERR07	Signature type is invalid.	A field in the signing record is invalid. The signing record has been modified by unknown tools.
ERR08	Signature version is invalid.	A field in the signing record is invalid. The signing record has been modified by unknown tools.
ERR09	Signature length is invalid.	A field in the signing record is invalid. The signing record has been modified by unknown tools.
ERR10	Signature reserved bytes are invalid.	A field in the signing record is invalid. The signing record has been modified by unknown tools.
ERR11	Signature algorithm is invalid.	A field in the signing record is invalid. The signing record has been modified by unknown tools.
ERR12	Signature hash is invalid. Load module has been modified.	The hash calculated at the reporting time does not match the hash calculated at the signing time. This error is usually caused by tools that are able to modify load modules. For example, SPZAP will cause this error.
ERR13	Directory entry error. Check the error message.	The directory entry of this module at the time of reporting is different from the directory entry of this module at the time of signing. More information is provided by one or more of the following error messages: IEW6022E, IEW6023E or IEW6024E

The table with the heading Algorithm ID Hash algorithm Sign algorithm provides the names of the algorithms used.

Certificate summary lists all certificates used to sign the reported load modules.

Return codes for the IEWSIGN utility

The following table lists the return codes, conditions of each return code, and the corresponding message that is issued for each condition.

Table 5. Return codes for the IEWSIGN utility
Return code (decimal)	Conditions of the return code
0	Successful completion. No error or warning messages are issued.
4	One or more non-load modules are found in INFILE. Message number: IEW6007W One or more overlay load modules are found in INFILE. Message number: IEW6008W One or more zero-text load modules are found in INFILE. Message number: IEW6009W The primary member has been renamed. Message number: IEW6011W
8	One or more directory entry errors have been found in INFILE. Message number: IEW6010E When Action=Report, an invalid signing record has been found. Message number: IEW6022E, IEW6023E, IEW6024E, IEW6025E, IEW6026E, IEW6027E RC4LIM or RC8LIM reached. Message number: IEW6014E, IEW6015E A load module has no CESD record or TEXT record, Message number: IEW6031E
12	Invalid parameters. Message number: IEW6001S, IEW6002S. IEW6003S, IEW6028S Necessary DD missed. Message number: IEW6004S Incorrect data set attributes. Message number: IEW6005S, IEW6006S, IEW6017S, IEW6018S, IEW6034S, IEW6035S Syntax error in INCLUDE or EXCLUDE. Message number: IEW6012S No load modules have been selected for processing. Message number: IEW6013S Output error of OUTFILE. Message number: IEW6019S, IEW6020S RACF has not been configured correctly to sign a load module. Message number: IEW6016S, IEW6033S IEWSIGN cannot allocate enough memory. Message number: IEW6021S Invalid blocksize of OUTFILE. Message number: IEW6029S, IEW6030S Language Environment callable service fails. Message number: IEW6032S