ACF2 support for setting up the keyrings and certificates needed for a typical SSL/TLS applications (e.g. FTP, CICS, DB2, TCP/IP, TN3270)
Article ID: 27722
Updated On:
Products
Issue/Introduction
ACF2 support for setting up the keyrings and certificates needed for a typical SSL/TLS application (e.g. FTP, CICS, DB2, TCP/IP, TN3270).
Resolution
This section covers how to generate certificates, set up keyrings, and connect the certificates to the keyrings. This scenario we will set up certificates and keyrings for a basic client/server FTP handshake, using Transport Layer Security (TLS). This example uses the FTP application however the setup would be the same for other applications such as CICS, DB2, TCP/IP, TN3270 etc. There are many ways to use digital certificates and this section will not apply to all situations.
Table of Contents
Acronyms
There are four acronyms that are frequently encountered when working with keyrings and certificates: Secure Sockets Layer (SSL), Transport Layer Security (TLS), Global Security Kit (GSK), and Public Key Cryptography Standards (PKCS). SSL built upon GSK functions, and TLS built upon SSL. This example will refer to SSL and TLS only. The PKCS value identifies the standards used in building the certificates.
Handshaking
SSL is a protocol that provides privacy and integrity for communications. It is used by Webservers, LDAP, Host-on-Demand, and other applications. Certificates are used to establish an SSL handshake between a client and server as follows:
- The client issues a secure session request.
- The server sends certificate containing server's public key.
- The client authenticates certificate against a list of known Certification Authorities (CA).
- The client generates a session key, encrypts it using the server's public key and sends the encrypted session key to the server.
- The server decrypts the session key. Client and server now both have the encrypted key and use it to encrypt end-user data for the duration of the session.
Keyrings
The application will make USS R_datalib (the interface to external security for the purpose of retrieving certificates and keys) service requests to retrieve certificates on a particular keyring. The keyring name is specified in one of the application's setup options or parameter files. Every application using SSL or TLS provides an option that identifies its keyring name. For FTP, the keyring name is specified in the FTP.DATA option KEYRING.
You must define the keyring and the certificates to ACF2 so ACF2 can retrieve them when they are requested. The ACF2 records are KEYRING and CERTDATA USER profile records stored on the INFOSTG database.
Keyring Ownership
In order for the correct keyring to be found, the KEYRING record in ACF2 must have as its owner id the logonid being used by the application address space making the request unless the keyring is being shared. The relationship between the address space logonid and its KEYRING records is called ownership.
As an example of ownership, if the ACF9CCCD message in the FTPD address space identifies the assigned logonid as "FTPD", this would be the first level qualifier of the record id for the associated KEYRING record(s). Identify the keyring name in FTP by setting KEYRING FTPRING in FPT.DATA. Then define the KEYRING record to ACF2.
Example: Define KEYRING record to ACF2
ACF
SET PROFILE(USER) DIV(KEYRING)
INSERT FTPD.RING1 RINGNAME (FTPRING)
Where FTPD.RING1 is the record id and FTPRING is the ringname defined in the FTP.DATA KEYRING option.
Important! The RINGNAME is case sensitive. Be sure you use the same case in the KEYRING record RINGNAME operand as in the application option.
Note on Shared Keyrings: If a logonid other than FTPD was used for ownership of the keyring, for example the record name was FTPD1.RING1 instead of FTPD.RING1, this would be considered a shared keyring since the address space logonid, FTPD, is no longer the owner of the KEYRING. In order for the r_datalib call from the application to find the FTPD1.RING1 keyring, the KEYRING parameter in FTP.DATA would need to be modified to conform to the syntax logonid/ringname. For example, FTPD1/FTPRING would need to be specified. Not all SSL/TLS applications support this syntax, nor do they support shared keyrings. Please review the product documentation for the application using the KEYRING to verify shared keyrings are supported.
Since there can be multiple keyrings for an address space, ACF2 searches through all KEYRING records for FTPD.xxxxxxxx until it finds the one that has the RINGNAME that matches the ringname in the R_datalib call. That is the keyring that must contain all the certificates the application is going to need.
The application reads all the certificates on this keyring, then searches for its own certificate among them. Its certificate will be in a CERTDATA record that has a record id that is the same as the address space id, just as it was for the keyring. In our FTP example, it is FTPD.CERT1. The FTPD is required to establish the application's ownership of the certificate, and the suffix CERT1 is optional and can be anything suffix that a site chooses. For details on certificate ownership and access to a certificate's Private Key, see Certificate Private Key Access.
Validations for Keyrings
There are two checks made for a user's access to a Keyring. These resource checks are driven by Unix System Services(USS) IRRSDL00 R_datalib READ functions, that are DataGetFirst, DataGetNext, and GetUpdateCode.
- The resource <ringOwner>.<ringName>.LST in the Resource class RDATALIB is checked first. This resource check is ring-specific profile checking, a resource with the format <ringOwner>.<ringName>.LST is used to provide access control to a specific keyring(ringname). READ access is required for any user ID that needs access to the keyring. This includes the keyring owner and/or any user ID that is sharing the keyring.
- If access is not allowed based on ring-specific profile checking, the resource IRR.DIGTCERT.LISTRING in the Resource class FACILITY is checked. This resource check is Global profile checking. The following IRR.DIGTCERT class FACILITY resources are checked.
Resource: IRR.DIGTCERT.LISTRING Access: READ Enables the caller to use the DataGetFirst and the CSSM_TP_CertGroupVerify functions to retrieve the contents of a key ring that is associated with the user's own user ID.
Resource: IRR.DIGTCERT.LISTRING Access: UPDATE Enables the caller to use the DataGetFirst and the CSSM_TP_CertGroupVerify functions to retrieve the contents of a key ring that is associated with another user's user ID(Shared Keyring).
Resource: IRR.DIGTCERT.LIST Access: READ Enables the caller to use the CertGroupVerify(ACF2 CHKCERT subcommand or SAFCRRPT Certificate Utility) function. (This CheckStatus function verifies a certificate chain, based on the Certificate Authorities and SITE certificates that are contained within the key ring.)
Certificate Private Key Access
Access to a certificate's private key. Application can use the Unix System Services (USS) R_datalib callable service (IRRSDL00) to extract the private keys from certain certificates (User/Personal/Server/Client).
An application can extract the private key from a user certificate if the following conditions are met:
- The certificate is connected to it's keyring with the PERSONAL usage option.
- One of the following two conditions is true:
- The caller's user ID (ACF2 logonid) is the user ID associated with the certificate (owner).
- The caller's user ID (logonid) has READ or UPDATE authority to the <ringOwner>.<ringName>.LST resource in the RDATALIB class. READ will return the certificate owner's private key, UPDATE will return the private key of a certificate owned by another user ID (logonid).
- For a SITECERT (or CERTAUTH) certificate with USAGE(PERSONAL) the private key can be shared by giving users DELETE access to the IRR.DIGTCERT.GENCERT resource within the FACILITY class or UPDATE access to the <ringOwner>.<ringName>.LST resource in the RDATALIB class.
Signing Certificates
Signing certificates(CERTAUTH) can be created by either a Local CA or an External CA.
Local CA
Sites that are going to act as their own Local CA will need to define that signing (CERTAUTH) certificate, as well as the Personal certificate for FTPD.
ACF
GENCERT CERTAUTH.SIGNER SUBJSDN(.....) LABEL(MY COMPANY CA)EXPIRE(12/31/25)
GENCERT FTPD.CERT1 SUBJSDN(.....) LABEL(FTPD Certificate) SIGNWITH(CERTAUTH.SIGNER)
The GENCERT command generates a digital certificate with a public/private key pair and inserts a CERTDATA profile record into the ACF2 database. The LABEL is a part of the CERTDATA profile record and not part of the certificate. It can be used to help identify a specific CERTDATA record. Be sure to specify an EXPIRE date when creating a signing (CERTAUTH) when acting as a local CA. The EXPIRE date should be 5-10 years in the future to ensure it will extend beyond the EXPIRE date of any certificates signed by it.
External CA
For sites using an External CA, the process is different. First, the GENCERT command is used to generate a self-signed certificate and its CERTDATA record. Next, the GENREQ command is used to generate a certificate request to be sent to the External CA. The GENREQ extracts the subjects distinguished name and the public key from the certificate and puts it in a dataset from which the request is sent to the CA.
ACF
GENCERT FTPD.CERT1 SUBJSDN(.....) LABEL(FTPD Certificate)
GENREQ FTPD.CERT1 DSN('CERTREQ.DSN')
The external CA creates a new signed certificate and sends it back. The signed certificate can be loaded (FTP'd) into a dataset and the INSERT command can be used to replace the previously GENCERT self-signed certificate and its CERTDATA record in the INFOSTG database.
ACF
SET PROFILE(USER) DIV(CERTDATA)
INSERT CERTAUTH.VERISIGN DSN('SIGNDCRT.DSN2') **
INSERT FTPD.CERT1 DSN('SIGNDCRT.DSN1'
This is the only instance where ACF2 allows an INSERT command to replace an existing record. CERTDATA profile processing allows this INSERT command to replace the exising self-signed certificate with the CA-signed certificate if the command specifies no LABEL or if it specifies a LABEL that matches the one on the original certificate, for example FTPD Certificate. It will not allow a different LABEL to be specified.
Note: The LABEL field for FTPD.CERT1 does not have to be included on the INSERT if the fully qualified record id is specified.
**When using certificates signed by a CA, the CA's root certificate must be obtained and inserted as a CERTAUTH CERTDATA profile record. If the CA is your own, the GENCERT shown earlier is sufficient. If the CA is external you should be able to get its root certificate from the CA's website, put it in the dataset, and insert it as shown above.
Note: Be careful how the returned certificate is put into the dataset. If the CA is cut and pasted in edit mode, be sure that CAPS OFF is specified so the data is not changed.
Since it is possible to have intermediate CA certificates where there is a chain of CA certificates, each one signing another, each signing CA would have to be defined as a CERTDATA record and each would have to be connected to the KEYRING record.
Important! Be aware that when the certificate in the dataset is in PKCS#12 format, a password must be supplied on the INSERT and CHKCERT commands.
CHKCERT
The CHKCERT command is available to display the contents of selected fields in the certificate. This command can be useful if INSERT and EXPORT commands are not working as expected or if certificates are being rejected. The CHKCERT can be issued against a dataset or against a CERTDATA record.
Note: The CHKCERT with the CHAIN parameter can be used against the personal certificate to verify and CHKCERT the entire certificate chain of certificates including any intermediate and root certificates.
Example: Certificate in a dataset
CHKCERT DSN('SIGNDCRT.DSN1')
Example: Certificate in a database
CHKCERT FTPD.CERT1
CHKCERT FTPD.CERT1 CHAIN
Connecting to KEYRINGS
The CERTDATA record defines the certificate and the KEYRING record defines the keyring, but ACF2 does not know which certificates are on the keyring unless you connect the CERTDATA records to the KEYRING record.
ACF
SET PROFILE(USER) DIV(KEYRING)
CONNECT CERTDATA(FTPD.CERT1) KEYRING(FTPD.RING1) USAGE(PERSONAL)
DEFAULT
Only the single certificate is needed in the keyring if it is self-signed, but if it was signed by a CA, the local or the external CA, that CA's certificate also must be connected to the keyring.
Example: Your own CA
CONNECT CERTDATA(CERTAUTH.SIGNER) KEYRING(FTPD.RING1) USAGE(CERTAUTH)
Example: External CA
CONNECT CERTDATA(CERTAUTH.VERISIGN) KEYRING(FTPD.RING1) USAGE(CERTAUTH)
If you LIST a KEYRING record you will get a display that looks like this:
KEYRING / FTPD.RING1 last changed by USER002 on 09/23/18 - 11:33
DEFAULT(FTPD.CERT1) RINGNAME(FTPRING)
The following certificates are connected to this keyring:
CERTDATA record Label Usage
--------------- ----- -----
CERTAUTH.SIGNER My Company CA CERTAUTH
FTPD.CERT1 FTPD Certificate PERSONAL
Before attempting to use the defined KEYRING and CERTDATA records, you will need to issue these operator commands to active them.
Example: Issue operator commands to activate
F ACF2,REBUILD(USR),CLASS(P)
F ACF2,OMVS or F ACF2,OMVS(CERTDATA)
Important! These commands will have to be reissued any time there is a change to the KEYRING or CERTDATA records.
Debugging
After the initial keyring and certificate setup is complete, the next step is to bring up the FTP address space as a SSL/TLS application. If there are error messages, gather the required documentation and contact Broadcom Suport for assistance in determining the cause.
The following recommended documentation is needed:
- Server log showing the error messages related to the KEYRING/certificates.
-
To verify KEYRING setup: LIST of the KEYRING that is being used. From TSO, ACF.
ACF
SET PROFILE(USER) DIV(KEYRING)
LIST ringname -
To verify the certificate status, keys and signing chain do a TSO, ACF CHKCERT CHAIN of the Personal/Server/client certificate int he KEYRING. From TSO, ACF.
ACF
CHKCERT certdata.recordname CHAIN - To verify the server task has the authority to access the keyring and the private key of the PERSONAL certificate, run the ACFRPTRV report against the SMF active at the time of the errors.
-
To verify that the keyring, certificates and PERSONAL certificate's Private Key are being returned to the server. Prior to the region/started task that the KEYRING/CERTIFICATES are being used for, start the ACF2 OMVS SECTRACE. This can be done from the console as follows (OMVS trace records are WTO'd to console).
SECTRACE SET,ID=mytrace,TYPE=OMVS,SFUNC=RDATALIB,ENDAfter re-creating the problem the SECTRACE can be deleted/disabled.
SECTRACE DELETE,ID=mytrace
Clients
When setting up FTP clients on Windows, sites must ensure the client has a copy of the signing CA certificate. If using a well known CA to sign your certificates, there should be nothing to do because the CA's certificate is already in the Trusted Root Certification Authorities store on the PC. When using a signing CA certificate, it needs to be exported (without the private key) and imported on the Windows PC.
Example: Clients get the certificates via the EXPORT command.
EXPORT FTPD.CERT1 DSN('dataset nameA') for a self-signed certificate
EXPORT CERTAUTH.SIGNER DSN('dataset nameB') for a CA certificate
The dataset is then FTPd to the client PC where it is imported to the appropriate certificate repository.
There are optional operands on this command, depending on the format being used for the EXPORT. For more details on the optional operands see EXPORT Subcommand.
z/OS Certificate FTP Information
- The standard DCB settings for the DSN references in the INSERT and EXPORT commands is RECFM=VB LRECL=84 BLKSIZE=27998.
- X.509 Distinguished Encoding Rules (DER) certificates (correspond to ACF2 CERTDER format) must be FTP’d in BINary format.
- X.509 certificate encoded using base-64 encoding certificates (correspond to ACF2 CERTB64 format) must be FTP’d in ASCII. This format is a text file, when browsed from Windows’ NOTEPAD or z/OS ISPF Browse the certificate starts with the text -----BEGIN CERTIFICATE----- and ends with the text -----END CERTIFICATE-----.
Feedback
