Usage notes for program signing

This service tracks the resources used for signing using a task-related name/token pair. The 16–byte token name has the following format:
```
IRRPSIGNprogram-name
```
Where program-name is one of the parameters provided by the caller. Consequently, for any given series of SIGINIT, SIGUPDAT, SIGFINAL, and SIGCLEAN calls used to sign a single program object, the program name value must be the same.
Calls to this service using different program name values are considered independent operations.
For a given program name, SIGINIT must be called before calling any of SIGUPDAT, SIGFINAL, or SIGCLEAN.
For a given program name, SIGINIT cannot be called a second time without terminating the first SIGINIT with a call to SIGFINAL or SIGCLEAN.
For a given program name, it is the caller’s responsibility to call the SIGCLEAN function if signature generation is not completed by calling SIGFINAL. Note that all R_PgmSignVer functions will perform this cleanup if they return an error to the caller. The caller must call the cleanup function if it is terminating for its own reason.

The signature area allocated and returned to the caller in the PGSN_SF_SIG_AREA@ parameter by SIGFINAL has the following format:

Table 1. PGSN_SF_SIG_AREA@ signature area format
Offset	Length	Description
0	4	Eyecatcher, “PSSD”.
4	4	Length of entire area, including the eyecatcher.
8	1	Subpool used to obtain the area storage.
9	3	Reserved.
12	4	Length of z/OS® signature information area.
16	*	ZOSSignatureInfo structure to be included in the signed program object. See the next usage note for the format.

The ZOSSignatureInfo structure returned in the signature area is the signature data that is to be placed in the signed program object. It is DER encoded according to 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.
It is the caller’s responsibility to free the signature area when it is no longer needed.
The only supported message digest algorithm is SHA256.
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.
On SIGINIT, if the key ring to use is not specified, the security manager determines the key ring that is based on security settings. See the z/OS Security Server RACF Security Administrator's Guide for information on these security settings and on how to populate the key ring . There can be no more than 10 certificates within the trust chain, starting with the code signer and ending with the self-signed certificate authority certificate.
If no program data is ever passed in by the caller, a digital signature is generated solely for the SignatureDetails structure documented above.