Start of change

IEAVBPRT: Validated Boot for z/OS® print utility

The IEAVBPRT utility reports the following information after a validated boot IPL:

  • Audit records that were created
  • Certificate extracts that are being used
  • Certificate extracts that were found not to be valid

For an enforce-mode IPL, no more than 1 audit record would be produced because any relevant issue would cause the system to enter a wait state right after building the audit record.

The IEAVBPRT utility provides options to generate a detailed report or a summary.

The same information is also provided by the IEAVBIPC utility within IPCS (VERBEXIT IEAVBIPC).

Invoking the IEAVBPRT utility

Invoke the IEAVBPRT utility as a job step program (such as, EXEC PGM=IEAVBPRT). The report output is written according to the SYSPRINT DD statement. IEAVBPRT opens the SYSPRINT DD with the attributes RECFM=FBA,LRECL=133.

The following example shows sample JCL for such a job step:
//VBPRT1   EXEC PGM=IEAVBPRT,TIME=1440,PARM=parm
//SYSPRINT DD   SYSOUT=A
The value of the parm parameter can be:
SUMMARY
Generates a summary report. This is the default value.
DETAIL
Generates a detailed report.

IEAVBPRT messages

The IEAVBPRT utility (and the IEAVBIPC utility in IPCS) issues the following messages:

IEAVB001I Validated Boot Information
This is the report header message.
IEAVB003I Audit Information
This message is followed by all the audit entries.

Within the audit entry messages, the term DSNE refers to a data set name entry. (Audit information is tracked by data set name.) Within those messages, the term DSNE ModE refers to a module name entry for a particular data set name entry. (Audit records are typically for a specific module within a specific data set.)

IEAVB004I There are no valid certificates
No valid certificates were found.
IEAVB005I Valid Certificates
This message is followed by information about each of the valid certificates.
IEAVB006I No certificates were discarded
There were no discarded certificates.
IEAVB007I Discarded Certificates
This message is followed by information about each of the discarded certificates.
IEAVB008I Validated Boot is not in effect
Validated boot is not in effect.
IEAVB009I Unable to access yyy at xxxxxxxx
This message is issued only by the IEAVBIPC utility.
IEAVB010I Unissued validated boot messages
This message is issued only by the IEAVBIPC utility and is followed by information about each unissued message.
(Audit mode) IEAVB011I PLPA page data set was specified. It would not be used if enforce mode.
(Enforce mode) IEAVB011I PLPA page data set was specified. It was not used.
A PLPA page data set was specified. PLPA page data sets are not used for an enforce-mode IPL.

The enforce-mode form of this message is issued only by the IEAVBIPC utility.

(Audit mode) IEAVB012I Not enough storage-class memory to hold LPA. A wait state would result if enforce mode.
(Enforce mode) IEAVB012I Not enough storage-class memory to hold LPA.
There was insufficient storage-class memory to hold the LPA. This would cause an enforce-mode IPL to enter a wait state.

The enforce-mode form of this message is issued only by the IEAVBIPC utility.

Contents of an IEAVBPRT report

The overall audit information displays one or more of the following lines:
There are no valid certificates
Could not retrieve certificate information
Total verification failures: n
Number of DSNEs: n
Number of DSNE ModEs: n
The last 2 lines are displayed only if the DETAIL option is in effect.
There might be no data set related audit entries, in which case the following line appears:
No dataset information is available
An audit entry begins with the following lines:
DSN(VOL): dataset_name(volume)
  Total DSN verification failures: n
  Number of DSNE ModEs: n
  [No module information is available]
  • The "Number of DSNE ModEs" line appears only when DETAIL is in effect.
  • The last line is displayed when there are no module name entries.
When DETAIL is not in effect and there is at least one module name entry, a table of module names and reasons appears:
Modname  Reason
m        r
When DETAIL is in effect and there is at least one module name entry:
Modname: m
  Reason: r
  {Key ID: xxxxxxxx_xxxxxxxx_xxxxxxxx_xxxxxxxx_xxxxxxxx | Key ID: not known}
  Fetch Type: ft
  Number of failures: n
  When first failed: yyyy/mm/dd hh:mm:ss
  Cert Name: cn
  When signed: yyyy/mm/dd hh:mm:ss
  Machine loader error info: xxxxxxxx xxxx
  • The "Key ID" and "When signed" lines appear only when the module signature is found.
  • The "Cert Name" line appears only when a certificate with a matching key ID is found.
  • The "Machine loader error info" line appears when there are machine loader errors, for module name IEAIPL00 only, for one of the following reasons:
    • Module was not signed
    • Signature verification failed
    • Machine loader detected error(s)
Within the message text:
m
The name of the module. When the module name ends with a X’C0’ character, that character is displayed as '*'.
r
One of the following reasons:
Module was not signed
The module is not signed.
Directory entry not found
The directory entry for the module could not be found.
Directory entry did not match
The directory for the module was found but does not match.
Signature not found
No signature record was found for this module.
Hash algorithm not valid
The signature record does not indicate a valid hash algorithm.
Signature algorithm not valid
The signature record does not indicate a valid signature algorithm.
Hash value not correct
The hash value in the signature record does not match the calculated hash value.
No certificate with matching key ID
The key ID in the signature record does not match any verification key available to this LPAR.
Signature verification failed
The signature verification operation did not complete successfully.
Overlay module
This is an overlay module. Signature support is not provided.
Signature record version not valid
The version of the signature record is not valid.
Machine loader detected error(s)
The machine loader detected one or more errors.
ft
One of the following fetch types:
IPL
Indicates that the fetch is during the early IPL phase.
Nucleus
Indicates that the fetch is for a module that is being used to build the nucleus.
NIP
Indicates that the fetch is for a module during the later IPL phase.
LPA
Indicates that the fetch is for a module that is being placed into PLPA, MLPA, or FLPA.
An entry for a valid certificate contains the following lines:
Name: cert_name
    Key ID: xxxxxxxx_xxxxxxxx_xxxxxxxx_xxxxxxxx_xxxxxxxx
    Successful uses: n
    Valid as of: yyyy/mm/dd hh:mm:ss
    Expiration: yyyy/mm/dd hh:mm:ss
    [Reason: Key is not valid]
  • The "Key ID", "Valid as of", and "Expiration" lines appear only when DETAIL is requested.
  • The "Reason: Key is not valid" line is determined after the system has started using the certificate. If this occurs, correct the certificate.
An entry for a discarded certificate contains the following lines:
Name: cert_name
    Reason: r
    KeyID: xxxxxxxx_xxxxxxxx_xxxxxxxx_xxxxxxxx_xxxxxxxx
    Valid as of: yyyy/mm/dd hh:mm:ss
    Expiration: yyyy/mm/dd hh:mm:ss
  • The "Key ID", "Valid as of", and "Expiration" lines appear only when DETAIL is requested.
Within the message text:
r
One of the following reasons:
Not valid yet
The certificate is not yet valid.
Expired
The certificate has expired.
Key is not valid
The key is not valid.
Key type is not valid
The key type is not valid.
Key ID length is not valid
The length of the key ID is not valid.
Hash type is not valid
The hash type is not valid.
Hash length is not valid
The length of the hash is not valid.
If any of these reasons occur, correct the certificate.

IEAVBPRT return codes

Table 1. Return codes for the IEAVBPRT utility
Return code (decimal) Meaning
0 Successful completion. No audit information was found.
2 Successful completion. This was not a validated boot IPL.
4 Successful completion. Some audit information was found.
8 An invalid parameter was specified.
12 An invalid SYSPRINT data set was specified.

Examples

  1. The following example shows a DETAIL entry for a module (within an entry for a data set):
    Modname: IEAIPL00
      Reason: Module was not signed
      Fetch Type: IPL
      Number of failures: 1
      When first failed: 2022/10/19 13:15:07
      Machine loader error info: 12000000 3400
  2. The following example shows a partial DETAIL entry for a data set and module:
    IEAVB003I Audit Information 
      Total verification failures: 1909  
      Number of DSNEs: 7                 
      Number of DSNE ModEs: 1754         
                                         
      DSN(VOL): SUPER.CSV.LOAD.PDS.HUGE.SIGNED(D16PK8) 
        Total DSN verification failures: 1             
        Number of DSNE ModEs: 1                        
                                                       
        Modname: GM64                                  
          Reason: No certificate with matching key ID  
          Fetch Type: LPA                              
          Number of failures: 1                        
          When first failed: 2022/10/26 17:51:50       
          Key ID: 21CC95D0_8A12F9FE_5AA01598_430EF6A0_8D58DFDE
          When signed: 2022/10/26 17:46:19             
    
End of change