Configure IBM RACF Security

Configure IBM RACF security to enable use of the SMP/E RECEIVE ORDER command.
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
Broadcom
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.
  1. Confirm that you have completed the procedures to obtain the certificates for
    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 keyrings.
      • 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 keyrings 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 keyring, 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 keyrings and certificates.
    You now have the appropriate access to RADCERT commands.
  3. Create a keyring. A keyring is a named collection of certificates that are associated with a specific user. You can use the same keyring for the
    Broadcom
    Automated Order server and
    Broadcom
    Download server. If you use the same keyring, SMP/E only requires that you define the keyring with the <ORDERSERVER>. A certificate is identified by its label and the keyring to which it is connected. A keyring 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 keyring.
    • keyringname
      Specifies a unique name for the keyring.
    The keyring 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:
    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 keyring:
    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 keyring you used when you created the keyring.
    • ring-owner
      Specifies the user ID that created the keyring.
    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 keyring 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 keyring, 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 keyring and is the owner of the User certificate. To let user ID USER2 share the user certificate, give USER2 permission to read other users’ keyrings 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 keyrings from anyone. However, this access only allows them the ability to extract and use the certificates from the keyring. 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 keyring when running the command. To do this step, USER2 must specify not only the keyring name, but also the user ID associated with the keyring, USER1, on the keyring attribute in the ORDERSERVER data set for the RECEIVE ORDER command as follows:
    keyring="USER1/
    keyringname
    "
You have configured
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 Keyring 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 keyring or certificates.
For assistance in debugging SMP/E RECEIVE ORDER keyring and certificate issues, contact Broadcom Support and ask for
ACF2
product support. Provide the list of keyrings, list of certificates, and the complete output from the SMP/E RECEIVE ORDER.
Use the following RACDCERT commands to list the keyring and certificates, and to verify their existence and proper attributes.
  • For the keyring:
    1. List the keyring owner and name:
      RACDCERT ID(
      ring-owner
      ) LISTRING(
      keyringname
      )
    2. Verify that all certificates are connected to the keyring 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.
  1. Complete the following steps as described in Obtain the Certificates for
    SMP/E Internet Service Retrieval
    :
    1. Obtain a new user certificate (Import a User Certificate from
      Broadcom Support
      ).
    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 keyring. 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 keyrings, 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 keyring, 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 keyring and is the owner of the User certificate. To let user ID USER2 share the user certificate, give USER2 permission to read other user keyrings 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 keyrings from anyone. This ability only lets USER2 extract and use the certificates from the keyring. 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 keyring when running the command. To accomplish this task, USER2 must specify not only the keyring name, but also the user ID associated with the keyring, USER1, on the keyring attribute in the ORDERSERVER data set for the RECEIVE ORDER command as follows:
keyring="USER1/
keyringname
"