How do I set up ACF2 support for the keyrings and certificates needed for a typical SSL/TLS application---FTP?

Document ID : KB000027722
Last Modified Date : 14/02/2018
Show Technical Document Details

Question:  

How do I set up ACF2 support for the keyrings and certificates needed for a typical SSL/TLS application---FTP?

 

Answer:  

Below are examples for generating certificates, setting up keyrings, and connecting the certificates to the keyrings. The problem in providing examples is that there are many ways to use digital certificates and these examples will not apply to all situations. You really need to understand how your application is going to use the certificates in order to choose the right setup. In this case we are going to set up certificates and keyrings for a basic client/server FTP handshake, using TLS. The steps you must take for this would be the same for any similar TLS/SSL application.

*** ACRONYMS ***

There are four acronyms that you will see frequently in working with keyrings and certificates: SSL - Secure Sockets Layer, TLS - Transport Layer Security, GSK - Global Security Kit, and PKCS - Public Key Cryptography Standards. SSL built upon GSK functions, and TLS built upon SSL. This document 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:

  1. Client issues a secure session request ------------------> (Server)

  2. (Client) <-------Server sends certificate containing server's public key.

  3. Client authenticates certificate against a list of known CAs.

  4. Client generates a session key, encrypts it using the server's public key and sends the encrypted session key to the server.

  5. 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. (Client) <------------------------------------------- > (Server)

*** KEYRINGS ***

The application will make R_datalib service requests to retrieve certificates on a particular keyring. (R_datalib is the interface to external security for the purpose of retrieving certificates and keys.) The keyring name will be specified by you in one of the application's setup options. 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 have to define the keyring and the certificates to ACF2 so ACF2 can retrieve them when they are requested. The ACF2 records are KEYRING and CERTDATA and they are USER profile records stored on the INFOSTG database.

In order for ACF2 to find the right keyring, the KEYRING record must have as its id the userid being used by the application address space making the the request. For example, if the ACF9CCCD message in the FTPD address space identifies the assigned userid as "FTPD", this would be the record id for the associated KEYRING record(s). This relationship between the address space userid and its KEYRING records is called "ownership".

Using FTP as our example, let's assume it is running in address space FTPD. We identify its keyring name by setting KEYRING FTPRING in FTP.DATA. We then define the 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.

Note1: RINGNAME is case sensitive. Be sure you use the same case in the KEYRING record RINGNAME operand as in the application option.

Note2: The KEYRING parameter in FTP.DATA also supports the syntax "userid/ ringname" for shared keyrings. The use of shared keyrings requires a slightly different setup, which is addressed briefly under GENERAL NOTES at the end of this document. Contact ACF2 Technical Support for more information on sharing keyrings.

Since there can be multiple keyrings for an address space, ACF2 will search 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 in 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 you choose. It generally helps if it's self-explanatory.

*** Signing Certificates ***

Before we can go any further and actually set up certificates, you have to decide whether you are going to sign your certificates with your own Certification Authority (CA), or whether you are going to have your certificates signed by one of the available CAs, such as Verisign, RSA, or another. If you are going to be your own CA, you need to define that certificate, as well as the one for FTPD.

    ACF
GENCERT CERTAUTH.SIGNER SUBJSDN(.....) LABEL(My Company CA)
EXPIRE(12/31/10)
GENCERT FTPD.CERT1 SUBJSDN(.....) LABEL(FTPD Certificate)
SIGNWITH(CERTAUTH.SIGNER)

The GENCERT command will generate a digital certificate with a public/private key pair and will insert a CERTDATA profile record into the ACF2 database. The LABEL is a part of the CERTDATA profile record and not part of the certi- ficate. It can be used to help identify a specific CERTDATA record. Be sure you specify an EXPIRE date if you are creating your own CA. It should be 5-10 years in the future to ensure it will extend beyond the EXPIRE date of any certificates signed by it.

If you are going to use an external CA, the process is different. First you use the GENCERT command to generate a self-signed certificate and its CERTDATA record. Next you issue a GENREQ to generate a certificate request to be sent to the 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 Certification Authority.

   ACF
GENCERT FTPD.CERT1 SUBJSDN(.....) LABEL(FTPD Certificate)
GENREQ FTPD.CERT1 DSN('CERTREQ.DSN')

The CA creates a new, signed certificate and sends it back. At that point you load the signed certificate into a dataset and use the INSERT command to replace the previously GENCERT'd 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 will allow this INSERT command to replace the existing self-signed certificate with the CA-signed certificate if the command specifies no LABEL or it specifies a LABEL that matches the one on the original certificate, e.g., FTPD Certificate. It will not allow a different LABEL to be specified. Note that 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 a dataset, and insert it as shown above.

Note: Be careful how you put the returned certificate into the dataset. If you cut and paste in edit mode, be sure you specify CAPS OFF 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.

Also 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:

CHKCERT DSN('SIGNDCRT.DSN1') <--certificate in dataset
CHKCERT FTPD.CERT1 <--certificate in database

*** 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, your own or an external CA, that CA's certi- ficate also must be connected to the keyring.

Your own CA:

   CONNECT CERTDATA(CERTAUTH.SIGNER) KEYRING(FTPD.RING1) USAGE(CERTAUTH)

An 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/05 - 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 activate them.

   F ACF2,REBUILD(USR),CLASS(P)
F ACF2,OMVS or F ACF2,OMVS(CERTDATA)

These commands will have to be reissued any time there is a change to the KEYRING or CERTDATA records.

*** DEBUGGING ***

Now you are ready to bring up the FTP address space as a SSL/TLS application. If there are error messages, contact us and we will work with you to determine the cause. Trouble-shooting usually starts with you running the ACFRPTOM report with PARM='DETAIL'. This will list the failed service requests. You will be searching the report for R_datalib requests for the failing address space. The report record will identify the address space and a 'Ring Name' value that identifies the RINGNAME it is using. List the KEYRING records and verify that the record used specifies a RINGNAME value that exactly matches the 'Ring Name' identified in the OM report record. If that is correct, then verify all required certificates are connected. If the KEYRING record is ok, issue a CHKCERT command against each CERTDATA record on the KEYRING record and verify all required signing CAs have been connected. If each CHKCERT output looks ok, the next step is to set the OMVS SECTRACE and restart the FTPD server.

   ST SET,ID=FTPD,TYPE=OMVS,FUNC=GET,END

This trace will show the R_datalib DataGetFirst and DataGetNext calls made in the system during the time it is set. The trace records are written to the console. (Other destinations may be available in the future.) From these trace records we can verify the keyring used by the caller is the same as the RINGNAME you specified in the KEYRING record---and whether the requested certificates were found. If you wish, you can bypass the CHKCERTs and skip directly to the OMVS SECTRACE. It does require that you recycle the address space.

*** CLIENTS ***

When setting up FTP clients on Windows, you must ensure the client has a copy of the signing CA certificate. If you are using a well-known CA to sign your certificates there should be nothing to do because the CA's certificate should already be in the Trusted Root Certification Authorities store on the PC. When using your own signing CA certificate, it needs to be exported (without the private key) and imported on the Windows PC.

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 appro- priate certificate repository.

There are optional operands on this command, depending on the format being used for the EXPORT. This is documented in the ACF2 Administrator Guide.

*** GENERAL NOTES ***

  1. The standard DCB settings for the DSN references in the INSERT and EXPORT commands is RECFM=VB LRECL=84 BLKSIZE=27998.

  2. When setting up FTP clients on z/OS it is allowable to share one keyring among all clients. This requires ACF2 resource rules for IRR.DIGTCERT.LISTRING, type FAC. If the user requesting the keyring owns the keyring he needs READ access to it. In our example the FTPU server needs READ access to this resource to read his own keyring. If the requestor is not the owner, UPDATE access to the resource is required.

    For example,
       $KEY(IRR.DIGTCERT.LISTRING) TYPE(FAC)
    UID(FTPDuid) SERVICE(READ) ALLOW <-gives access to FTPD
    UID(other) SERVICE(UPDATE) ALLOW <-gives access to non-FTPD requestor
  3. There are two different formats to identify CERTDATA and KEYRING records in the GENCERT and CONNECT commands. For example, the CERTDATA and KEYRING records created previously can be specified in either of the following formats:
       a) userid.suffix:               FTPD.CERT1 or FTPD.RING1
b) userid and label/ringname: FTPD LABEL(FTPD Certificate)
or FTPD RINGNAME(FTPRING)

Each of these formats identifies one unique record. No CERTDATA or KEYRING records can be INSERTed if they have the same record id and LABEL or RINGNAME as a pre-existing record. The record suffix is irrelevant in the comparison.