Create a Key Ring and Certificates in ACF2
Create a Key Ring and Certificates in
ACF2
Configure the key ring and generate certificates in
ACF2
to enable the TLS connection between Topology
and the client browser.Required roles: security administrator |
|---|
This article provides instructions for
ACF2
which enable you to generate a key ring and store a certificate in the key ring. The 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 withACF2. For more information about availableACF2commands, see theACF2documentation at https://techdocs.broadcom.com/acf2.
- The user ID that runs the STC for theTopologyAPI server. The examples in this article use the TPLSTC user ID, according to the instructions for the requiredTopologyuser IDs.
- The authorization to add certificates to CERTAUTH logonid.
- 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. CONTROL 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. CONTROL access is required to connect CERTSITE or CERTAUTH certificate.
- ACFCMD.DIGTCERT.GENCERT - READ access is required for your own user ID. CONTROL access is required to sign with CERTSITE or CERTAUTH certificate.
- ACFCMD.DIGTCERT.GENREQ - READ access is required for your own user ID. CONTROL access is required to generate a request based on 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. CONTROL 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.
For more information, see Administer Digital Certificate Authorizations.
Generate the Key Ring and the Certificate
In this procedure, you first generate a key ring and an unsigned certificate, then you sign the certificate using a Certification Authority of your choice.
- Generate the key ring.Example:SET PROFILE(USER) DIV(KEYRING) INSERT TPLSTC.TOPORING RINGNAME(TOPORING)The key ring is generated.
- Generate the certificate.Example:SET PROFILE(USER) DIV(CERTDATA) GENCERT TPLSTC.CERT SUBJ(CN='topology.example.com' - OU='Mainframe Dept' - O='Example Inc.' L='Prague' S='Prague' C='CZ') - ALTNAME(DOMAIN=topology.example.com) - LABEL(Topology Certificate unsigned) SIZE(2048) - KEYUSAGE(HANDSHAKE)The certificate is generated.
- Generate a certificate signing request (CSR) for your certificate.Example:SET PROFILE(USER) DIV(CERTDATA) GENREQ TPLSTC LABEL(Topology Certificate unsigned) - DSN('TOPORING.CERTU')The certificate signing request is generated and stored in the data set that you specified in the DSN parameter.
- 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.
- 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
- 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
- Add your signed certificate to your user ID. Specify the data set that stores your signed certificate.Example:SET PROFILE(USER) DIV(CERTDATA) INSERT TPLSTC.CERT DSNAME('TOPORING.CERT') - LABEL(Topology Certificate) CHANGE TPLSTC.CERT TRUSTThe certificate is connected to your user ID and paired with a private key.
- 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.SET PROFILE(USER) DIV(KEYRING) CONNECT CERTDATA(TPLSTC.CERT) KEYRING(TPLSTC.TOPORING) - USAGE(PERSONAL) DEFAULTThe signed certificate is connected to your key ring.
- Connect the root CA certificate to the CERTAUTH logonid.If the root certificate is already connected to CERTAUTH logonid, you can skip this step.Example:SET PROFILE(USER) DIV(CERTDATA) INSERT CERTAUTH.DIGICERT DSNAME('TOPORING.ROOTCERT') - LABEL(DigiCert Global Root CA) TRUSTThe root CA certificate is connected to the CERTAUTH logonid.
- Add the root CA certificate to your key ring.Example:SET PROFILE(USER) DIV(KEYRING) CONNECT CERTDATA(CERTAUTH) LABEL(DigiCert Global Root CA) - KEYRING(TPLSTC.TOPORING) USAGE(CERTAUTH)The root CA certificate is connected to your key ring.
- (Optional) If you received intermediate certificates, repeat steps 3 and 4 to add the intermediate certificates to the CERTAUTH logonid and to your key ring. Specify the appropriate data sets that contain the intermediate certificates.
- Ensure that the Topology API Server can read the key ring attached to the TPLSTC user ID under which it is executing. The followingACF2rule enables the reading.Example:SET RESOURCE(FAC) RECKEY IRR ADD(DIGTCERT.LISTRING USER(TPLSTC) ALLOW)
- Refresh the access tables for FACILITY class by using the following system command:F ACF2,REBUILD(FAC)
You successfully stored the certificates in your key ring and connected them to your user ID and to the CERTAUTH logonid.
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(TPLSTC.-)
A list of certificates assigned to the user ID appears.
CERTDATA / TPLSTC.CERT LAST CHANGED BY USER00 ON 06/02/21-07:24 CERTNSER(0000000000000000) ISSUERDN(CN=Company.OU=www.company.com.O=Company Inc.C=US) KEYSIZE(2,048) LABEL(Topology Certificate) SERIAL#(000A00A000A00A000A00A000A00A0) SUBJDN(CN=m10h.b pc.company.net.O=Company Inc.L=City.ST=State.C= US) TRUST Certificate is connected to the following key rings: Key ring record: TPLSTC.TOPORING Key ring name: TOPORING