Configure CA Top Secret Security

Configure CA Top Secret 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 CA Top Secret commands are provided. For detailed command information, see the CA Top Secret for z/OS documentation.
cmcm
Configure CA Top Secret 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 CA Top Secret commands are provided. For detailed command information, see the CA Top Secret for z/OS documentation.
Before you begin changing your CA Top Secret database, ensure that your user ID is authorized to manipulate certificates and key rings.
2
Configure CA Top Secret
Use the following procedure to configure CA Top Secret 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. Create a CA Top Secret key ring.
    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 key ring is a named collection of certificates that are associated with a specific user. A certificate is identified by its label and the key ring to which it is connected.
    TSS ADD(
    user1
    ) KEYRING(SMPERING) LABLRING(
    lablring
    )
    • KEYRING(
      yourRingName
      )
      Specifies the key ring being added to the user's ACID. An individual ACID can be a member of more than one key ring.
      Limits:
      Up to eight characters.
      Example:
      SMPERING
    • lablring
      Specifies the label to be associated with the key ring being added to the user. This label is used as an identifier of the digital certificate code and must be unique for the key ring.
      Limits:
      Up to 327 characters
    The key ring is created.
  3. Add the Digicert Intermediate CA certificate to your CA Top Secret database:
    TSS ADD(CERTAUTH) DIGICERT(
    yourDigicertCAIntercertname
    ) LABLCERT(
    yourlabelname
    ) - DCDSN('
    your.mvs.dataset.name
    ') TRUST
    • DIGICERT(
      yourDigicertCAIntercertname
      )
      Specifies a case-sensitive ID that identifies the Digicert Intermediate CA certificate with the user ACID.
      Limits:
      Up to eight characters
      Example:
      SERVER
    • LABLCERT(
      yourlabelname
      )
      Specifies a label to be associated with the Digicert Intermediate CA certificate being added to the user. If single quotation marks are used, spaces are allowed. This label is used as an identifier and must be unique for the individual user. If you do not specify a label, this value defaults to the value specified for DIGICERT.
      Limits:
      31 case-sensitive characters
      Example:
      SERVER
    • '
      your.mvs.dataset.name
      '
      Specifies the name of the data set where the Digicert Intermediate CA certificate was uploaded.
      If you receive this message:
      TSS1573I THE CERTIFICATE <
      yourDigicertCAIntercertname
      > SIGNER NOT FOUND. ADDING CERTIFICATE WITH NOTRUST STATUS
      Issue the following command:
      TSS REPLACE(
      user1
      ) DIGICERT(
      yourDigicertCAIntercertname
      ) TRUST
    The Digicert Intermediate CA certificate has been added to your CA Top Secret database.
  4. Add the Digicert Root certificate to your CA Top Secret database:
    This certificate is required before 11:30 pm EST on February 5, 2021.
    TSS ADD(CERTAUTH) DIGICERT(
    yourDigicertCARootcertname
    ) LABLCERT(
    yourlabelname
    ) - DCDSN('
    your.mvs.dataset.name
    ') TRUST
    • DIGICERT(
      yourDigicertRootcertname
      )
      Specifies a case-sensitive ID that identifies the Digicert Root certificate with the user ACID.
      Limits:
      Up to eight characters
      Example:
      SERVER
    • LABLCERT(
      yourlabelname
      )
      Specifies a label to be associated with the Digicert Root certificate being added to the user. If single quotation marks are used, spaces are allowed. This label is used as an identifier and must be unique for the individual user. If you do not specify a label, this value defaults to the value specified for DIGICERT.
      Limits:
      31 case-sensitive characters
      Example:
      SERVER
    • '
      your.mvs.dataset.name
      '
      Specifies the name of the data set where the Digicert Root certificate was uploaded.
      If you receive this message:
      TSS1573I THE CERTIFICATE <
      yourDigicertCARootcertname
      > SIGNER NOT FOUND. ADDING CERTIFICATE WITH NOTRUST STATUS
      Issue the following command:
      TSS REPLACE(
      user1
      ) DIGICERT(
      yourDigicertCARootcertname
      ) TRUST
    The Digicert Root certificate has been added to your CA Top Secret database.
  5. Add the User certificate to your CA Top Secret database:
    TSS ADD(
    user1
    ) DIGICERT(
    yourUsercertname
    ) LABLCERT(
    yourlabelname
    ) - DCDSN('
    your.mvs.dataset.name
    ') TRUST
    • DIGITCERT(yourUsercertname)
      Specifies a case-sensitive ID that identifies the User certificate with the user ACID.
      Length:
      1 to 8 characters
      Example:
      USERCERT
    • LABLCERT(
      yourlabelname
      )
      Specifies a label to be associated with the User certificate being added to the user.
      Limits:
      32 case-sensitive characters
      Example:
      SMPE Client Certificate
    • '
      your.mvs.dataset.name
      '
      Specifies the name of the data set where the User certificate was uploaded.
      If you receive this message:
      TSS1573I THE CERTIFICATE <
      yourUsercertname
      > SIGNER NOT FOUND. ADDING CERTIFICATE WITH NOTRUST STATUS
      Issue the following command:
      TSS REPLACE(
      user1
      ) DIGICERT(
      yourUsercertname
      ) TRUST
    The User certificate has been added to your CA Top Secret database.
  6. Connect the Digicert certificates and User certificate to your key ring:
    TSS ADD(
    user1
    ) KEYRING(
    yourRingName
    ) RINGDATA(CERTAUTH,
    yourDigicertCAIntercertname
    ) - USAGE(CERTAUTH)
    TSS ADD(
    user1
    ) KEYRING(
    yourRingName
    ) RINGDATA(CERTAUTH,
    yourDigicertCARootcertname
    ) - USAGE(CERTAUTH)
    TSS ADD(
    user1
    ) KEYRING(
    yourRingName
    ) RINGDATA(
    user1,
    yourUsercertname
    ) - USAGE(CERTAUTH)
    The KEYRING should match the key ring that is specified on the TSS ADD command.
  7. Grant user permissions for shared and non-shared certificates:
    • Non-Shared Certificates
      :
      Give user1 permission to read key rings and certificates as shown in this example:
      TSS PER(
      user1
      ) IBMFAC(IRR.DIGTCERT.LIST) ACC(READ) TSS PER(
      user1
      ) IBMFAC(IRR.DIGTCERT.LISTRING) ACC(READ)
      Repeat all previous steps for each additional user certificate. Each user must have a key ring with their user certificate and the Digicert certificates. Ensure that SMP/E finds the certificates in the correct key ring when executing the RECEIVE ORDER command.
    • Shared Certificates
      :
      Give user2 permission to read other user key rings and certificates as shown in this example:
      TSS PER(
      user2
      ) IBMFAC(IRR.DIGTCERT.LIST) ACC(READ) TSS PER(
      user2
      ) IBMFAC(IRR.DIGTCERT.LISTRING) ACC(UPDATE)
      Ensure that SMP/E finds the certificates in the correct key ring when executing the RECEIVE ORDER command. To do this step, user2 must specify not only the key ring name, but also the userid that is associated with the key ring, user1, on the key ring attribute in the ORDERSERVER data set (within CA SMP/E Internet Service Retrieval) as follows:
      keyring="
      user1
      /SMPE_USER_KEYRING"
      The ring name must match (name and case) the LABLRING specified in the TSS ADD command.
    The user permissions for the certificates are defined.
You have configured CA SMP/E Internet Service Retrieval.
(Optional) Post-Configuration Tasks
Complete these post-configuration tasks as needed.
Debug Key Ring and Certificate Issues
The following TSS 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 issues with key rings and certificates, contact Broadcom Support and ask for CA Top Secret product support. Provide the list of key rings, list of certificates, and the complete output from the SMP/E RECEIVE ORDER.
Use the following TSS 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:
      TSS LIST(USER01) LABLRING(
      ringname
      ) LIST
      user1.ring
      (USER01 is the ACID that created and owns the keyring USER01)
    2. Verify that all certificates are connected to the key ring with USAGE(CERTAUTH).
    3. Verify that the following parameters (key ring owner, key ring name, and label) are specified with the SMP/E RECEIVE ORDER ORDERSERVER parameter:
      keyring="
      USER01
      /
      ringname
      " certificate="
      label
      "
  • For the certificate authority (CA) certificates:
    1. List the CA certificates:
      TSS LIST(CERTAUTH) DIGICERT(
      yourDigicertCAIntercertname
      ) TSS LIST(CERTAUTH) DIGICERT(
      yourDigicertCARootcertname
      )
    2. Verify that the CERTAUTH certificates have
      Status = TRUST
      .
  • For the user certificate:
    1. List the user certificate:
      TSS LIST(user1) DIGICERT(
      yourUsercertname
      )
    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 gives you 30 days notice when the User certificate is about to expire. 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 one 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 Broadcom Support Online).
    2. Upload the User Certificate to z/OS.
  2. Delete the existing User certificate from the CA Top Secret database so that you can use the same label for the new User certificate:
    TSS REMOVE(
    owningacid
    ) DIGICERT(
    olddigicertname
    )
  3. Add the new User certificate and connect it to your key ring. Follow the steps at the beginning of this article in Configure CA Top Secret.
    The expired certificate is replaced.
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.