Create a Key Ring and Certificates in
Top Secret

Configure the key ring and generate certificates in
Top Secret
to enable the TLS connection between
Topology
and the client browser.
Required roles: security administrator
This article provides instructions for
Top Secret
that enable you to generate a key ring and store a certificate in the key ring. This certificate is required to enable TLS encryption between
Topology
and the client browser.

Generate a Key Ring and Connect a Certificate

A key ring (also known as z/OS key ring or SAF key ring) is a collection of digital certificates that are associated with an individual user. Key rings provide enhanced security over file key stores because they are managed and protected by an external security manager.

Prerequisites

  • This article requires that the user is familiar with
    Top Secret
    . For more information about available
    Top Secret
    commands, see the
    Top Secret
    documentation at https://techdocs.broadcom.com/topsecret.
  • The user ID that runs the STC for the
    Topology
    API server. The examples in this article use the TPLSTC user ID, according to the instructions for the required
    Topology
    user IDs.
  • The authorization to add certificates to CERTAUTH ACID.
  • Administrative authority to set up the key ring and certificates:
    MISC4(ALL)
    All the certificate operation
    MISC4(CERTUSER)
    Maintain user certificates
    MISC4(CERTAUTH)
    Maintain CERTAUTH certificates
    MISC4(CERTSITE)
    Maintain CERTSITE certificates
    MISC4(CERTLIST)
    List the certificate information
    MISC4(CERTGEN)
    Generate the certificate
    MISC4(CERTCHEK)
    Display information about certificates
    MISC4(CERTEXPO)
    Export digital certificates.
    Alternatively, use the CASECAUT authority to administer certificates to individual users. For more information see Restricted Administrative Authorities (CASECAUT Resource Class).

Generate the Key Ring and the Certificate

In this procedure, you generate a key ring and an unsigned certificate, then you sign the certificate using a Certification Authority of your choice.
  1. Generate the key ring.
    Example:
    TSS ADD(TPLSTC) KEYRING(TOPORING)
    The key ring is generated.
  2. Generate the certificate.
    Example:
    TSS GENCERT(TPLSTC) DIGICERT(TPLCERTU) SUBJECTN('CN="CA Topology" OU="Mainframe Dept" O="Example Inc." L="Prague" ST="Prague" C="CZ"') KEYSIZE(2048) KEYUSAGE(HANDSHAKE) LABLCERT('Topology Certificate unsigned') ALTNAME('DOMAIN=topology.example.com')
    The certificate is generated.
  3. Generate a certificate signing request (CSR) for your certificate.
    Example:
    TSS GENREQ(TPLSTC) DIGICERT(TPLCERTU) DCDSN('TOPORING.CERTU')
    The certificate signing request is generated and stored in the data set that you specified in the DCDSN parameter.
  4. Download the CSR from the data set generated in step 3 and send it to a Certificate Authority (CA). The CA signs your request, encrypts it with a private key, and sends you a validated certificate. The CA also sends you a root CA certificate and, sometimes, one or more intermediate certificates.
  5. Allocate two data sets to store your signed certificate and the root certificate. Use the same format as the output data set in step 2 (TOPORING.CERTU):
    RECFM=VB LRECL=84
    .
    If the Certificate Authority provides also the intermediate certificates, allocate extra data sets to store the intermediate certificates.
    Example:
    TOPORING.CERT
    The data set that stores your signed certificate
    TOPORING.ROOTCERT
    The data set that stores the root certificate
    (Optional) TOPORING.INTCERT
    The data set that stores the intermediate certificate
  6. Upload the signed certificate files to the data sets allocated in step 5.
You have obtained and stored your signed certificate and a root certificate.

Connect the Signed Certificates to the Key Ring and the IDs

  1. Add your signed certificate to your user ID. Specify the data set that stores your signed certificate.
    Example:
    TSS ADD(TPLSTC) DIGICERT(TPLCERT) LABLCERT('Topology Certificate') DCDSN('TOPORING.CERT') TRUST
    The certificate is connected to your user ID and paired with a private key.
  2. Add your signed certificate to the key ring that you generated in step 1 of the previous procedure.
    Example:
    In this example, the first reference to the TPLSTC user ID specifies the owner of the key ring. The second reference specifies the owner of the signed certificate.
    TSS ADD(TPLSTC) KEYRING(TOPORING) RINGDATA(TPLSTC,TPLCERT) USAGE(PERSONAL) DEFAULT
    The signed certificate is connected to your key ring.
  3. Connect the root CA certificate to the CERTAUTH ACID.
    If the root certificate is already connected to CERTAUTH ACID, you can skip this step.
    Example:
    TSS ADD(CERTAUTH) DIGICERT(ROOTCERT) LABLCERT('DigiCert Global Root CA') DCDSN('TOPORING.ROOTCERT') TRUST
    The root CA certificate is connected to the CERTAUTH ACID.
  4. Add the root CA certificate to your key ring.
    Example:
    TSS ADD(TPLSTC) KEYRING(TOPORING) RINGDATA(CERTAUTH,ROOTCERT) USAGE(CERTAUTH)
    The root CA certificate is connected to your key ring.
  5. (Optional) If you received intermediate certificates, repeat steps 3 and 4 to add the intermediate certificates to the CERTAUTH ACID and to your key ring. Specify the appropriate data sets that contain the intermediate certificates.

List the Key Ring Content

To list the certificates owned by a user ID, use the following
Top Secret
command:
Example:
TSS LIST(TPLSTC) DIGICERT(ALL)
A list of certificates assigned to the user TPLSTC appears.
DIGICERT = TPLCERT ACCESSORID = TPLSTC ADMIN BY= BY(ADMIN ) SMFID(M10H) ON(05/07/2021) AT(11:01:13) LABEL = Topology Certificate STATUS = TRUST SERIAL# = 000A00A000A00A000A00A000A00A0 ISSUER DISTINGUISHED NAME: .CN=Company.OU=www.company.com.O=Company In - c.C=US SUBJECT DISTINGUISHED NAME: CN=*.company.net.O=Company Inc.L=City.ST=State. - C=US DOMAIN NAME: *.company.net KEYUSAGE: HANDSHAKE PRIVATE KEY SIZE = 2048 PRIVATE KEY TYPE = RSA ALGORITHM = sha256WithRSAEncryption NOT BEFORE = 2021/05/07 00:00:00 UTC NOT AFTER = 2022/05/12 23:59:59 UTC CERTIFICATE WAS SIGNED BY: ACID(CERTAUTH) DIGICERT(DCCACERT) CERTIFICATE IS CONNECTED TO THE FOLLOWING KEYRINGS: ACID(TPLSTC ) KEYRING(TOPORING)