Steps for verifying a signed program

Before you begin:

Do not perform these steps until you complete Steps for preparing RACF to verify signed programs (one-time setup).
Do not perform these steps to enable RACF® to verify the modules of z/OS® System SSL. Instead, see "System SSL module verification setup" in z/OS Cryptographic Services System SSL Programming.
For each signed program you want RACF to verify:
- Obtain or locate the root certificate-authority (CA) certificate of each code signer.
  - If the program was acquired from a software vendor, review the software documentation for information about obtaining the vendor's root CA certificate and adding it to RACF. Once you obtain the root CA certificate, store it in a cataloged, variable-byte (VB) MVS™ data set.
  - If the program was signed by your installation (in Step 1 of Steps for enabling a user to sign a program using RACF code-signing certificates) or signed by an external CA (in Step 1 of Steps for enabling a user to sign a program using external code-signing certificates), locate the label name of root CA certificate in the RACF database.
    To list all CA certificates in the RACF database, issue the RACDCERT LIST CERTAUTH command.
- Determine if the program is already controlled by a generic program profile. If so, create a new program profile to control this program or ensure that all programs controlled by this profile are signed. An unsigned program controlled by a profile with the SIGVER options shown in Step 3 will fail to load. If several similarly named programs can be verified using the same SIGVER options, you might choose to create a generic profile such as ABC*. If you do, ensure that no other programs are unintentionally verified based on their similar program names.
  Important: Do not specify the SIGVER options shown in Step 3 for the ** program profile because this might fail critical programs and lead to system failure.
- If you share the RACF database with other z/OS systems, determine if another version of this program runs on a shared system. If so, ensure that the version on the shared system is signed. Alternatively, control the other version with a separate program profile.
- Determine if the program has an alias (an alternate name that can be used to execute it). If so, control both the real name and the alias name. This might require an additional PROGRAM profile in Step 3. For an example, When a controlled program has an alias name.

Perform the following steps for each signed program you want RACF to verify.

Add the root CA certificate of the code signer to RACF as a trusted CA.
Skip this step if you created the root CA of the code signer (in Step 1 of Steps for enabling a user to sign a program using RACF code-signing certificates), or if you obtained the root CA of the code signer from an external CA and added it to RACF (in Step 1 of Steps for enabling a user to sign a program using external code-signing certificates).
1. If you obtained the root CA certificate of the code signer from a software vendor, add it to RACF, specifying the name of the data set where it is stored.
  Example:
```
RACDCERT CERTAUTH ADD(VENDOR.CA.CERT.DSN) 
  WITHLABEL('Vendor Code Signing CA') 
  TRUST
```
2. If the vendor's root CA certificate is already added to RACF, add the TRUST attribute if it is not already trusted.
  Example:
```
RACDCERT CERTAUTH ALTER(LABEL('Vendor Code Signing CA')) TRUST
```
______________________________________________________________________
Add the root CA certificate to the key ring that your installation uses for signature verification. This is the ring you created in Step 1 of Steps for preparing RACF to verify signed programs (one-time setup).
Examples:
```
RACDCERT ID(RACFADM) CONNECT(CERTAUTH LABEL('Vendor Code Signing CA')
  RING(CODE.SIGNATURE.VERIFICATION.KEYRING))

-or-

RACDCERT ID(RACFADM) CONNECT(CERTAUTH LABEL('MyCompany Code Signing CA')
  RING(CODE.SIGNATURE.VERIFICATION.KEYRING))
```
______________________________________________________________________
Create or modify the PROGRAM class profile that controls the signed program and specify the signature verification options.
The following examples specify that the load of program MYPROG14 should fail if the signature cannot be verified for any reason and that only failures should be logged.
Examples:
```
RDEFINE PROGRAM MYPROG14 ADDMEM('SYS1.TEST.LOADDLL'//NOPADCHK) UACC(READ) 
  SIGVER(SIGREQUIRED(YES) FAILLOAD(ANYBAD) SIGAUDIT(ANYBAD))

-or-

RALTER PROGRAM MYPROG14 
  SIGVER(SIGREQUIRED(YES) FAILLOAD(ANYBAD) SIGAUDIT(ANYBAD))
```
If you want to delegate authority to perform this step to a user who does not have the SPECIAL attribute, see Delegating the authority for specifying signature verification options.

______________________________________________________________________
Activate your profile changes in the PROGRAM class.
Example:
```
SETROPTS WHEN(PROGRAM) REFRESH
```
______________________________________________________________________

You have now enabled RACF to verify a signed program. If you specified the signature verification options shown in the example in Step 3, the program will fail to load if RACF cannot verify the signature for any reason. If the program is part of a critical business application, be prepared to invoke a recovery procedure to minimize the business impact.