Using CA (Certificate Authority) SSL certificates with XCOM

Products

• XCOM Data Transport
• XCOM Data Transport - Windows
• XCOM Data Transport - Linux PC

Issue/Introduction

This article describes where to install certificates issued by an external CA (Certificate Authority) so that they are used by XCOM when performing SSL transfers.

Environment

• XCOM™ Data Transport® for Windows
• XCOM™ Data Transport® for UNIX/Linux PC
  
  

Resolution

Regardless of whether the sample scripts delivered with XCOM (makeca, makeclient, makeserver) are used or an external CA has issued the certificates, at the end of the process there will be the following files:

• A CA certificate which identifies the CA and signs the certificates issued by it.
  
  
• Two pairs of files, each file in the pair containing a private key and its corresponding certificate. One pair of files is to be used when this server initiates an SSL transfer (this server is an SSL client) and the other is to be used when another XCOM server initiates an SSL transfer to this server (this server is an SSL server).

Those files are functionally equivalent to the ones created when running the XCOM sample scripts and need to go to the exact same places, as determined by XCOM config files. The rules are as follows:

• File %XCOM_HOME%\config\xcom.glb has the XCOM_CONFIG_SSL parameter, which names the SSL configuration file which by default is %XCOM_HOME%\config\configssl.cnf. This file indicates where the certificate and key files reside.
  XCOM_CONFIG_SSL can also be set in transfer .cnf/.xml files or on the command line and doing so will override the xcom.glb file parameter value setting.
  
  
• The file containing the CA certificate is named in the [CA] section. This should contain the signing CA certificate for this server plus other CA certificates for XCOM partners which take part in secure transfers. 
  
  
• The path containing the file is named in the [CA_DIRECTORY] section. This needs to be set although it's certainly redundant.
  
  
• The files containing the SSL client and SSL server certificates (including the public key) are named in the [CERTIFICATE] section
  
  
• The files containing the SSL client and SSL server private keys are named in the [PRIVATEKEY] section

Note that, in each section, INITIATE_SIDE refers to the SSL client side, the one which initiates the connection, and RECEIVE_SIDE refers to the SSL server side, the one which receives the connection request from the network.
Both INITIATE_SIDE and RECEIVE_SIDE entries are required because XCOM does 2-way SSL authentication so both the SSL client and SSL server certificates are verified at the other end of the connection.

Additional Information

NOTES:
1. The XCOM SSL configuration requires the use of PEM encoded certificate/private key files.

2. When changing xcom.glb the XCOM service needs to be restarted. However when making any changes to the configssl.cnf file or any of the files it refers to a restart is not required because the configssl.cnf and those files are re-read each time an SSL transfer is initiated.

3. Related KB articles:
Concatenate certificates for incoming XCOM SSL transfers from different systems
Replace Expiring SSL certificates used by XCOM for Windows, UNIX, Linux PC

4. XCOM for Windows doc. pages:
11.6: Generate TLS/SSL Certificates > Configure the TLS/SSL Server and Client
12.0: Set Up TLS/SSL Mode > Configure the TLS/SSL Server and Client Settings

5. XCOM for UNIX/Linux doc. pages:
11.6: Generate TLS/SSL Certificates > Configure the TLS/SSL Server and Client
12.0: Set Up TLS/SSL Mode

6. The .pem format certificate files are Base64 ASCII text files that can be read in any editor to validate contents.