Stunnel

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:

• Self check
• Remote storage facility
• SLNP  

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/platforms.html

Stunnel Setup Procedure

The following steps are required to set up Stunnel:  

1. Select a server or workstation and install Stunnel as a service or daemon.
2. Obtain the Alma certificate from the Alma configuration screen
3. Update the configuration file
4. 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:

• 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

Go to the Stunnel downloads page to obtain the latest version of Stunnel: https://www.stunnel.org/downloads.html. Download and run the latest stunnel-X.YY-installer.exe file.

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.

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

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

3. Click OK.
4. From Control Panel – Administrative Tools, open the Services console.
5. 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 Workstation

It is best to install Stunnel from the official site or using the standard OS package e.g. (RedHat, as root):

yum install stunnel

Sample Sip2 section for the configuration file:

[Sip2]
client=yes
accept = 8888
# Provide the full path to your certificate-key pair file
key = /path/to/stunnel/etc/stunnel/stunnel.pem
cert = /path/to/stunnel/etc/stunnel/stunnel.pem
connect = sandbox.alma.exlibrisgroup.com:6443

The sample above configures tunneling incoming connections on port 8888 to the Alma sandbox machine 6443 secure socket (Sip server).

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:

4. 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

sslVersion = TLSv1.2

The following table describes some of the lines in the configuration file:

5. 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

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

7. 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