TLS on z/OS: Setting Up Digital Certificates :: Encryption in SAS® 9.4, Sixth Edition

Step 1. Authorize Access to the RACDCERT Command

To use z/OS as your trusted Certificate Authority (CA), you must authorize access to the RACDCERT command in order to set up the CA and to create and sign certificates. Authorize the trusted administrator using CONTROL access to these profiles in the FACILITY class:

IRR.DIGTCERT.ADD
IRR.DIGTCERT.DELETE
IRR.DIGTCERT.EXPORT
IRR.DIGTCERT.GENCERT
IRR.DIGTCERT.LIST

The following sites provide information about alternative CAs:

For VeriSign, see www.verisign.com
For Thawte, see www.thawte.com

Step 2. Create the Digital Certificate for the CA

The tasks that you perform to generate a digital certificate for the CA, the server, and the client are similar. However, the values that you specify are different.

In this example, Proton, Inc. is the organization that is applying to become a CA by using RACDCERT. After Proton, Inc. becomes a CA, it can serve as a CA for issuing digital certificates to clients (users) and servers on its network.

Perform these tasks:

Request a digital CA certificate. Here is an example of a request:

RACDCERT GENCERT CERTAUTH +
SUBJECTSDN( +
  CN('proton.com') +
  C('US') +
  SP('North Carolina') +
  L('Cary') +
  O('Proton Inc.') +
  OU('IDB') +
) +
ALTNAME( +
  EMAIL('Joe.Bass@proton.com') +
) +
WITHLABEL('Proton CA')

Export the CA certificate in PEM format:

RACDCERT CERTAUTH EXPORT(LABEL('Proton CA')) +
DSN(CA.CERT)

Copy the certificate to the UNIX file system. Use the TSO OPUT and OCOPY commands to copy the files to your UNIX file system.

Note: TLS certificate and key files must reside in the z/OS UNIX file system. The OpenSSL library cannot read MVS data sets.
```
cp //ca.cert ca.cert
```
Convert the certificate file to ASCII format

Note: TLS PEM format certificate files must be converted to ASCII format. The OpenSSL library code in SAS cannot read EBCDIC text.
```
iconv -f ibm-1047 -t iso8859-1 ca.cert >ca.cert.ascii
```

The creation of the CA digital certificate is complete.

A root CA digital certificate is self-signed, which means that the digital certificate is signed using the private key that corresponds to the public key that is in the digital certificate. Except for root CAs, digital certificates are usually signed using a private key that corresponds to a public key that belongs to someone else, usually the CA.

The location of the CA digital certificate is specified using the SSLCALISTLOC= system option which is automatically set to <SASHOME>/SASSecurityCertificateFramework/1.1/cacerts/trustedcerts.pem.

Step 3. Create the Server and Client Digital Certificates

Perform these tasks to create a digital certificate for a server and a client. The steps are identical for the server and the client. This example shows the tasks for the server.

Request a signed server certificate.

Here is an example of a request for a signed server certificate for user SERVER that runs on proton.zos.com.

RACDCERT GENCERT ID(SERVER) +
SUBJECTSDN( +
  CN('proton.zos.com') +
  C('US') +
  SP('North Carolina') +
  L('Cary') +
  O('Proton Inc.') +
  OU('IDB') +
) +
ALTNAME( +
  EMAIL('Joe.Bass@proton.com') +
) +
WITHLABEL('Proton Server') +
SIGNWITH(CERTAUTH LABEL('Proton CA'))

Export the server certificate and key that are specified in PKCS #12 DER encoding package format.

Note: The PKCS #12 DER encoding package is the format used by the RACDCERT utility to encode the exported certificate and private key for an entity, such as a server. It is a binary format.
```
RACDCERT ID(SERVER) EXPORT(LABEL('Proton Server')) +
DSN(SERVER.P12) +
PASSWORD('abcd')
```
Copy the certificate to the UNIX file system.

Note: The PKCS #12 DER encoding package file must reside in the z/OS UNIX file system. The OpenSSL library cannot read MVS data sets. Because the file is already in binary format, its conversion to ASCII is unnecessary.
```
cp //server.p12 server.p12
```

The creation of the server digital certificate and key is complete.

A PKCS #12 DER encoding package is the format that RACDCERT uses to export a certificate and a key for an entity. The exported package file contains both the certificate and the key. The content of the package file is secure by using the password that is specified in the RACDCERT EXPORT command.

Specify a server or client PKCS #12 package using the SSLPKCS12LOC= system option. Specify the password for the package using the SSLPKCS12PASS= option.

Note: For the server, the Common Name must be the name of the computer that the server runs on (for example, proton.zos.com.)

Step 4. View Digital Certificates

To view a digital certificate, issue these commands:

RACDCERT CERTAUTH LIST(LABEL('Proton CA'))
RACDCERT ID(SERVER) LIST(LABEL('Proton Server'))

A digital certificate contains data that was collected to generate the digital certificate timestamps, a digital signature, and other information. However, because the generated digital certificate is encoded (usually in PEM format), it is unreadable.

To read the certificate files, issue these commands:

RACDCERT CHECKCERT(CA.CERT)
RACDCERT CHECKCERT(SERVER.P12) PASS('abcd')

Step 5. Create a CA Trust List Using OpenSSL

After generating a digital certificate for the CA, the server, and the client (optional), you must identify for the OpenSSL client application one or more CAs that are to be trusted. This list is called a trust list.

Note: Starting in the third maintenance release of SAS, you can use the SAS Deployment Manager after Installation to add to the Trusted CA Bundle of Certificates.

If there is only one CA to trust, in the client application, specify the name of the file that contains the OpenSSL CA digital certificate.

If multiple CAs are to be trusted, you can copy and paste into a new file the contents of all the digital certificates of CAs to be trusted by the client application. These CAs can be primary, intermediate, or root certificates. They can be added to the file in any order. To manually create a new trust list, use the following template:

(Your Server Certificate - ssl.crt)

-----BEGIN CERTIFICATE-----

<PEM encoded certificate>

-----END CERTIFICATE-----

(Your Intermediate CA Certificate(s)) 

-----BEGIN CERTIFICATE-----

<PEM encoded certificate>

-----END CERTIFICATE-----

(Your Root CA Certificate)

-----BEGIN CERTIFICATE-----

<PEM encoded certificate>

-----END CERTIFICATE-----

Because the digital certificate is encoded, it is unreadable. Therefore, the content of the digital certificate in this example is represented as

<PEM
                        encoded certificate>

. The content of each digital certificate is delimited using a -----BEGIN CERTIFICATE----- and

-----END
                        CERTIFICATE-----

pair. All text outside the delimiters is ignored. Therefore, you might not want to use delimited lines for descriptive comments.

Generally, OpenSSL returns .pem files, CA's return .crt files (Microsoft returns .cer files). Instead of manually cutting and pasting these files together (regardless of your file extension), you can use the UNIX cat command to concatenate the certificate authority files together. For example, you can take an intermediate authority certificate file, a root authority certificate file, and primary certificate file and concatenate them into a single PEM file. All the certificates must be encoded in PEM format and in ASCII format.

An example of concatenating certificates is as follows:

cat server.pem > certchain.pem
cat intermediateCA.pem >> certchain.pem
cat rootCA.pem >> certchain.pem

Note: You can place these files in any order.

Because the digital certificate is encoded, it is unreadable. To view the file contents, you can use the following OpenSSL commands for your file type:

openssl x509 -in cert.pem -text -noout
openssl x509 -in cert.cer -text -noout
openssl x509 -in cert.crt -text -noout

Use the following OpenSSL command to view a DER encoded Certificate:

openssl x509 -in certificate.der -inform der -text -noout

Note: If you are including a digital certificate that is stored in DER format, you must first convert it to PEM format. For more information, see Convert between PEM and DER File Formats Using OpenSSL.

Step 5. Verify Certificates in the Trust Chain Using OpenSSL

Clients and servers exchange and validate each other’s digital certificates. All of the CA certificates that are needed to validate a server certificate compose a trust chain. All CA certificates in a trust chain have to be available for server certificate validation. The certificates are combined into one file pointed to by the SSLCALISTLOC= option.SSLCALISTLOC= System Option.

You can use the following OpenSSL command to verify certificates signed by a recognized certificate authority (CA):

openssl verify <your-certificate-file>

If your local OpenSSL installation recognizes the certificate or its signing authority and everything checks out (dates, signing chain, and so on.), you get a simple OK message.

openssl verify -verbose -CAfile <your-CA_file>.pem <your-server-cert>.pem

Note: In the third release of SAS 9.4, you can use the SAS Deployment Manager after installation to add your trust chain. The SAS Deployment Manager also validates those certificates.

Step 6. End OpenSSL

To end OpenSSL, type quit at the prompt.