Usage notes for program verification

For unauthorized callers, this service tracks the resources used for verification in a ‘context’ using a task related name/token pair. The 16–byte token name has the following format:
```
IRRPVERFprogram-name
```
Where program-name is one of the parameters provided by the caller. Consequently, for any given series of VERINIT, VERUPDAT, VERFINAL, and VERCLEAN calls used to verify the signature of a single program object, the program name must be the same.
Calls to this service using different program names are considered independent operations.
For a given program name, VERINIT must be called before calling any of VERUPDAT, VERFINAL (with the exception documented in the descriptions of the PGSN_VF_CONTEXT@ and PGSN_VF_PGM_NAME_LEN fields in the VERFINAL parameter list), or VERCLEAN.
For a given program name, VERINIT cannot be called a second time without terminating the first VERINIT with a call to VERFINAL or VERCLEAN.
For a given program name, it is the caller’s responsibility to call the VERCLEAN function in the event that signature generation will not be completed by calling VERFINAL. Note that all R_PgmSignVer functions will perform this cleanup if they return an error to the caller. The caller only needs to call the cleanup function if it is terminating for its own reason.
If auditing is required, it is performed in the VERFINAL (or VERINTER) call. Auditing is only performed when the ICHSFENT is provided by an authorized caller, subject to the audit settings from the directive within and the outcome of the VERFINAL service.

Some signature generation and all verification functions allow, from a pointer in the function-specific parameter list, the specification of an array of ranges of data to be hashed. This is optional. If the address is 0, no data will be hashed. The ranges are defined using the structure mapped by PGSN_DATA_RANGE in the IRRPCOMP mapping macro. This structure must exist in storage within the primary address space. The structure consists of an ALET followed by a fullword specifying the number of ranges which follow (if the number of ranges is 0, no data will be hashed). This is followed by an array of pointer pairs. Each pointer is an 8-byte pointer. AMODE(31) callers must set the high order fullword of the pointer fields to 0. The first pointer is the address of the first byte of the range, and the second pointer is the address of the last byte of the range (they can be the same, for a length of 1). The maximum number of ranges which can be specified per call is defined in the PGSN_DATA_NUM_RANGES_MAX constant.

Field	Attributes	Description
PGSN_DATA_RANGE	Structure	Ranges of data to verify.
PGSN_DATA_ALET	4 byte numeric	The ALET for the address space containing the data.
PGSN_DATA_NUM_RANGES	4 byte numeric	The number of data ranges in the following array, not to exceed PGSN_DATA_NUM_RANGES_MAX.
PGSN64_DATA_RANGE_LIST	Array	Repeating array of the following data items.
PGSN_DATA_START@	Address of	Address of the first byte in the range.
PGSN_DATA_END@	Address of	Address of the last byte in the range.

The default message digest algorithm is SHA256. This is the only supported message digest algorithm.

The ZOSSignatureInfo structure is DER encoded. It has the following ASN.1 definition:

ZOSSignatureInfo ::= SEQUENCE {
   signDetails     SignatureDetails
   certs           SET OF Certificate -- In reverse hierarchy order, EE to root
   signature       BIT STRING         -- PKCS #1 format - Encrypted DigestInfo
}

SignatureDetails ::= SEQUENCE {       -- DER encoding included in data signed
   version         INTEGER(0)
   signatureAlg    AlgorithmIdentifier -- From PKCS #1
   signatureTime	 OCTET STRING(12)      -- TIME DEC,ZONE=UTC,DATETYPE=YYYYMMDD
                                       -- format (EBCDIC)
}

The only supported algorithm for the signatureAlg field is sha256WithRSAEncryption with NULL parameters.
The only supported certificate key type is RSA. The maximum RSA key size is 4096 bits.
The supported certificate signature algorithms are:
- sha256WithRSAEncryption
- sha1WithRSAEncryption
All numeric parameters are treated as unsigned.
All length parameters must be non-zero unless otherwise indicated.
The program signature-verification key ring is specified using the APPLDATA field of FACILITY class profile IRR.PROGRAM.SIGNATURE.VERIFICATION. See z/OS Security Server RACF Security Administrator's Guide for more information about creating profiles.
If there is no ICHSFENT, and thus no directive, which is supplied by the caller, the verification occurs on the signature, but there is no check for the root CA certificate being trusted, and no auditing performed.