SSL/TLS, HTTP(S), and Certificates with EntireX

Transport Layer Security (TLS), and its predecessor, Secure Sockets Layer (SSL) are cryptographic protocols. They provide communications security in computer networks. TLS and SSL use the public-and-private key encryption system from RSA, which also includes the use of digital certificates.

This document describes Secure Sockets Layer/Transport Layer Security (SSL/TLS) and Certificates within an EntireX context. The term "SSL" in this document refers to both SSL and TLS. The document covers the following topics:

• Introduction

• Random Number Generator

• SSL/TLS Sample Certificates Delivered with EntireX

• SSL/TLS Parameters for Broker as SSL Server (One-way SSL)

• SSL/TLS Parameters for SSL Clients

• Using SSL/TLS with EntireX Components

• SSL/TLS Certificate Creation and Handling

• Managing One-way and Two-way SSL

Related Information

• Running Broker with SSL/TLS Transport under z/OS | UNIX | Windows

• Using SSL/TLS with the RPC Server under z/OS (CICS, Batch, IMS) | Java | C | .NET | XML/SOAP | CICS ECI | CICS Socket Listener | AS/400 | IMS Connect | IBM MQ

• Using SSL/TLS with RPC-ACI Bridge | Listener for IBM MQ

• Broker HTTP(S) Agent (UNIX | Windows)

• Transport: Broker Stubs and APIs

Introduction

One of the major components when using SSL is the certificate. One of the tasks of certificates is to ensure that communication, which runs atop TCP/IP, adheres to an industrial-strength encryption.

Certificates can be described as electronic passports. They contain information about someone (or a machine or location), generally called the Subject. The authenticity of the subject's information is digitally signed by a trustworthy instance, called the Issuer. With certificates, this issuer is also known as a Certificate Authority (CA).

In addition to the above, a certificate also contains a random number that is called the subject's public key. Together with this public key, the subject must also be in possession of a private key. As their names suggest, the public key can be viewed by anyone, whereas the private key must be strictly secured. The public and the private keys together always form a key pair, i.e. they are always created together and complement each other.

The terms SSL/TLS client and SSL/TLS server specify communication endpoints:

• an SSL/TLS server provides a listen port as secure target endpoint

• an SSL/TLS client uses a secure endpoint to connect to the SSL/TLS server

The SSL/TLS connection can be established in two different ways:

• With one-way SSL, the SSL/TLS client validates the SSL/TLS server. The server sends the public certificate to the client, and the client validates the certificate through a certification authority (CA).

• With two-way SSL, client and server authenticate each other. The client validates the public server certificate through a CA. If it was successful, the client will send its public certificate to the server. The server verifies the client certificate through a CA as well.

Here are some typical scenarios using SSL/TLS:

Encryption

In the image above, a public key has been used to encrypt a document. Only the owner of the private key is able to decrypt this text.

Authentication

To verify that the instance that presented a certificate is really who they claim to be (authentic), I can choose a random string, encrypt it with their public key, send it to the subject, have it decrypted with their private key and sent back. I then compare it with my original random string. Only the owner of the appropriate private key is able to perform this operation.

Random Number Generator

Another of the major components with SSL is called the Random Number Generator (RNG). To ensure genuinely random keys with each new session, SSL uses its own random number generator.

This requires a "seed", which should be unique for each installation.

• On UNIX systems, make sure you have defined the environment variable RANDFILE, which refers to a file that contains at least 2048 bytes of random data. As humans are rather limited in their ability to "generate" random data, we suggest using the OpenSSL tool for this task (see Creating Certificates with OpenSSL (z/OS, UNIX, Windows) below).

• On Windows systems, the seed is automatically taken.

SSL/TLS Sample Certificates Delivered with EntireX

Certificates play an important role with SSL. The term "SSL" in this section refers to both SSL and TLS. In order to use SSL as the transport method for EntireX, you need to have certificates available at various locations and for various purposes. The sample certificates come as two types: a trust store (containing a public key), and a keystore (containing a private key). EntireX provides the following default certificates for preliminary test purposes:

• Default Certificates for z/OS

• Default Certificates for UNIX and Windows

• Default Certificates for Java

We strongly recommended you create your own certificates. See below for how to create your own certificates with OpenSSL and keytool.

Default Certificates for z/OS

After the installation process, you will find certificates in the data set EXX108.CERT ready to use for preliminary testing of the SSL transport:

Notes:

1. See also the README with step-by-step description for setting up an environment that enables an SSL-secured communication with a mainframe Broker and certificates stored in RACF.
2. To allow for multiple CAs, import multiple times the various CA certificates into the keystore.

Default Certificates for UNIX and Windows

After the installation process, you will find certificates in directory etc ready to use for preliminary testing of the SSL transport.

Notes:

1. To allow for multiple CAs, concatenate all of the CAs' .pem files into a single new .pem file.

Default Certificates for Java

After the installation process, you will find certificates in etc directory for preliminary testing of the SSL transport:

Notes:

1. To allow for multiple CAs, import multiple times the various CA certificates into the keystore.

SSL/TLS Parameters for Broker as SSL Server (One-way SSL)

The term "SSL" in this section refers to both SSL and TLS. EntireX clients and servers are always SSL clients. The SSL server can be either the EntireX Broker, EntireX Broker SSL Agent or direct RPC in webMethods Integration Server (IS inbound).

SSL usually requires a certificate on the SSL server side of a communication. In order to validate the certificate, the SSL client needs to accept the issuer of the server certificate, that is, it needs to trust the same instance that the certificate has signed. (Customs do not trust your passport - which could be forged - but instead verify its authenticity electronically!) If you are using EntireX Broker as your SSL server, use the following SSL-specific broker attributes:

The SSL client must now present the CA (i.e. its certificate, which includes the public key), so that SSL can determine whether to accept a server certificate or not. For this purpose, specify SSL parameter trust-store (see below) with the EntireX client or server. Checking the SSL server certificate by an SSL client is also known as one-way SSL.

SSL/TLS Parameters for SSL Clients

broker_id="pc001.my-company.com:1958:ssl"

Subject, CN=pc001.my-company.com

How you provide SSL parameters depends on the EntireX component in use. See table Using SSL/TLS with EntireX Components below for platform and language-specific information. SSL parameters are separated by ampersand (&).

If the SSL server requests a client certificate (known as two-way SSL; verify_client=yes is defined in the configuration of the SSL server) the following additional parameters have to be specified:

• key_file

• key_store

• key_passwd

The password that protects the private key is specified with key_passwd. The ampersand (&) character cannot appear in the password.

Using SSL/TLS with EntireX Components

This table provides references to available SSL documentation. Select the RPC or ACI components in use from column SSL Client and the communication partner such as EntireX Broker, Direct RPC, etc. from column SSL Server:

SSL/TLS Certificate Creation and Handling

This section covers the following topics:

• Creating Certificates with OpenSSL (z/OS, UNIX, Windows)

• Creating Certificates with keytool (Java)

• Importing Certificates into RACF (z/OS)

• Additional Considerations for PKI (Public Key Infrastructure)

• Support of Self-signed Certificates

Creating Certificates with OpenSSL (z/OS, UNIX, Windows)

This section contains step-by-step instructions on how to create your own certificates. The OpenSSL tool is installed together with EntireX and can be found in directory <install_root>/common/security/openssl/bin.

To set up all necessary paths when working with the OpenSSL tool

• Call the installed tlsenv script, which is provided in the following locations:

  • Under UNIX: <install_root>/common/security/openssl/extras/tlsenv.sh. Source this once with the dot command in the POSIX shell (bash, ksh, etc.) where the OpenSSL tool will be used.

  • Under Windows: <install_root>\common\security\openssl\extras\tlsenv.bat. Call this once in the command line interpreter window (cmd.exe) where the OpenSSL tool will be used.

To create your own certificates

1. Create a new directory in which the new certificates will be created and where all of the other required files will be stored.

2. In your new directory create a file named genca.cnf with a text editor and cut and paste the contents of the file gencacnf.html (delivered with this documentation) to your new file.

3. Create an empty directory newcerts in your new directory.

4. Create an empty directory certs in your new directory.

5. Create an empty file index.txt in the current directory.

6. Create a file serial in the current directory and enter a number in column 1, line 1, for example: 1000. This serial number will be incremented for each certificate that you create.

7. Now edit the file genca.cnf that you cut and pasted into your new directory in step 2, above. Read the comments carefully. There are a few defaults that you will probably want to adapt to your own environment. Take care not to mix filename separators: Always use the UNIX-style forward slash "/", even on Windows.

   Below is a list of the important variables that should be checked:

   • Set the variable database to point to the index.txt file.

   • Set the variable serial to point to the serial file.

   • Set the variable new_certs to point to the newcerts directory.

   • Set the variable certs_dir to point to the certs directory.

   • Set the variable certificate to point to the CA certificate file (see NewCACert.pem in the example below).

   • Set the variable private_key to point to the CA certificate's private key file (see NewCAKey.pem in the example below).

   • Review the req_distinguished_name section and fill in the *_default variables, if sensible. Empty defaults will be prompted for.

8. Save the configuration file.

You can now start creating certificates.

First, you need to define a Certificate Authority (CA); create a key pair and a self-signed certificate to represent this CA.

Enter the following command in a shell and follow the instructions (be patient, loading the screen state takes several seconds)

openssl req -config genca.cnf -newkey rsa:4096 -x509 -keyout <NewCAKey.pem> -out <NewCACert.pem> -days 365

Do not forget the passphrase for the key file! You will need it whenever a new certificate is generated.

Now you have a CA certificate and a CA key file.

Next, create a certificate that can be used by various products (for example the Broker kernel) to start an SSL server session.

With the CA cert and key files described above you can create any number of certificates. We will sign all of them with the same CA (used from the genca.cnf file).

Create a certificate request:

openssl req -config genca.cnf -newkey rsa:2048 -out <ExxAppCertReq.pem> -keyout <ExxAppKey.pem> -days 365

You will be prompted for a new passphrase. Again, this will be the passphrase to lock the MyAppKey.pem file. Remember it well.

You must then sign this certificate request with your CA to create a proper certificate:

openssl ca -config genca.cnf -policy policy_anything -out <ExxAppCert.pem> -infiles <ExxAppCertReq.pem>

Creating Certificates with keytool (Java)

A certificate management tool is also supplied with the standard JDK kit, i.e. it is part of J2SE kit, not the JSSE kit. Certificate requests can be generated and keystores and truststores can be built with this tool. The steps for building keystores and truststores are outlined below.

To create a keystore

1. Create a keystore containing a self-signed certificate and key (example yourkeystore).

   The following command will prompt you for identification information.

    keytool -genkey -v -alias yourJavaApp -keyalg RSA -validity 900 -keypass yourkeypsw -keystore yourkeystore -storepass  yourkeypsw

2. Import any CA certificates of CAs which will sign the certificate generated above.

   keytool -import -v -alias yourcacert -file yourcacert.pem -keystore yourkeystore -storepass yourkeypsw

3. (Optional) List certificate chain present in keystore.

   keytool -list -v -keystore yourkeystore -storepass yourkeypsw

4. Extract certificate for signing by a CA.

   keytool -certreq -v -alias yourJavaApp -file yourJavaAppreq -keypass yourkeypsw -keystore yourkeystore -storepass yourkeypsw

5. Sign Java certificate request with OpenSSL tool.

   openssl ca -config yourca.cnf -policy policy_anything -out yourjavaapp.pem -notext -days 365 -infiles yourJavaAppreq

   Note:
   The -notext parameter is required. Without it, the import of a signed certificate to keystore will fail. The error will be either a Not an X.509 certificate or a Tag sequence error. The reason for the error is that the OpenSSL signing tool will write both a text version and an encoded version of the signed certificate to the output file if the -notext parameter is not specified.

6. Import signed certificate.

   keytool -import -v -alias yourJavaApp -file yourjavaapp.pem -keypass yourkeypsw -keystore yourkeystore -storepass yourkeypsw

   Notes:

   1. yourjavaapp.pem is the signed certificate returned by the CA.
   2. Import will only work if a signed CA certificate is already present in the keystore.

To create a truststore

• Import the CA certificates that were used to sign the client and server certificates.

  • Import signed CA certificates.

    keytool -import -v -alias yourcacert -file yourcacert.pem -keystore yourtruststore -storepass yourstorepsw

  • (Optional) List truststore.

    keytool -list -v -keystore yourtruststore -storepass yourstorepsw

Importing Certificates into RACF (z/OS)

This section applies to operating system z/OS only.

To import certificates into RACF

1. Create a certificate with OpenSSL. See Creating Certificates with OpenSSL (z/OS, UNIX, Windows).

2. Create the PKCS#12 import format for RACF. Enter the following command to create a file containing the application certificate and application key files for import into RACF:

   openssl pkcs12 -export -inkey <EXXAppKey.pem> -in <EXXAppCert.pem> -certfile <EXXCACert.pem> -out <EXXPkcs12.p12>

   You will be prompted for the passphrase of the private key and for an export password. The output file is created in PKCS#12 format. You can use FTP to transfer the output file in binary mode to the IBM host.

3. Import certificates and private keys with RACDCERT into RACF. See readme file EXX108.CERT(README) in the product distribution for detailed instructions.

Additional Considerations for PKI (Public Key Infrastructure)

When using a PKI, there are usually more than two certificates involved. Typically, there is one (self-signed) root certificate, one or more CA certificates, and several application certificates, usually one for every server.

For the SSL server side (Broker) you need a suitable application certificate.

To check the certificate

• Execute the command:

  openssl x509 -in <YourSSLCert.pem> -text

  This will display relevant information about the certificate such as key extensions with key usage and basic constraints. (For example, the Basic Contraint CA should be "FALSE".)

Given a specific server certificate, it is also possible to verify the certificate chain.

To verify the certificate chain

• Execute the command:

  openssl verify -CAfile <YourCaCert.pem> -purpose sslserver <YourSSLCert.pem>

  If you receive an OK, then <YourSSLCert.pem> should work on the SSL server side together with the <YourCaCert.pem> on the SSL client side.

Support of Self-signed Certificates

To support self-signed certificates it is probably necessary to modify the LDAP settings. For example, to allow use of a self-signed certificate in OpenLDAP, the client needs access to the CA's certificate. Add the following line to file /etc/openldap/ldap.conf:

TLS_CACERT <YourCaCert.pem>

Managing One-way and Two-way SSL

• One-way SSL
  One-way SSL is always active in EntireX, that is, the public SSL server certificate is always checked by the client.

• Two-way SSL

  • EntireX Adapter requires parameter verify_client=yes in the configuration of the SSL server.

  • EntireX Broker on z/OS requires HandshakeRole ServerWithClientAuth in the AT-TLS configuration.

  • EntireX Broker on all other platforms requires SSL-specific Broker attribute VERIFY-CLIENT=YES.