Create a Certificate and Key Ring in
ACF2

Configure the key ring and generate certificates in
ACF2
to enable the TLS connection between the product and the client browser.
Required roles: security administrator
This article provides instructions for
ACF2
which enables you to generate a key ring and store a certificate in the key ring. The certificate is required to enable TLS encryption between the
Alert Insights
and the Zowe API Mediation Layer. You can Use a Self-signed Certificate that you generate yourself, or you can Use a Certificate Authority to sign a certificate that you generate using
ACF2
.

Prerequisites

  • This article requires that the user is familiar with
    ACF2
    . For more information about available
    ACF2
    commands, see the
    ACF2
    documentation at https://techdocs.broadcom.com/acf2.
  • The user ID that runs the STC for the
    Alert Insights
    . The examples in this article use the CAACPROC user ID.
  • The user ID of the Zowe API ML. The examples in this article use the ZAPIUSER user ID.
  • The name of the Zowe API ML key ring. The examples in this article use the ZAPIRING key ring.
  • The authorization to add certificates to the Zowe API ML keyring.
  • The authorization to add certificates to CERTAUTH ACID.
  • Required privileges to the CASECAUT class to set up the key ring and certificates:
    • ACFCMD.DIGTCERT.ADD - READ access is required for your own user ID. DELETE access is required to add CERTSITE or CERTAUTH certificate.
    • ACFCMD.DIGTCERT.ADDRING - READ access is required for your own user ID. UPDATE access is required to create a key ring for another user ID.
    • ACFCMD.DIGTCERT.CONNECT - READ access is required for your own user ID. DELETE access is required to connect CERTSITE or CERTAUTH certificate.
    • ACFCMD.DIGTCERT.GENCERT - READ access is required for your own user ID. DELETE access is required to sign with CERTSITE or CERTAUTH certificate.
    • ACFCMD.DIGTCERT.GENREQ - READ access is required for your own user ID. DELETE access is required to generate a request based on a CERTSITE or CERTAUTH certificate.
  • Required privileges to the CASECAUT class to read the key ring and certificates:
    • ACFCMD.DIGTCERT.LIST - READ access is required for your user ID. DELETE access is required to list CERTSITE or CERTAUTH certificates.
    • ACFCMD.DIGTCERT.LISTRING - READ access is required for your user ID. UPDATE access is required to list and read key rings for another user ID.
  • (Optional) The knowledge and ability to generate a self-signed certificate.

Use a Self-signed Certificate

In this procedure, you generate a self-signed certificate and a key ring, then connect the certificate to the key ring and your user ID.
  1. Generate the self-signed certificate. This step assumes that you have the knowledge and ability to generate a self-signed certificate.
  2. Generate the key ring.
    Example:
    SET PROFILE(USER) DIV(KEYRING) INSERT CAACPROC.ACCRING RINGNAME(ACCRING)
    The key ring is generated.
  3. Allocate a data set to store your keystore with your self-signed certificate and its private key using the following format:
    RECFM=VB LRECL=84
    .
    Example:
    CAACPROC.KEYSTORE
    The data set that stores your keystore with your self-signed certificate and its private key.
  4. Upload the keystore file to the data set that you allocated in the previous step.
    You have obtained and stored your self-signed certificate.
  5. Add your self-signed certificate to your user ID. Specify the data set that stores your keystore.
    Example:
    SET PROFILE(USER) DIV(CERTDATA) INSERT CAACPROC.KEYSTORE DSNAME('CAACPROC.KEYSTORE') - LABEL(ACCCERT) PASSWORD('
    password
    ') CHANGE CAACPROC.CERT TRUST
    The self-signed certificate is connected to your user ID and paired with a private key.
  6. Add your self-signed certificate to the key ring that you generated in step 2.
    Example:
    In this example, the first reference to the CAACPROC user ID specifies the owner of the key ring. The second reference specifies the owner of the signed certificate.
    SET PROFILE(USER) DIV(KEYRING) CONNECT CERTDATA(CAACPROC.KEYSTORE) KEYRING(CAACPROC.ACCRING) - USAGE(PERSONAL) DEFAULT
    The self-signed certificate is connected to your key ring.
  7. (Conditional) If Zowe API ML is not configured to use key ring, skip this step. Add the self-signed certificate to the Zowe API ML key ring.
    Example:
    SET PROFILE(USER) DIV(KEYRING) CONNECT CERTDATA(CERTAUTH) LABEL(SelfSigned ACC Certificate) - KEYRING(ZAPIUSER.ZAPIRING) USAGE(CERTAUTH)
    The self-signed certificate is connected to the Zowe API ML key ring.
You successfully stored the self-signed certificate in your key ring and the Zowe API ML keyring and connected it to your user ID.

Use a Certificate Authority

In this procedure, you generate a key ring and an unsigned certificate. You also sign the certificate using a Certification Authority of your choice and connect it to the key ring and your user ID.
  1. Generate the key ring.
    Example:
    SET PROFILE(USER) DIV(KEYRING) INSERT CAACPROC.ACCRING RINGNAME(ACCRING)
    The key ring is generated.
  2. Generate the certificate. You specify the common name of the certificate using the CN keyword. You use this common name later to create the required
    Alert Insights
    service account.
    Example:
    SET PROFILE(USER) DIV(CERTDATA) GENCERT CAACPROC.CERT SUBJ(CN='ACCUser' - OU='Mainframe Dept' - O='Example Inc.' L='Pittsburgh' S='Pittsburgh' C='PA') - ALTNAME(DOMAIN=acc.example.com) - LABEL(ACC Certificate unsigned) SIZE(2048) - KEYUSAGE(HANDSHAKE)
    The certificate is generated.
  3. Generate a certificate signing request (CSR) for your certificate.
    Example:
    SET PROFILE(USER) DIV(CERTDATA) GENREQ CAACPROC LABEL(ACC Certificate unsigned) - DSN('ACCRING.CERTU')
    The certificate signing request is generated and stored in the dataset that you specified in the DSN 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.
    You must request that the certificate is signed specifically with extended key usage for ‘Client Authentication’ (OID ‘1.3.6.1.5.5.7.3.2’). Otherwise
    Alert Insights
    does not accept the certificate.
  5. Allocate two datasets to store your signed certificate and the root certificate. Use the same format as the output data set in step 2 (CAACPROC.CERTU):
    RECFM=VB LRECL=84
    .
    If the Certificate Authority also provides the intermediate certificates, allocate extra data sets to store the intermediate certificates.
    Example:
    CAACPROC.CERT
    The data set that stores your signed certificate
    CAACPROC.ROOTCERT
    The data set that stores the root certificate
    (Conditional) CAACPROC.INTCERT
    The data set that stores the intermediate certificate
  6. Upload the signed certificate files to the data sets allocated in the previous step.
    You have obtained and stored your signed certificate and a root certificate.
  7. Add your signed certificate to your user ID. Specify the data set that stores your signed certificate.
    Example:
    SET PROFILE(USER) DIV(CERTDATA) INSERT CAACPROC.CERT DSNAME('CAACPROC.CERT') - LABEL(ACCCERT) CHANGE CAACPROC.CERT TRUST
    The certificate is connected to your user ID and paired with a private key.
  8. Add your signed certificate to the key ring that you generated in step 1.
    Example:
    In this example, the first reference to the CAACPROC user ID specifies the owner of the key ring. The second reference specifies the owner of the signed certificate.
    SET PROFILE(USER) DIV(KEYRING) CONNECT CERTDATA(CAACPROC.CERT) KEYRING(CAACPROC.ACCRING) - USAGE(PERSONAL) DEFAULT
    The signed certificate is connected to your key ring.
  9. 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:
    SET PROFILE(USER) DIV(CERTDATA) INSERT CERTAUTH.DIGICERT DSNAME('ACCRING.ROOTCERT') - LABEL(DigiCert Global Root CA) TRUST
    The root CA certificate is connected to the CERTAUTH ACID.
  10. Add the root CA certificate to your key ring.
    Example:
    SET PROFILE(USER) DIV(KEYRING) CONNECT CERTDATA(CERTAUTH) LABEL(DigiCert Global Root CA) - KEYRING(CAACPROC.ACCRING) USAGE(CERTAUTH)
    The root CA certificate is connected to your key ring.
  11. (Conditional) If Zowe API ML is not configured to use key ring, skip this step. Add the root CA certificate to the Zowe API ML key ring.
    Example:
    SET PROFILE(USER) DIV(KEYRING) CONNECT CERTDATA(CERTAUTH) LABEL(DigiCert Global Root CA) - KEYRING(ZAPIUSER.ZAPIRING) USAGE(CERTAUTH)
    The root CA certificate is connected to the Zowe API ML key ring.
  12. (Conditional) If you received intermediate certificates, repeat steps 3, 4 and 5 to add the intermediate certificates to the CERTAUTH ACID, your key ring and the Zowe API ML key ring. Specify the appropriate data sets that contain the intermediate certificates.
You successfully stored the certificates in your key ring and the Zowe API ML keyring and connected them to your user ID and to the CERTAUTH ACID.

List the Key Ring Content

To list the certificates owned by a user ID, use the following
ACF2
command:
Example:
SET PROFILE(USER) DIV(CERTDATA) LIST LIKE(CAACPROC.-)
A list of certificates assigned to the user ID appears.
CERTDATA / CAACPROC.CERT LAST CHANGED BY USER04 ON 06/02/21-07:24 CERTNSER(0000000000000001) ISSUERDN(CN=GeoTrust RSA CA 201 8.OU=www.digicert.com.O=DigiCert Inc.C=US) KEYSIZE(2,048) LABEL(Topology Certificate) SERIAL#(0123456789ABCDEF0123456789ABCDEF) SUBJDN(CN=abcd.a bc.mycmpny.net.O=MyCompany Inc.L=San Jose.ST=California.C= US) TRUST The certificate is connected to the following key rings: Key ring record: CAACPROC.ACCRING Key ring name: MYRING