Copyright © Cloud Software Group, Inc. All Rights Reserved

Configuring SSL Communications

This section explains the configuration setup required for SSL communications between the client requestor and Apache HTTP server.

Before you can set up the configuration for SSL, you should install the Apache server with SSL enabled. See Configuring Mutual SSL Authentication.

Configuring One-Way SSL Authentication

To enable one-way SSL authentication, follow these steps:

1.	Ensure that mod_ssl module is available in the Apache HTTP server installation.

2.	Enable the mod_ssl module as follows:

a.	Open the APACHE_HOME/conf/httpd.conf file for editing.

b.	Uncomment the following directive in the httpd.conf file, if commented. If this directive does not exist, add it in the file:

   LoadModule ssl_module APACHE_ROOT/modules/mod_ssl.so

where APACHE_ROOT is the actual path of the Apache HTTP server installation which must be SSL enabled.

c.	Uncomment the following line in the file:

#Include conf/extra/httpd-ssl.conf

d.	Save the changes in the file.

3.	Open the APACHE_HOME/conf/extra/httpd-ssl.conf file for editing.

a.	Set the values for the specified directives (if not already set), as follows:

SSLEngine on

SSLCertificateFile "Name_of_Server_public_certificate"

SSLCertificateKeyFile "Name_of_Server_private_key"

SSLCACertificateFile Name_of_CA_Certificate

SSLVerifyClient none

b.	Set the Listen directive if you want to change the default port value for SSL requests:

   Listen listening_port_value

c.	Save the changes made to the APACHE_HOME/conf/extra/httpd-ssl.conf file.

4.	Import the CA certificate as specified in the SSLCACertificateFile directive of the Apache Server configuration.

5.	Verify that the SSL configuration is working.

a.	Open a web browser window.

b.	Enter the following URL to verify the connection to the Apache server.

      http://machine_name:listening_port_value

For example,

http://<machine-name>:8443

6.	Verify that the connection to the Apache server is successful.

Configuring Mutual SSL Authentication

To enable authentication and X.509-based authorization, you must configure both the Apache HTTP server and the Module for the Apache HTTP Server in TIBCO API Exchange Gateway.

Before you start configuring mutual authentication and authorization, see Prerequisites for Mutual SSL Setup.

Prerequisites for Mutual SSL Setup

•	Apache HTTP server with mod_ssl module. Refer to the TIBCO API Exchange Gateway readme for the Apache server version information. Verify that you have set it up as specified in Installing Apache HTTP Server.

•	RSA private key in PEM format to be used by the Apache HTTP server.

•	Digital certificate in PEM format that identifies the Apache HTTP server and includes the public key that corresponds to the Apache HTTP server’s private key.

•	Digital certificate chain in PEM format for each certificate authority that is trusted by the Apache HTTP server. This certificate chain is used to verify the digital certificates presented by the clients as part of the authentication step.

•	The issuer distinguished name and subject distinguished name (or optionally the certificate’s serial number) of each certificate that clients use to identify themselves to the Apache HTTP server.

Configuring Mutual SSL on Apache HTTP Server

To use the mod_ssl module with Apache HTTP server, you must ensure the following:

•	OpenSSL is installed on the Apache server's host computer.

•	An RSA private key in PEM format used by the Apache HTTP server.

•

A digital certificate in PEM format that identifies the Apache HTTP server and includes the public key that corresponds to the Apache HTTP server’s private key. To ensure the integrity of the certificate, it must be signed by a party that every client trusts. For details, see Generate Private Keys And Public Certificates with OpenSSL.

To configure mutual SSL on the Apache HTTP server:

1.	Ensure that the mod_ssl module is available and enabled on the Apache HTTP server installation. To enable the mod_ssl module, follow theser steps:

a.	Open the APACHE_HOME/conf/httpd.conf file for editing.

b.	Uncomment the following directive in the httpd.conf file, if commented. If this directive does not exist, add it in the file:

   LoadModule ssl_module APACHE_ROOT/modules/mod_ssl.so

where APACHE_ROOT is the actual path of the Apache HTTP server installation which must be SSL enabled.

c.	Uncomment the following line in the file:

#Include conf/extra/httpd-ssl.conf

d.	Save the changes in the file.

2.	Open the APACHE_HOME/conf/extra/httpd-ssl.conf file for editing.

a.	Set the values for the specified directives (if not already set), as follows:

SSLEngine on

SSLCertificateFile "Name_of_Server_public_certificate"

SSLCertificateKeyFile "Name_of_Server_private_key"

SSLCACertificateFile Name_of_CA_Certificate

SSLVerifyClient require

SSLVerifyDepth 1

For example, the following are the example values:

SSLCertificateFile "C:\apache2\conf\server.crt"

SSLCertificateKeyFile "C:\apache2\conf\server.key"

SSLCACertificateFile "C:\apache2\certs\myrootca.crt"

• For details on each of the SSL specific properties, refer to the Apache HTTP server SSL documentation. • The value of SSLVerifyDepth is set to 1 as you are doing only one level of authentication. You have configured only one CA which is the root CA.

b.	Set the Listen directive if you want to change the default port value for the SSL requests:

Listen listening_port_value

•

The default port for SSL/TLS requests on the Apache HTTP server side is 443. The regular Apache server listens on the port 80 so there is no conflict between a regular Apache listening on port 80 and an SSL/TLS enabled Apache listening on port 443. Both HTTP and SSL/TLS enabled can run with the same Apache server instance, usually by defining separate virtual hosts listening on port 80 and port 443 to separate the virtual servers.

•	You can access the machine using the http://<machine-name>:443/../..when the default port as 443 is used.

If the port is changed to 8443, the access link is: http://<machine-name>:8443/..

• Ensure that the firewall is open to listening_port_value specified in the Listen directive.

c.	Ensure that the global SSL configuration directives are defined as follows:

      LoadModule ssl_module C:/apache2/modules/mod_ssl.so

      SSLRandomSeed startup builtin

      SSLRandomSeed connect builtin

 

      AddType application/x-x509-ca-cert .crt

      AddType application/x-pkcs7-crl .crl

      SSLPassPhraseDialog builtin

      SSLSessionCache "shmcb:c:/apache2/logs/ssl_scache(512000)"

      SSLSessionCacheTimeout 300

 

      SSLMutex default

d.	Ensure that the SSL related directives are defined as follows and set per virtual host instance basis:

      SSLEngine on

      SSLProtocol all -SSLv2

 

      SSLCipherSuite HIGH:MEDIUM:!aNULL:!MD5

      SSLCertificateFile "Name_of_Server_public_certificate"

      SSLCertificateKeyFile "Name_of_Server_private_key"

Ensure that you have copied the private key and the server’s digital certificate in the directories specified in the SSLCertificateFile and SSLCertificateKeyFile directives.

3.	Save the changes made to the APACHE_HOME/conf/extra/httpd-ssl.conf file.

4.	Import the CA certificate as specified in the SSLCACertificateFile directive of the Apache Server configuration.

5.	Verify that the SSL configuration is working.

a.	Open a web browser window.

b.	Enter the following URL to verify connection to Apache HTTP server.

      http://machine_name:listening_port_value

For example,

http://<machine-name>:8443

c.	Verify that the connection to the Apache HTTP server is successful.

When you invoke a secure connection to the Apache server for the first time using HTTP/S transport, the browser displays a message indicating that the server presented is an untrusted certificate. Accept the certificate by clicking Yes and the following message should be displayed: "it works!".

Configuring Client Authentication with Digital Certificates on Apache HTTP Server

Configure the client authentication with digital certificates on the Apache HTTP server as follows:

1.	Open the APACHE_HOME/conf/extra/httpd-ssl.conf file in a text editor.

2.	Ensure that the following SSL directives are defined:

Table 17: SSL Directives

Parameter	Value
SSLCACertificatePath	Location of the directory containing the separate files for each certificate authority’s digital certificate. For example, /etc/apache2/ssl.crt Set either of the SSLCACertificatePath or SSLCACertificateFile directive, not both.
SSLCACertificateFile	Name and location of a single certificate file that contains all CA certificates. For example, /etc/apache2/ssl.crt/cacert-bundle.pem Set one of the SSLCACertificatePath or SSLCACertificateFile directive, not both.
SSLVerifyClient	require
SSLVerifyDepth	1

3.	Save the changes and close the file.

4.	Restart the Apache HTTP server, if already running.

5.

Test the configuration changes by importing a client certificate into the web browser. To do this, import a PKCS12 archive file into the browser which contains the client’s X.509 certificate, corresponding private key and the public certificates of all the CAs in the chain of trust. The archive file must be trusted by one of the CAs as configured on the Apache HTTP server.

6.	Use a browser as follows:

Using Firefox

a.	Open the web browser.

b.	Navigate to Tools > Options on the browser menu.

c.	Select Advanced tab in the new window.

d.	Select Security tab in the new dialog.

e.	Click the View Certificates button.

f.	Click Import and follow the wizard to import the file.

Using Internet Explorer

g.	Open the web browser.

h.	Navigate to Tools > Internet Options on the browser menu.

i.	Select Content tab in the new dialog window.

j.	Go to Certificates section and click Certificates tab.

k.	Click Import and follow the wizard to import the file.

7.	After you have imported the PKCS12 file, open a browser window.

8.	Enter the following URL to verify secure connection to the Apache server.

   http://machine_name:listening_port_value

For example,

http://<machine-name>:8443

9.	Verify that the connection to the Apache server is successful.

Forwarding Client Certificate Identification Details on Apache HTTP Server to Core Engine

To configure the setup so that the Apache HTTP server forwards the client identification details to the Core Engine,

1.	Open the ASG_HOME/modules/http_server/apache/mod_ASG.conf file in a text editor.

2.	Add the following line to enable the mod_headers module:

   LoadModule headers_module APACHE_HOME/modules/mod_headers.so

   SSLOptions +StdEnvVars

3.	Set RequestHeader directives as follows:

   RequestHeader add X-SSL_PROTOCOL "%{SSL_PROTOCOL}s"

   RequestHeader add CAissuer "%{SSL_CLIENT_I_DN}e"

   RequestHeader add SerialNumber "%{SSL_CLIENT_S_DN}e"

4.	Save the changes and close the file.

5.	Restart the Apache HTTP server.

6.	Start the Core Engine, if not already running. See Starting Core Engine.

7.

Test the configuration changes to see that only requests from clients that authenticate themselves with a client certificate are forwarded to the Core Engine. As no partners are configured yet on the Config UI with the credentials specified in the certificate, the incoming request fails the identification with this configuration.

8.	To test this configuration setup, enter the following URL to submit a ping operation request:

   http://machine_name:listening_port_value/ping

If you have configured everything on the Apache HTTP server but have not registered the partner in the TIBCO API Exchange Gateway yet, you should receive the response from TIBCO API Exchange Gateway on the web browser as follows:

   <asg:Error> <asg:ErrorCode> 2001 </asg:ErrorCode>

   <asg:ErrorMessage> Partner null not identified    </asg:ErrorMessage> </asg:Error>

Registering Partners On Config UI

Register the partner with the identity information as follows:

1.	Start the Config UI. See Starting GUI for details.

2.	Select the gateway project configuration.

3.	Click the PARTNER tab.

4.	Add a new partner. See Partners for details.

5.	Set the following fields for the new partner:

Parameter	Description
Partner Serial Number	Specifies the client’s identity that the Apache HTTP server forwards in the SerialNumber HTTP header of requests that are submitted by this partner. This can either be the certificate’s serial number or the subject distinguished name as used for the digital certificate. For example, the value can be defined as follows: Partner Serial Number: /C=US/ST=California/L=Palo Alto/O=Cloud Software Group, Inc./OU=ActiveMatrix Service Gateway/CN=ASG Demo Client01/emailAddress=asgclient01@tibasg.co.pd
Partner Issuer CA	Specifies the realm in which the client’s identity is valid. This is always the issuer distinguished name as used from the digital certificate for that partner. For example, the value can be defined as follows: Partner Issuer CA: /C=US/ST=California/O=Cloud Software Group, Inc./OU=ActiveMatrix Service Gateway/CN=TIBCO ASG Certificate Authority/emailAddress=admin@tibasg.co.pd

 

Partner Serial Number and Partner Issuer CA fields contain distinguished names as defined by the X.509 standard. The X.509 standard defines the fields, field names, and abbreviations used to refer to the fields.

6.	Click the Partner Operations tab.

7.	Define a ping operation (internal_ping) for new partner. See Facade Access for details.

8.	Save the configuration.

9.	Start the Core Engine. See Starting Core Engine

10.	Test the configuration.

a.	Open a web browser window.

b.	Enter the following URL to submit a ping operation request:

      http://machine_name:listening_port_value/ping

c.	Verify that you receive ASG is alive response from TIBCO API Exchange Gateway on the web browser.

Copyright © Cloud Software Group, Inc. All Rights Reserved