Steps for enabling a user to sign a program using external code-signing certificates

Before you begin:

Obtain or locate the root certificate-authority (CA) certificate of an external CA and store it in a cataloged, variable-byte (VB) MVS™ data set.
Determine your IRR.PROGRAM.SIGNING profile structure for assigning program-signing key rings to users who are authorized program signers.
The following steps are based on defining the IRR.PROGRAM.SIGNING.userid profile. Therefore, the following examples define a program-signing key ring for each authorized program signer. For details about other options, see Details about defining IRR.PROGRAM.SIGNING profiles.

Guideline: If you opt instead to define the IRR.PROGRAM.SIGNING profile to assign the same key ring to all authorized signers, you might use a profile in the RDATALIB class instead of the FACILITY class to authorize users to access the program-signing ring. A profile in the RDATALIB class allows you to authorize users to a specific key ring. For details, see "RACF® Authorization" for R_datalib (IRRSDL00 or IRRSDL64) in z/OS Security Server RACF Callable Services.

Perform the following steps to enable a user to digitally sign a program using code-signing certificates that you obtain from an external certificate-authority (CA).

If not already done, add the root CA certificate of the external CA to RACF, specifying the name of the data set where it is stored.
Example:
```
RACDCERT CERTAUTH ADD(CA.CERT.DSN) WITHLABEL('MyCompany Code Signing CA')
```
______________________________________________________________________
For each user, obtain a code-signing certificate from the external CA and add it to RACF. To do so, perform the following sub-steps.
1. Create a self-signed code-signing certificate (as a placeholder) that will be signed by the external CA.
  Rule: Do not specify the PKDS, PCICC, or ICSF option. The private key of the code-signing certificate must reside in the RACF database.
  Example:
```
RACDCERT ID(RAMOS) GENCERT 
  SUBJECTSDN(CN('Ramos Code Signing Cert') O('MyCompany') C('US')) 
  SIZE(1024) WITHLABEL('Ramos Code Signing Cert') 
  KEYUSAGE(HANDSHAKE DOCSIGN)
```
2. Create a PKCS #10 certificate request based on the placeholder certificate you created in Step 2.a, specifying the name of the MVS data set where the certificate request will be stored.
  Example:
```
RACDCERT ID(RAMOS) GENREQ(LABEL('Ramos Code Signing Cert'))
  DSN(RAMOS.CERT.REQUEST.DSN)
```
3. Send the MVS data set (for example, RAMOS.CERT.REQUEST.DSN) containing the stored certificate request to the external CA.
4. Receive the signed certificate returned by the external CA and store it in a cataloged, variable-byte (VB) MVS data set (for example, RAMOS.CERT.DSN).
5. Add the new signed certificate to RACF, replacing the placeholder certificate you created in Step 2.a.
  Example:
```
RACDCERT ID(RAMOS) ADD(RAMOS.CERT.DSN) WITHLABEL('Ramos Code Signing Cert')
```
______________________________________________________________________
For each user, create a program-signing key ring to hold the external certificates you added in Steps 1 and 2.
Rule: Specify only uppercase characters in the key ring name. This is because you must specify the ring name in the APPLDATA field of the FACILITY profile you create in Step 5.
Example:
```
RACDCERT ID(RAMOS) ADDRING(RAMOS.CODE.SIGNING.KEYRING)
```
______________________________________________________________________
Connect both of the certificates you added in Steps 1 and 2 to the key ring you created in Step 3.
Rule: The code-signing certificate must be the default certificate in the ring.
Example:
```
RACDCERT ID(RAMOS) CONNECT(CERTAUTH LABEL('MyCompany Code Signing CA')
  RING(RAMOS.CODE.SIGNING.KEYRING))
RACDCERT ID(RAMOS) CONNECT(ID(RAMOS) LABEL('Ramos Code Signing Cert') DEFAULT
  RING(RAMOS.CODE.SIGNING.KEYRING))
```
______________________________________________________________________
For each user, create a FACILITY class profile that specifies the hash algorithm and the name of the key ring to be used whenever the user digitally signs a program module.
Example:
```
RDEFINE FACILITY IRR.PROGRAM.SIGNING.RAMOS
  APPLDATA('SHA256 RAMOS/RAMOS.CODE.SIGNING.KEYRING')
```
______________________________________________________________________
Permit each user to access his own key rings, if not already authorized, by administering a profile in either the FACILITY or the RDATALIB class.
- When using the FACILITY class:
```
RDEFINE FACILITY IRR.DIGTCERT.LISTRING UACC(NONE) 
PERMIT IRR.DIGTCERT.LISTRING CLASS(FACILITY) ID(RAMOS) ACCESS(READ)
```
  - If the FACILITY class is not already active, activate and RACLIST it.
```
SETROPTS CLASSACT(FACILITY) RACLIST(FACILITY)
```
  - If the FACILITY class is already active and RACLISTed, refresh it.
```
SETROPTS RACLIST(FACILITY) REFRESH
```
- When using the RDATALIB class:
```
RDEFINE RDATALIB RAMOS.CODE.SIGNING.KEYRING.LST UACC(NONE)
PERMIT RAMOS.CODE.SIGNING.KEYRING.LST CLASS(RDATALIB) 
    ID(RAMOS) ACCESS(READ)
```
  - If the RDATALIB class is not already active, activate and RACLIST it.
```
SETROPTS CLASSACT(RDATALIB) RACLIST(RDATALIB)
```
  - If the RDATALIB class is already active and RACLISTed, refresh it.
```
SETROPTS RACLIST(RDATALIB) REFRESH
```
______________________________________________________________________

You have now enabled a user to digitally sign a program using code-signing certificates that you obtained from an external certificate-authority (CA).