Ready to Learn?Ex Libris products all provide open APIs

Overview

Stunnel is free software used to secure traffic running between a TCP client and server. It is designed to work as an SSL encryption wrapper, encrypting the messages using industry-standard crypto libraries (such as OpenSSL) and allowing for secure communication without changing the program running on either side of the TCP connection.
 
Alma uses Stunnel to secure the communication in the following integrations:
 

Compatible Operating Systems

  • Stunnel has been successfully tested on many operating systems, including:
  • Microsoft Windows (32-bit and 64-bit) – Windows Server 2008, 2003, 2000 and Windows 7, Vista, and XP
  • Linux
  • Solaris
  • Mac OS X
  • FreeBSD
For a complete list of tested environments, see the following: https://www.stunnel.org/ports.html
 

Stunnel Setup Procedure

 
The following steps are required to set up Stunnel:  
  1. Select a server or workstation and install Stunnel
  2. Set Stunnel as a service or daemon.
  3. Obtain the Alma certificate.
  4. Update the configuration file.
  5. Test.
 

Installing Stunnel

Since the integration with Alma in specific areas depends on the availability of the Stunnel service, Stunnel must be installed on a machine that can be run 24/7.
 
Using multiple instances of stunnel – pros and cons
Technically it possible to have a single stunnel instance serving multiple integration points. Different opinions have been heard in favor of using multiple stunnel installation:
 
Pros:
  • Avoiding single point of failure.
  • Separate log files for make it easier to track down connectivity problems is such exists.
Cons:
  • Need to configure/maintain/upgrade multiple instances.
 

 Below are installation instructions for installing Stunnel on Windows (as a service) and Linux (as a daemon).
 

Installing Stunnel on a Windows Workstation

  1. Go to the Stunnel downloads page to obtain the latest version of Stunnel: https://www.stunnel.org/downloads.html. The following is displayed:
 
  1. Download and run the latest stunnel-X.YY-installer.exe file.
  2. When presented with the license agreement, click I Agree. The following is displayed:

 

  1. Select the default installation options and click Next. The following is displayed:

  1. Select the desired installation location and click Install.

During the installation process, the following may be displayed:

The answers to these questions are used to create the initial certificate file for Stunnel. Since you download the certificate from Alma, there is no need to provide real answers. Enter a period (.) for each question to leave it blank.

 

Configuring Stunnel to Run as a Windows Service

To ensure that Stunnel is always running and starts when Windows starts, you may want to install Stunnel as a Windows service.

To install Stunnel as a Windows service:

  1. Open a command prompt and go to the directory in which Stunnel is installed. For example:

  1. Execute the following command: stunnel.exe –install. The following is displayed:

  1. Click OK.
  2. From Control Panel - Administrative Tools, open the Services console.
  3. Confirm that Stunnel is installed and configured as an Automatic startup type. To change the service settings, right-click the service name and click Properties. For example:

Note: The error message OpenSCManager error 5 access denied is due to the User Access Control (UAC) feature in Windows. Even if you are logged on as an administrator, you do not have administrative privileges in an application, by default. To run an application in administrative mode, right-click the application icon and select Run as an administrator. To work around the issue, right-click the shortcut to the command prompt in the Start menu under Accessories and select Run as Administrator. The title for the command prompt changes to Administrator: Command Prompt. Run the stunnel.exe - install command from the administrator command prompt to install the service.
 

Installing Stunnel on a Linux / Solaris Workstation

Ex Libris provides a package as an alternative to downloading and compiling Stunnel yourself. To install Stunnel on a Linux / Solaris workstation, download and install the Ex Libris Stunnel package. Run one of the following:
  • For Linux (as root):
wget ftp://produser:Pr6gue@ftp.exlibrisgroup.com/global.new/Linux/openssl-1.0.1e.Linux.x86_64.tar.gz \ 
ftp://produser:Pr6gue@ftp.exlibrisgroup.com/global.new/Linux/stunnel-4.56.Linux.x86_64.tar.gz

tar.gz tar zxf openssl-1.0.1e.Linux.x86_64.tar.gz -C /exlibris/product

tar zxf stunnel-4.56.Linux.x86_64.tar.gz -C /exlibris/product

 

  • For Solaris 10 on x86:
wget ftp://produser:Pr6gue@ftp.exlibrisgroup.com/global.new/SunOS.i386/openssl-1.0.1e.SunOS.i386.tar.gz \
ftp://produser:Pr6gue@ftp.exlibrisgroup.com/global.new/SunOS.i386/stunnel-4.56.SunOS.i386.tar.gz

tar zxf openssl-1.0.1e.SunOS.i386.tar.gz -C /exlibris/product

tar zxf stunnel-4.56.SunOS.i386.tar.gz -C /exlibris/product

 

Notes:

  • The stunnel package includes an example configuration file.
  • The example configuration file and certificate included are configured for tunneling incoming connections on port 8888 to the Alma sandbox machine 6443 secure socket (Sip server).
  • Stunnel logs and pid files are located on /tmp. It is recommended to configure a lower debug level and move log/pid files to your preferred location when switching to production.

 

Configuring Stunnel to Run as a Daemon

To ensure that Stunnel is always running and starts when Linux starts, you may want to run Stunnel as a daemon. To do so, after Stunnel is installed, add the following line to /etc/services:
sip2 XXXX/tcp # sip2 traffic coming to stunnel
Replace XXXX with the port configured for traffic to the Stunnel workstation.
 

Configuring Stunnel

After installing Stunnel, you must configure it. Stunnel relies on secure socket layer encryption or SSL. SSL has an advantage in that only a certificate has to be generated. Certificates are a way of starting a secure communication. In order for communication to be secured, it must be:
  • Encrypted – to prevent a third-party from seeing what is being transmitted
  • Signed – to prevent tampering and to ensure the communication came from the intended party
A certificate is an electronic file that can contain both a public and a private key. The certificate is unique to a Stunnel installation/configuration and is shared with the server. The values in the certificate are used to encrypt and sign the transmitted data by Stunnel and are used to decrypt and verify the
data after it arrives at the server. Alma certificates are associated with an integration profile. The certificate uniquely identifies both the institution and the integration profile. Refer to the specific integration you want to set up for details of the integration profile and the certificate.
 
To configure Stunnel to communicate with Alma:
  1. Double-click the Stunnel icon to start Stunnel.
  2. Copy the certificate file to the directory in which Stunnel is installed.
  3. Select Edit stunnel.conf from the Configuration menu, as in the following screenshot:

 

  1. Delete the existing contents of the stunnel.conf file and paste the following contents:
; **************************************************************************

; * Global options *

; ************************************************************************** ;

; Debugging stuff (may useful for troubleshooting)

debug = 7

output = stunnel.log ;

;Disable FIPS mode to allow non-approved protocols and algorithms

fips = no

;**************************************************************************

; * Service defaults may also be specified in individual service sections *

; **************************************************************************

; Disable support for insecure SSLv2 protocol

options = NO_SSLv2


[Integration Profile 1]

key = [certificate file name]

cert = [certificate file name]

client = yes

accept = 5001

connect = [Alma domain]:6443

TIMEOUTclose = 0

TIMEOUTconnect = 200

TIMEOUTidle = 86400

 
 
Note: Make sure not to add a line with sslVersion=SSLv3 as it is currently not supported.
 
The following table describes some of the lines in the configuration file:
 
ParameterDescription
Key/certThe certificate file name as saved in the Stunnel directory, (for example client.pem).
AcceptReplace the port (and optionally add the IP address) with the desired port. This is the port to which the machine is sending its messages.
Note: When selecting port assignments for services such as Stunnel, do not select a port already in use by another active process or your service may not start.
ConnectFor example: eu01.alma.exlibrisgroup.com:6443
For APAC customers make sure to configure the URL without the acceleration suffix (without the “-a”).
TIMEOUTidleSet to 86400 (24H)
  1. Click Save and close the file.

In certain situations, you must create multiple connection definitions in the stunnel.conf file. If you receive multiple client certificates from your Alma implementation engineer, add each one with a different name to the Stunnel installation directory, Then copy the entire [Integration Profile 1] section and edit the appropriate values, including the certificate file name and accept port. For example, you can add a second [Integration Profile 2] using client2.pem certification and accept port of 5002:

 

[Integration Profile 2]

key = client2.pem

cert = client2.pem

client = yes

accept = 5002

connect = [Alma domain]:6443


TIMEOUTclose = 0

TIMEOUTconnect = 200

TIMEOUTidle = 86400

 

  1. Select Reload Stunnel.conf from the Configuration menu to reload the configuration file, as in the following screenshot:

  1. Confirm that the console displays the following message:
2013.04.23 09:49:01 LOG7[3820:2276]: Service [Integration Profile 1] (FD=440) bound to 0.0.0.0:5001

2013.04.23 09:49:01 LOG7[3820:2276]: Service [Integration Profile 2] (FD=584) bound to 0.0.0.0:5002

 

 

Testing that Stunnel is Running Correctly

To test that Stunnel is operating and accepting traffic, open a command prompt and type telnet STUNNEL-IP STUNNEL-PORT, as in the following screen: 

 
If Stunnel is not operating correctly, an error message, such as the following, is displayed:
C:\ >telnet 10.1.116.102 5001

Connecting To 10.1.116.102...Could not open connection to the host, on port 5001

: Connect failed

 

If Stunnel is operating correctly, the command prompt clears and you connect to Stunnel. For example:

 

In addition, the Stunnel console displays something similar to the following:

2013.03.07 15:43:44 LOG5[5924:2736]: Service [Integration Profile 1] accepted connection from 10.1.116.102:54127