Configure
Top Secret
Security

Configure
Top Secret
security to enable use of the SMP/E RECEIVE ORDER command.
cmcm
Configure
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
Broadcom
Automated Order server and Digicert certificates are required. Sample
Top Secret
commands are provided. For detailed command information, see the
Top Secret
for z/OS documentation.
Before you begin changing your
Top Secret
database, ensure that your user ID is authorized to manipulate certificates and keyrings.
2
Configure
Top Secret
Use the following procedure to configure
Top Secret
security for the server certificates.
  1. Confirm that you have completed the procedures to obtain the certificates for
    SMP/E Internet Service Retrieval
    .
  2. Create a
    Top Secret
    keyring.
    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 keyring is a named collection of certificates that are associated with a specific user. A certificate is identified by its label and the keyring to which it is connected.
    TSS ADD(
    user1
    ) KEYRING(SMPERING) LABLRING(
    lablring
    )
    • KEYRING(
      yourRingName
      )
      Specifies the keyring being added to the user's ACID. An individual ACID can be a member of more than one keyring.
      Limits:
      Up to eight characters.
      Example:
      SMPERING
    • lablring
      Specifies the label to be associated with the keyring being added to the user. This label is used as an identifier of the digital certificate code and must be unique for the keyring.
      Limits:
      Up to 327 characters
    The keyring is created.
  3. Add the Digicert Intermediate CA certificate to your
    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
    Top Secret
    database.
  4. Add the Digicert Root certificate to your
    Top Secret
    database:
    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
    Top Secret
    database.
  5. Add the User certificate to your
    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
    Top Secret
    database.
  6. Connect the Digicert certificates and User certificate to your keyring:
    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 keyring 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 keyrings 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 keyring with their user certificate and the Digicert certificates. Ensure that SMP/E finds the certificates in the correct keyring when executing the RECEIVE ORDER command.
    • Shared Certificates
      :
      Give user2 permission to read other user keyrings 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 keyring when executing the RECEIVE ORDER command. To do this step, user2 must specify not only the keyring name, but also the userid that is associated with the keyring, user1, on the keyring attribute in the ORDERSERVER data set (within
      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
SMP/E Internet Service Retrieval
.
(Optional) Post-Configuration Tasks
Complete these post-configuration tasks as needed.
Debug Keyring 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 keyring or certificates.
For assistance in debugging SMP/E RECEIVE ORDER issues with keyrings and certificates, contact Broadcom Support and ask for
Top Secret
product support. Provide the list of keyrings, list of certificates, and the complete output from the SMP/E RECEIVE ORDER.
Use the following TSS 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:
      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 keyring with USAGE(CERTAUTH).
    3. Verify that the following parameters (keyring owner, keyring 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. This certificate 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.
  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 Online).
    2. Upload the User Certificate to z/OS.
  2. Delete the existing User certificate from the
    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 keyring. Follow the steps at the beginning of this article in Configure
    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.