Installing and Configuring SSL under z/OS

Setting Up Digital Certificates for SSL under z/OS

Perform these tasks to set up and use SSL:

Step 1. Authorize Access to the RACDCERT Command

To use z/OS as your trusted Certification 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.

Note: SSL 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: SSL 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.

You will specify the CA digital certificate using the SSLCALISTLOC= system option.

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.) [cautionend]

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 for the SSL Client Application

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.

If there is only one CA to trust (for example, Proton CA), in the client application, use the SSLCALISTLOC= option to specify the name of the file that contains the CA digital certificate, which was created in Step 2.

If multiple CAs are to be trusted by the client application, use the UNIX cat command to concatenate the contents of all the digital certificates for CAs. All the certificates must be encoded in PEM format and in ASCII format.

As an alternative method for creating a CA trust list, use this template to copy and paste the digital certificates into one file:

Certificate for Proton CA

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

<PEM encoded certificate>

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


Certificate for Keon CA 

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

<PEM encoded certificate>

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


Certificate for Microsoft CA

-----BEGIN 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. In the preceding template, the file that is used contains the content of digital certificates for the CAs: Proton, Keon, and Microsoft.

Top of Page