Program Signing and Verification

Invoked Sub-functions › Program Signing and Verification

Program Signing and Verification

CA Top Secret supports program signing and the verification of programs. You can dictate that certain programs must have valid digital signatures prior to their loading in the system. You can also set up the records required to allow users to sign programs using the z/OS Binder.

Program Signing

A user can indicate that a signature is required by using the SIGN binder option when the program object is created. The binder only generates signatures for program objects stored in a PDSE.

To sign a program, the user must have access to a key ring and the certificate objects stored in the key ring. The key ring used during signing must contain a code-signing certificate and its private key and each certificate authority (CA) certificate in the certificate chain of the code-signing certificate. Note the following certificate restrictions within this key ring:

There can be more than ten certificates in the certificate chain of the code-signing certificate.
The key ring may not be a PKCS #11 token.
The code signing certificate and each certificate in the chain must be signed using either the sha256WithRSAEncryption or sha1WithRSAEncryption signature algorithms.
The code-signing certificate must have the no KeyUsage extension or a KeyUsage extension with at least the digitalSignature and nonRepudiation values set.
The CA certificates in the code-signing certificate chain must have certificate-signing capabilities. They must have both of the following – either the certificate has no BasicConstraints extension, or the certificate must have BasicConstrains extension with the CA indicator enabled plus the certificate either has no KeyUsage extension or the keyUsage exitension is present and at least the keyCertSign value is enabled

When the binder attempts to sign a program, it obtains the code-signing key ring by issuing a RACROUTE EXTRACT for a profile in the following format. It extracts each profile until it finds a profile:

IRR.PROGRAM.SIGNING.group.user
IRR.PROGRAM.SIGNING.user
IRR.PROGRAM.SIGNING.group
IRR.PROGRAM.SIGNING

In CA Top Secret, the user performing the program signing must have a PERMIT to the profiles in the ACID record, in an attached profile, or using the ALL record. The USERID and KEYRING, which are used for the program signing, are obtained from the APPLDATA field associated with the selected permit.

A user who requests that a program be signed using the binder must have access to the certificate objects in the selected key ring. The certificate objects are obtained using the R_datalib callable service. If you decide to assign the same key ring to all authorized signers, you can create resource rules in the RDATALIB class instead of the FACILITY class. The RDATALIB class rules let you grant access to a specific key ring. The FACILITY class resources grant access to any key ring.

Program Verification

The program verification process uses a single key ring for all programs being verified. This key ring must contain a root CA certificate for each of your trusted program signer certificates. This key ring also has some restrictions on the key ring and the certificates within this key ring:

You must add the TRUST status to the IBM code signing CA certificate supplied with CA TSS.
The key ring may not be a PKCS #11 token.
Each root CA certificate must be signed using either the sha256WithRSAEncryption or sha1WithRSAEncryption signature algorithms.
Each root CA certificates must have certificate-signing capabilities. They must have the following:
- The certificate has no BasicConstraints extension or the certificate must have BasicConstrains extension with the CA indicator enabled plus the certificate either has no KeyUsage extension or the keyUsage exitension is present and at least the keyCertSign value is enabled.

When the program is loaded, the z/OS Loader obtains the signature verification key ring by issuing a RACROUTE EXTRACT for the IRR.PROGRAM.SIGNATURE.VERIFICATION profile.

The USERID and KEYRING used for the verification process are obtained from the APPLDATA field associated with a PERMIT to the IRR.PROGRAM.SIGNATURE.VERIFICATION profile.

Defining Programs for Verification

SIGVER records specify which programs require a valid digital signature. The SIGVER records can indicate if the load should fail if the program does not contain a valid signature or if an audit record should be cut. SIGVER records can also determine if signed programs are currently executing in your system.

Verify a Signed Program

SIGVER records let you specify which programs require a valid digital signature. The SIGVER records can indicate if the load should fail if the program does not contain a valid signature or if an audit record should be cut. SIGVER records can also determine if signed programs are currently executing in your system.

To verify a signed program

Create the signature verification key ring by entering the following command:
Note: You only perform this step once because all signature verification requests use the same key ring.
```
TSS ADD(USER01) KEYRING(SIGVER) LABLRING('Pgm_Signature_Ver')     
```
Note: All users loading signed programs must be able to access the certificates on this key ring. The key ring is accessed using the R_Datalib callable service. You may want to provide access using the RDATALIB class instead of the FACILITY class. The RDATALIB class rules let you grant access to a specific key ring. The FACILITY class resources grant access to any key ring. For more information, see z/OS Security Service RACF Callable Services.

The signature is created.

Note: Skip the following step if you generated the CA certificate.
Add the root CA certificate to CA TSS as a trusted CA by entering the following command:
```
TSS ADD(CERTAUTH) DIGICERT(PSVCA) DCDSN(VENDOR.CA.CERT.DSN) labei(Vendor Code Signing CA) TRUST
```
The root CA certificate is added to CA TSS.
Add the root CA certificate to the signature verification key ring (this is the key ring created earlier) by entering the following command:
```
TSS ADD(USER01) KEYRING(SIGVER) RINGDATA(CERTAUTH,PSVCA)
```
The root CA certificate is added to the key ring.
Create the SIGVER record to indicate a signature is required by entering the following command:
```
TSS ADD(SIGVER) PROGRAM(iefbr14) SIGREQ(YES) FAILLOAD(ANYBAD) SIGAUDIT(FAIL)
```
The SIGVER record is created.

Manage the SIGVER Record

Use this procedure to add a program to the SIGVER record. The SIGVER record is a VSAM record type.

All keywords are optional except the program name. LOADLIB is optional, but it is part of the VSAM record key; therefore if it is specified on an ADD, you must also specify it on a REMOVE and REPLACE.

To add a program to the SIGVER record, issue the following command:

 TSS ADD(SIGVER) PROGRAM(prog_name) 
     [LOADLIB(dsname[,volser])]
     [SIGREQ(YES|NO)] 
     [FAILLOAD(ANYBAD | BADSIGONLY | NEVER  )]
     [SIGAUDIT(ALL | FAIL| NONE  )]

prog_name: Identifies the program name.
dsname: Identifies the data set where the program is stored.
volser: Identifies the volume serial number.

For detailed information regarding keywords, see the Command Functions Guide.

Examples: Managing the SIGVER Record

To replace a program in the SIGVER record, use the following command:

TSS REPLACE(SIGVER) PROGRAM(prog_name){any valid keyword}

To remove a program from the SIGVER record, use the following command:

TSS REMOVE(SIGVER) PROGRAM(prog_name)
[LOADLIB(dsname[,volser])]

To list program details for the SIGVER record, use the following command:

TSS LIST(SIGVER) PROGRAM(*|prog_name)
[LOADLIB(dsname[,volser])]

Authorize and Assign a Keyring for Program Signing

For the signing process, a user must be authorized for the IRR.PROGRAM.SIGNING profile in the IBMFAC resource class. Assign the algorithm and key ring name using the APPLDATA keyword on the PERMIT command.

Note: You can allow different key rings for different departments and users.

The entity name in the PERMIT may be suffixed by a group name, a user ID, or both. The PERMIT may be associated with a user ACID or the *ALL record.

To authorize and assign a keyring, issue the following command:

TSS PERMIT(tssuser)  IBMFAC(IRR.PROGRAM.SIGNING[group[.user]) 
	APPLDATA('[SHA256] userid/keyring_name')

group: Specifies the group name.
user: Specifies the user name.
SHA256: Specifies the digest algorithm. SHA256 is the only supported algorithm.
userid: Specifies the user ID.
keyring_name: Specifies the eight-byte keyring name.

The keyring is assigned and authorized.

If an algorithm name is included within the APPLDATA string, include a single blank before the USERID name.

The APPLDATA value is extracted by searching for a best match PERMIT in the following order:

IRR.PROGRAM.SIGNING.group.user
IRR.PROGRAM.SIGNING.user
IRR.PROGRAM.SIGNING.group
IRR.PROGRAM.SIGNING

Examples: Program Signing

Authorize a user within a group to use the Pgm_Sign_Ver keyring associated with USER99 and specify the SHA256 algorithm:

TSS PERMIT(USER01)  IBMFAC(IRR.PROGRAM.SIGNING.OMVSGRP.USER01)
     APPLDATA('SHA256 USER99/Pgm_Sign_Ver')

Authorize any user within a group to use the Pgm_Sign_Ver keyring associated with USER99 and specify the SHA256 algorithm:

TSS PERMIT(USER01)  IBMFAC(IRR.PROGRAM.SIGNING.OMVSGRP) 
     APPLDATA('SHA256 USER99/Pgm_Sign_Ver')

Authorize and Assign a Keyring for Signature Verification

For the verification process, a user must have authority for the IRR.PROGRAM.SIGNATURE.VERIFICATION profile in the IBMFAC resource class.

The verification process uses a single keyring, which needs all of the CA certificates attached to it. Use the APPLDATA keyword on the PERMIT command to assign the keyring. This PERMIT can be associated with the *ALL record.

To authorize and assign a keyring, issue the following command:

TSS PERMIT(ALL)  
	IBMFAC(IRR.PROGRAM.SIGNATURE.VERIFICATION) 
	APPLDATA('[SHA256] userid/keyring_name')

userid: Specifies the user ID.
keyring_name: Specifies the eight-byte keyring name.

The keyring is assigned and authorized.

Examples: Signature Verification

Authorize all users to use the Pgm_Sign_Ver keyring associated with USER99 and specify the SHA256 algorithm:

TSS PER(ALL) IBMFAC(IRR.PROGRAM.SIGNATURE.VERIFICATION) 
     APPLDATA('SHA256 USER99/Pgm_Sign_Ver')