Parameters

Work_area

The name of a 1024-byte work area for SAF. The work area must be in the primary address space.

ALET

The name of a word containing the ALET for the following parameter. Each parameter must have an ALET specified. Each ALET must be 0 for this service. The words containing the ALETs must be in the primary address space.

SAF_Return_Code

The name of a fullword in which the SAF router returns the SAF return code.

RACF_Return_Code

The name of a fullword in which the service routine stores the return code.

RACF_Reason_Code

The name of a fullword in which the service routine stores the reason code.

Num_parms

Specifies the name of a fullword that contains the total number of parameters in the parameter list. The contents of this field must be set to binary ten.

Function_code

The name of a 2-byte area containing the Function code. The function code has one of the following values:

X’0001’: Initialize signing. (Function name SIGINIT.) This function must be called before calling any of the other signing functions.
X’0002’: Digest intermediate program data for signature generation. (Function name SIGUPDAT.) This function is optional. It should be called only if all the program’s data cannot be processed on one call to generate signature. It may be called multiple times before calling generate signature.
X’0003’: Generate signature. (Function name SIGFINAL.) This function finalizes the signature generation and returns the result. It also frees any work area storage that may have been allocated.
X’0004’: Terminates the signing operation and frees resources allocated by SIGINIT. (Function name SIGCLEAN.) This function should be called only if signature generation is not to be finalized with a call to SIGFINAL. Note that all R_PgmSignVer functions will perform this cleanup if they return an error to the caller. The caller needs to call the cleanup function only if it is terminating for its own reason.
X’0005’: Initialize signature-verification and optionally digest initial program data. (Function name VERINIT.) This function must be called before calling any of the other verification functions except VERINTER (interrogate directive).
X’0006’: Digest intermediate program data for signature-verification. (Function name VERUPDAT.) This function is optional. It should be called only if all the program’s data cannot be processed on the VERINIT and VERFINAL calls. It may be called multiple times before performing final verification.
X’0007’: Perform final verification. (Function name VERFINAL.) This function finalizes the signature-verification and returns the result. It also audits the event and frees any work area storage that may have been allocated. If all the program data can be specified in a single call, then VERFINAL can be called without first calling VERINIT. See Table 7 for more information.
X’0008’: Terminates the signing operation and frees resources allocated by VERINIT. (Function name VERCLEAN.) This function should be called only if signature generation is not to be finalized with a call to 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.
X’0009’: Interrogate directive. (Function name VERINTER.) This function examines the directive (supplied within the ICHSFENT in the function-specific parameter list) to determine the appropriate action. This would be used for the cases where VERFINAL will not be called. For example, when digital signature processing is required but the module does not have a digital signature. This function is not available to unauthorized callers.

Function_parmlist

Specifies the name of the function code specific parameter list area for the Function_code specified.

All address fields are 8-byte addresses. When referring to 31-bit storage addresses, the caller must make sure that the high-order word of the address field is set to binary zeros.

Table 1. Function_parmlist for SIGINIT
Field	Attributes	Usage	Description
PGSN_SI_PLIST	Structure	In	Function-specific parameter list for signing initialization.
PGSN_SI_EYE	8 characters	In	Eyecatcher, 8 characters. Actual value must be set by invoker: 'SIGINIT '.
PGSN_SI_VERS	4 byte numeric	In	The version number for this function-specific parameter list. The contents of this field must be set to binary zero.
PGSN_SI_PGM_NAME_LEN	4 byte numeric	In	Length of the name of the program being signed. The length must not exceed 8 characters.
PGSN_SI_PGM_NAME@	Address of	In	Address of the name of the program being signed. Note: This parameter is used to derive the name/token that is used for subsequent calls. As such, it does not necessarily need to be the program name, but must be a unique value which does not result in a name collision with other signing operations.
PGSN_SI_KEYRING_NAME@	Address of	In	Address of the name of the SAF key ring that contains the certificates to be used for signing. The address is meaningful only if PGSN_SI_KEYRING_LEN is a non-zero value. The name that this address points to has the following syntax: owning-userid/ring-name The owning-userid (but not the slash) may be omitted if the key ring is owned by the user ID associated with the calling application.
PGSN_SI_KEYRING_LEN	4 byte numeric	In	Length of the name of the SAF key ring that contains the certificates to be used for signing. Set this field to binary zero to have the security manager determine the key ring to use.
PGSN_SI_SIGINFO_LEN	4 byte numeric	Out	Length of the ZOSSignatureInfo structure which will be returned as part of the signature area structure in the SIGFINAL call.
PGSN_SI_DIGEST_ALG	1 byte numeric	In	Numeric value indicating what message digest algorithm to use for the signing. Set this field to binary zero to have the security manager determine the algorithm to use. A value of 1 indicates that SHA256 is to be used.

Table 2. Function_parmlist for SIGUPDAT
Field	Attributes	Usage	Description
PGSN_SU_PLIST	Structure	In	Function-specific parameter list for intermediate signing.
PGSN_SU_EYE	8 characters	In	Eyecatcher, 8 characters. Actual value must be set by invoker: 'SIGUPDAT'.
PGSN_SU_VERS	4 byte numeric	In	The version number for this function-specific parameter list. The contents of this field must be set to binary zero.
PGSN_SU_PGM_NAME_LEN	4 byte numeric	In	Length of the name of the program being signed. The length must not exceed 8 characters.
PGSN_SU_PGM_NAME@	Address of	In	Address of the name of the program being signed. Must be the same as the value supplied on the SIGINIT call.
PGSN_SU_PGM_DATA@	Address of	In	Address of a structure specifying the intermediate range(s) of data to sign. The structure is mapped by PGSN_DATA_RANGE. See usage note 7 in Usage notes for program verification for the format of this structure.

Table 3. Function_parmlist for SIGFINAL
Field	Attributes	Usage	Description
PGSN_SF_PLIST	Structure	In	Function-specific parameter list for final signing.
PGSN_SF_EYE	8 characters	In	Eyecatcher, 8 characters. Actual value must be set by invoker: 'SIGFINAL'.
PGSN_SF_VERS	4 byte numeric	In	The version number for this function-specific parameter list. The contents of this field must be set to binary zero.
PGSN_SF_PGM_NAME_LEN	4 byte numeric	In	Length of the name of the program being signed. The length must not exceed 8 characters.
PGSN_SF_PGM_NAME@	Address of	In	Address of the name of the program being signed. Must be the same as the value supplied on the SIGINIT call.
PGSN_SF_PGM_DATA@	Address of	In	Address of a structure specifying the final range(s) of data to sign. The structure is mapped by PGSN_DATA_RANGE. See usage note 7 in Usage notes for program verification for the format of this structure.
PGSN_SF_SIG_AREA@	Address of	Out	Address of the allocated signature area structure. See usage note 6 in Usage notes for program signing for the format of the area.
PGSN_SF_SUBPOOL	1 byte numeric	In	Subpool to be used for allocation of the signature data structure. For unauthorized callers, this must be a value in the range 1 – 127.

Table 4. Function_parmlist for SIGCLEAN
Field	Attributes	Usage	Description
PGSN_SC_PLIST	Structure	In	Function-specific parameter list for signing cleanup.
PGSN_SC_EYE	8 characters	In	Eyecatcher, 8 characters. Actual value must be set by invoker: 'SIGCLEAN'.
PGSN_SC_VERS	4 byte numeric	In	The version number for this function-specific parameter list. The contents of this field must be set to binary zero.
PGSN_SC_PGM_NAME_LEN	4 byte numeric	In	Length of the name of the program being signed. The length must not exceed 8 characters.
PGSN_SC_PGM_NAME@	Address of	In	Address of the name of the program being signed. Must be the same as the value supplied on the SIGINIT call.

Table 5. Function_parmlist for VERINIT
Field	Attributes	Usage	Description
PGSN_VI_PLIST	Structure	In	Function-specific parameter list for verification initialization.
PGSN_VI_EYE	8 characters	In	Eyecatcher, 8 characters. Actual value must be set by invoker: 'VERINIT '.
PGSN_VI_VERS	4 byte numeric	In	The version number for this function-specific parameter list. The contents of this field must be set to binary zero.
PGSN_VI_PGM_NAME_LEN	4 byte numeric	In	For unauthorized callers, length of the name of the program being verified. The length must not exceed 8 characters. Ignored for authorized callers.
PGSN_VI_PGM_NAME@	Address of	In	For unauthorized callers, address of the name of the program being verified. Ignored for authorized callers.
PGSN_VI_CONTEXT@	Address of	Out	For authorized callers, address of the allocated verify context that the caller should pass in to subsequent verification calls. Ignored for unauthorized callers.
PGSN_VI_PGM_DATA@	Address of	In	Address of a structure specifying the initial range(s) of data to verify. The structure is mapped by PGSN_DATA_RANGE. See usage note 7 in Usage notes for program verification for the format of this structure.
PGSN_VI_SIGINFO@	Address of	In	Address of the ZOSSignatureInfo structure extracted from the program object being verified.
PGSN_VI_SIGINFO_LEN	4 byte numeric	In	Length of the ZOSSignatureInfo structure extracted from the program object being verified.
PGSN_VI_DIGEST_ALG	1 byte numeric	In	Numeric value indicating what message digest algorithm to use for the verification. A value of 0 means the value contained in the ZOSSignatureInfo structure should be used. This is the only supported value.

Table 6. Function_parmlist for VERUPDAT
Field	Attributes	Usage	Description
PGSN_VU_PLIST	Structure	In	Function-specific parameter list for intermediate verification.
PGSN_VU_EYE	8 characters	In	Eyecatcher, 8 characters. Actual value must be set by invoker: 'VERUPDAT'.
PGSN_VU_VERS	4 byte numeric	In	The version number for this function-specific parameter list. The contents of this field must be set to binary zero.
PGSN_VU_PGM_NAME_LEN	4 byte numeric	In	For unauthorized callers, length of the name of the program being verified. The length must not exceed 8 characters. Ignored for authorized callers.
PGSN_VU_PGM_NAME@	Address of	In	For unauthorized callers, address of the name of the program being verified. Must be the same as the value supplied on the VERINIT call. Ignored for authorized callers.
PGSN_VU_CONTEXT@	Address of	In	For authorized callers, address of the verify context area allocated on the VERINIT call. Ignored for unauthorized callers.
PGSN_VU_PGM_DATA@	Address of	In	Address of a structure specifying the intermediate range(s) of data to verify. The structure is mapped by PGSN_DATA_RANGE. See usage note 7 in Usage notes for program verification for the format of this structure.

Table 7. Function_parmlist for VERFINAL
Field	Attributes	Usage	Description
PGSN_VF_PLIST	Structure	In	Function-specific parameter list for final verification.
PGSN_VF_EYE	8 characters	In	Eyecatcher, 8 characters. Actual value must be set by invoker: 'VERFINAL'.
PGSN_VF_VERS	4 byte numeric	In	The version number for this function-specific parameter list. The contents of this field must be set to binary zero.
PGSN_VF_PGM_NAME_LEN	4 byte numeric	In	For unauthorized callers, length of the name of the program being verified. The length must not exceed 8 characters. Ignored for authorized callers. If the length is zero, it is assumed that no VERINIT call was made, and the signature is generated based on the data supplied in this call, using the default digest algorithm.
PGSN_VF_PGM_NAME@	Address of	In	For unauthorized callers, address of the name of the program being verified. Must be the same as the value supplied on the VERINIT call. Ignored for authorized callers.
PGSN_VF_CONTEXT@	Address of	In	For authorized callers, address of the verify context area allocated on the VERINIT call. Ignored for unauthorized callers. If the address is zero, it is assumed that no VERINIT call was made, and the signature is generated based on the data supplied in this call, using the default digest algorithm.
PGSN_VF_PGM_DATA@	Address of	In	Address of a structure specifying the final range(s) of data to verify. The structure is mapped by PGSN_DATA_RANGE. See usage note 7 in Usage notes for program verification for the format of this structure.
PGSN_VF_LOGSTRING@	Address of	In	Address of an area that consists of a 1 byte length field followed by character data (up to 255 bytes) to be included in any audit records that are created. If the address or the length byte is 0, this parameter is ignored.
PGSN_VF_ICHSFENT@	Address of	In	For authorized callers, address of the FASTAUTH entity parameter mapping containing the directive (previously retrieved from RACF® by Contents Supervision). This parameter is optional. See usage notes 6 and 16 in Usage notes for program verification. Ignored for unauthorized callers.
PGSN_VF_SIGINFO@	Address of	In	Address of the ZOSSignatureInfo structure extracted from the program object being verified. This field is required if VERFINAL is the only call being made. It is ignored if it was already passed to VERINIT.
PGSN_VF_SIGINFO_LEN	4 byte numeric	In	Length of the ZOSSignatureInfo structure extracted from the program object being verified. This field is required if VERFINAL is the only call being made. It is ignored if it was already passed to VERINIT.

Table 8. Function_parmlist for VERCLEAN
Field	Attributes	Usage	Description
PGSN_VC_PLIST	Structure	In	Function-specific parameter list for verification cleanup.
PGSN_VC_EYE	8 characters	In	Eyecatcher, 8 characters. Actual value must be set by invoker: 'VERCLEAN'.
PGSN_VC_VERS	4 byte numeric	In	The version number for this function-specific parameter list. The contents of this field must be set to binary zero.
PGSN_VC_PGM_NAME_LEN	4 byte numeric	In	For unauthorized callers, length of the name of the program being verified. The length must not exceed 8 characters. Ignored for authorized callers.
PGSN_VC_PGM_NAME@	Address of	In	For unauthorized callers, address of the name of the program being verified. Must be the same as the value supplied on the VERINIT call. Ignored for authorized callers.
PGSN_VC_CONTEXT@	Address of	In	For authorized callers, address of the verify context area allocated on the VERINIT call. Ignored for unauthorized callers.

Table 9. Function_parmlist for VERINTER
Field	Attributes	Usage	Description
PGSN_ID_PLIST	Structure	In	Function-specific parameter list for interrogating the directive.
PGSN_ID_EYE	8 characters	In	Eyecatcher, 8 characters. Actual value must be set by invoker: 'VERINTER'.
PGSN_ID_VERS	4 byte numeric	In	The version number for this function-specific parameter list. The contents of this field must be set to binary zero.
*	4 characters	In	Reserved
PGSN_ID_ ICHSFENT@	Address of	In	For authorized callers, address of the FASTAUTH entity parameter mapping (previously retrieved from RACF by Contents Supervision). Ignored for unauthorized callers.
PGSN_ID_LOGSTRING@	Address of	In	Address of an area that consists of a 1 byte length field followed by character data (up to 255 bytes) to be included in any audit records that are created. If the address or the length byte is 0, this parameter is ignored.
PGSN_ID_EVENT	1 byte numeric	In	Constant indicating what sigver event was detected: x’01’ – Digital signature processing is required but the module does not have a digital signature. x’02’ – Digital signature processing is required. The PDSE directory entry for the module indicates it’s signed but the digital signature is missing.