Configure IBM RACF Security

Configure IBM RACF security to enable use of the SMP/E RECEIVE ORDER command. A user digital certificate is required to identify a user uniquely to the CA Automated Order Server and Digicert certificates are required. Sample IBM RACF commands are provided.
cmcm
Configure IBM RACF security to enable use of the SMP/E RECEIVE ORDER command. A user digital certificate is required to identify a user uniquely to the CA Automated Order Server and Digicert certificates are required. Sample IBM RACF commands are provided. Before you modify the security characteristics for your system, consult the RACF security administrator and see the
z/OS Security Server RACF Security Administrator's Guide
.
2
Configure RACF Security for the Server Certificates
Use the following procedure to configure RACF security for the server certificates.
Follow these steps:
  1. Confirm that you have completed the procedures to obtain the certificates for CA SMP/E Internet Service Retrieval.
  2. Define the necessary FACILITY class profiles to give you access to use the RACDCERT commands:
    • The control levels in increasing strength are NONE, READ, UPDATE, CONTROL, and ALTER.
    • To use the RACDCERT command, you need the appropriate permission to the IRR.DIGTCERT.function profile under the FACILITY class.
      • READ access is required to manipulate your certificates and key rings.
      • UPDATE access is required to manipulate them for other users.
      • CONTROL access is required to manipulate CERTAUTH (certificate authority) certificates.
      Use the following sample RACF RDEFINE, PERMIT, and SETROPTS commands to define necessary FACILITY class profiles. These commands also give you access to use the RACDCERT commands:
      RDEFINE FACILITY IRR.DIGTCERT.ADD UACC(NONE) RDEFINE FACILITY IRR.DIGTCERT.ADDRING UACC(NONE) RDEFINE FACILITY IRR.DIGTCERT.ALTER UACC(NONE) RDEFINE FACILITY IRR.DIGTCERT.CONNECT UACC(NONE) RDEFINE FACILITY IRR.DIGTCERT.LIST UACC(NONE) RDEFINE FACILITY IRR.DIGTCERT.LISTRING UACC(NONE) PERMIT IRR.DIGTCERT.ADD CLASS(FACILITY) ID(userid) ACCESS(READ) PERMIT IRR.DIGTCERT.ADDRING CLASS(FACILITY) ID(userid) ACCESS(READ) PERMIT IRR.DIGTCERT.ALTER CLASS(FACILITY) ID(userid) ACCESS(READ) PERMIT IRR.DIGTCERT.CONNECT CLASS(FACILITY) ID(userid) ACCESS(UPDATE) PERMIT IRR.DIGTCERT.LIST CLASS(FACILITY) ID(userid) ACCESS(READ) PERMIT IRR.DIGTCERT.LISTRING CLASS(FACILITY) ID(userid) ACCESS(READ)
      Give the certificate-owner for the User certificate permissions to read key rings and certificates as shown in the following example:
      PERMIT IRR.DIGTCERT.LIST CLASS(FACILITY) ID(certificate-owner) ACCESS(READ) PERMIT IRR.DIGTCERT.LISTRING CLASS(FACILITY) ID(certificate-owner) ACCESS(READ) SETROPTS RACLIST(FACILITY) REFRESH
      • To connect a certificate authority certificate to your key ring, UPDATE access is required to the IRR.DIGTCERT.CONNECT profile in the FACILITY.
      • To use the SMP/E RECEIVE ORDER command, access is required to the IRR.DIGTCERT.LIST and IRR.DIGTCERT.LISTRING profiles
        only
        . Access to the other profiles is required to create and manipulate key rings and certificates.
    You now have the appropriate access to RADCERT commands.
  3. Create a key ring. A key ring is a named collection of certificates that are associated with a specific user. You can use the same key ring for the CA Automated Order server and CA Download server. If you use the same key ring, SMP/E only requires that you define the key ring with the <ORDERSERVER>. A certificate is identified by its label and the key ring to which it is connected. A key ring must be created using a RACF command similar to the following sample:
    RACDCERT ID(
    ring-owner
    ) ADDRING(
    key-ring-
    name)
    • ring-owner
      Specifies the user ID that owns the key ring.
    • keyringname
      Specifies a unique name for the key ring.
    The key ring is created.
  4. Add the Digicert Intermediate CA certificate to your RACF database:
    RACDCERT CERTAUTH ADD('
    your.mvs.dataset.name
    '
    ) + WITHLABEL('your Digicert CA label') TRUST
    • your.mvs.dataset.name
      Name of the sequential data set that is used to store the uploaded Digicert Intermediate CA certificate.
    The Digicert IntermediateCA certificate is added to your RACF database.
  5. Add the Digicert Root certificate to your RACF database:
    This certificate is required before 11:30 pm EST on February 5, 2021.
    RACDCERT CERTAUTH ADD('
    your.mvs.dataset.name
    '
    ) + WITHLABEL('your Digicert CA label') TRUST
    • your.mvs.dataset.name
      Name of the sequential data set that is used to store the uploaded Digicert Root certificate.
    The Digicert Root certificate is added to your RACF database.
  6. Add the User certificate to your RACF database:
    RACDCERT ID(
    certificate-owner
    ) ADD('
    your.mvs.dataset.name
    ') + WITHLABEL('your User certificate label') TRUST
    • certificate-owner
      Specifies the user ID that you select to own the certificate
    • 'your.mvs.dataset.name'
      Specifies the data set name that is used to store the User certificate package that is obtained from Broadcom Support Online.
    • your User certificate label
      Specifies the label that you opt to identify this User certificate (32 characters or less). For example, SMPE Client Certificate.
  7. Connect the certificates to the key ring:
    Complete this step after you have added the User certificate to the RACF database and after you have verified that the Digicert certificates are in your RACF database.
    RACDCERT ID(
    ring-owner
    ) CONNECT(LABEL('SMPE Client Certificate') + RING(
    keyringname
    ) USAGE(CERTAUTH) ) RACDCERT ID(
    ring-owner
    ) CONNECT( CERTAUTH LABEL('your Digicert CA certificate label') + RING(
    keyringname
    ) USAGE(CERTAUTH) ) RACDCERT ID(
    ring-owner
    ) CONNECT( CERTAUTH LABEL('your Digicert Root certificate label') + RING(
    keyringname
    ) USAGE(CERTAUTH) )
    • LABEL
      Specifies the label that you used in the previous step to identify each certificate.
    • keyringname
      Specifies the name of the key ring you used when you created the key ring.
    • ring-owner
      Specifies the user ID that created the key ring.
    To enable the User certificate to be shared easily by other user IDs without requiring high levels of access for those other user IDs, connect the User certificate to the key ring as a certificate authority (CA) certificate (USAGE of CERTAUTH). This step lets the User certificate be shared without requiring other user IDs to access the certificate’s associated private key.
  8. (Optional) Share a User certificate among multiple user IDs.
    Multiple users can share a single User certificate that is obtained from Broadcom Support. To do so, create a key ring, enable the CA certificate, and add the User certificate to your RACF database as explained in the preceding steps. Assume that user ID USER1 is associated with the key ring and is the owner of the User certificate. To let user ID USER2 share the user certificate, give USER2 permission to read other users’ key rings and certificates. Use the following RACF commands:
    PERMIT IRR.DIGTCERT.LIST CLASS(FACILITY) ID(USER2) ACCESS(READ) PERMIT IRR.DIGTCERT.LISTRING CLASS(FACILITY) ID(USER2) ACCESS(UPDATE) SETROPTS RACLIST(FACILITY) REFRESH
    Permitting USER2 UPDATE access to the IRR.DIGTCERT.LISTRING FACILITY class is not a security exposure. USER2 can read key rings from anyone. However, this access only allows them the ability to extract and use the certificates from the key ring. This access does not allow use of the private keys that are associated with those certificates. Therefore, USER2 cannot masquerade as another user ID.
    After USER2 has the appropriate permission, for USER2 to use the certificate for the SMP/E RECEIVE ORDER command, ensure SMP/E finds the certificate in the correct key ring when running the command. To do this step, USER2 must specify not only the key ring name, but also the user ID associated with the key ring, USER1, on the key ring attribute in the ORDERSERVER data set for the RECEIVE ORDER command as follows:
    keyring="USER1/
    keyringname
    "
You have configured CA SMP/E Internet Service Retrieval.
Go to Define the ORDERSERVER input for RECEIVE ORDER.
(Optional) Post-Configuration Tasks
Complete the following post-configuration tasks as needed.
Debug Key Ring and Certificate Issues
The following RACDCERT commands can be useful if the SMP/E RECEIVE ORDER command detects errors or failures that are related to your key ring or certificates.
For assistance in debugging SMP/E RECEIVE ORDER key ring and certificate issues, contact Broadcom Support and ask for CA ACF2 product support. Provide the list of key rings, list of certificates, and the complete output from the SMP/E RECEIVE ORDER.
Use the following RACDCERT commands to list the key ring and certificates, and to verify their existence and proper attributes.
  • For the key ring:
    1. List the key ring owner and name:
      RACDCERT ID(
      ring-owner
      ) LISTRING(
      keyringname
      )
    2. Verify that all certificates are connected to the key ring with USAGE(CERTAUTH).
    3. Verify that the following parameters are specified with the SMP/E RECEIVE ORDER ORDERSERVER parameter:
      keyring="
      ring-owner
      /
      keyringname
      " certificate="
      certificate label name
      "
  • For the certificate authority (CA) certificates:
    1. List the CA certificates:
      RACDCERT CERTAUTH LIST(LABEL(
      your Digicert CA certificate label
      )) RACDCERT CERTAUTH LIST(LABEL(
      your Digicert Root certificate label
      ))
    2. Verify that the CERTAUTH certificates have
      Status: TRUST
      .
  • For the user certificate:
    1. List the user certificate:
      RACDCERT ID(
      certificate-owner
      ) LIST(LABEL('SMPE Client Certificate
      '
      ))
      certificate-owner
      Specifies the user ID that owns the certificate.
    2. Verify that the user certificate has
      Status: TRUST
      .
    3. Verify that the certificate's
      Subject's Name: CN
      contains the email of the Broadcom Support registered user.
Replace an Expired User Certificate
A User certificate that is obtained from Broadcom Support Online has a finite life span; it expires after one year. The SMP/E RECEIVE ORDER command warns you when the User certificate is going to expire within 30 days. The command fails when the certificate expires. When a certificate expires, replace your existing certificate with a new one. The steps to replace an existing certificate with a new certificate are similar to the steps that you performed when obtaining and adding the first User certificate.
Follow these steps:
  1. Complete the following steps as described in Obtain the Certificates for CA SMP/E Internet Service Retrieval:
    1. Obtain a new user certificate (Import a User Certificate from CA Support Online).
    2. Upload the
      User Certificate
      to z/OS.
  2. Delete the existing User certificate from the RACF database so that you can use the same label for the new User certificate:
    RACDCERT ID(
    certificate-owner
    ) DELETE(LABEL('SMPE Client Certificate
    '
    ))
    certificate-owner
    Specifies the user ID that owns the certificate.
  3. Add the new user certificate and to connect it to your key ring. Follow the steps in Configure RACF.
    You have replaced an expired certificate.
Because the new certificate uses the same label as the existing certificate, no other changes are necessary to ensure that your RECEIVE ORDER command jobs continue to run as expected.
Refresh RACF Classes
After you perform the RACF updates to add certificates and key rings, refresh the in-storage RACF profiles if needed. If you use RACLIST the DIGTCERT and DIGTRING classes, activate them.
SETROPTS CLASSACT(DIGTCERT DIGTRING)
If you have RACLISTed the DIGTCERT or DIGTRING classes, refresh the in-storage profiles before the updates can take effect.
SETROPTS RACLIST(DIGTCERT DIGTRING) REFRESH
If you have not RACLISTed the DIGTCERT or DIGTRING classes, you do not need to refresh the in-storage profiles.
Share a User Certificate among Multiple User IDs
Multiple users can share a single User certificate that is obtained from Broadcom Support Online. To do so, create a key ring, enable the Digicert CA certificate, and add the User certificate to your RACF database as explained in the preceding topics.
Assume that user ID USER1 is associated with the key ring and is the owner of the User certificate. To let user ID USER2 share the user certificate, give USER2 permission to read other user key rings and certificates.
PERMIT IRR.DIGTCERT.LIST CLASS(FACILITY) ID(USER2) ACCESS(READ) PERMIT IRR.DIGTCERT.LISTRING CLASS(FACILITY) ID(USER2) ACCESS(UPDATE)
Permitting USER2 UPDATE access to the IRR.DIGTCERT.LISTRING FACILITY class is not a security exposure. USER2 can read key rings from anyone. This ability only lets USER2 extract and use the certificates from the key ring. This ability does not allow use of the private keys that are associated with those certificates. Therefore, USER2 cannot masquerade as another user ID.
After USER2 has the appropriate permission, for USER2 to use the certificate for the SMP/E RECEIVE ORDER command, ensure that SMP/E finds the certificate in the correct key ring when running the command. To accomplish this task, USER2 must specify not only the key ring name, but also the user ID associated with the key ring, USER1, on the key ring attribute in the ORDERSERVER data set for the RECEIVE ORDER command as follows:
keyring="USER1/
keyringname
"