################################################################# # STUNNEL_README_AXP_I64.TXT # # (How to use Stunnel on OpenVMS Alpha and I64) # # # # MODIFICATION HISTORY: # # # # Version 3.0 (September 2007) # # - Reflects new stunnel changes. # # # # History: Version 2.0 (September 15, 2003) # ################################################################# Disclaimer: "Stunnel for OpenVMS" is a Port of a Open Source Project to OpenVMS. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. or http://www.opensource.org/licenses/gpl-license.php Requirements (for "Stunnel 4.20 for OpenVMS") - OpenVMS Alpha Version 7.3-2 or higher or OpenVMS I64 (Itanium) version 8.2 or higher - SSL V1.3 for OpenVMS or higher - Compaq/DEC C version 6.4 or higher on OpenVMS Alpha (Note: Executable images for Alpha are provided with this kit. You do not need the C compiler unless you build another Stunnel image.) HP C version 7.1 on OpenVMS IA64 - TCP/IP version 5.4 or higher ----------------------------------------------------------- This section contains the instructions on how to extract an Stunnel directory from STUNNEL-4_20.BCK. ----------------------------------------------------------- Extract STUNNEL-4_20.BCK with the backup command. Example: $ create/dir SSL$ROOT:[stunnel] $ backup STUNNEL-4_20.BCK/save SSL$ROOT:[STUNNEL...] This command extracts the Stunnel backup saveset in SSL$ROOT:[STUNNEL] and creates the SSL$ROOT:[STUNNEL.STUNNEL-4_20] directory. Note: If the SSL$ROOT is not defined on your systems, the prerequisite software "SSL for OpenVMS" has not been installed on your systems. Please install the software first. After Stunnel is extracted, read this file, or find README_VMS.txt in the STUNNEL-4_20 directory. This file describes how to build, start up and shutdown Stunnel in addition to the requirements for the application. ----------------------------------------------------------- 1. Make sure the required SSL for OpenVMS product is properly installed SSL for OpenVMS product is a port of OpenSSL (www.openssl.org) to OpenVMS Alpha & I64. This is a supported layered product that ships with OpenVMS version 7.3-1 or later. The kit also can be downloaded from the HP OpenVMS web site (http://h71000.www7.hp.com/openvms/products/ssl/ssl.html). 2. Building Stunnel for OpenVMS: Stunnel images for Alpha & IA64 (STUNNEL_ALPHA.EXE & STUNNEL_IA64.EXE) are included in this kit. If you wish to build a new image on your system, follow the instructions below. - Move to the "VMS" directory $ set default SSL$ROOT:[STUNNEL.STUNNEL-4_20.VMS] $ @BUILD_STUNNEL.COM Another image will be created after the command procedure completes. (STUNNEL_ALPHA.EXE for Alpha, STUNNEL_IA64.EXE for Itanium) 2.1. Create/obtain an X.509 certificate for the SSL server In the SSL protocol, a digital certificate within the SSL server is required. As Stunnel implements the SSL protocol, the SSL server certificate & its private key must be created before running Stunnel. On OpenVMS, using the certificate tool from "SSL for OpenVMS" (SSL$ROOT:[COM]SSL$CERT_TOOL.COM) would be the easiest way to create them. Run the certificate tool: $ @SSL$ROOT:[COM]SSL$CERT_TOOL.COM Follow these steps with this tool: A. If you don't have a CA certificate (self-signed or from a commercial CA), create it by choosing Menu 5 (Create a CA certificate). The "PEM Pass Phrase" is used when decrypting the key associated with the CA certificate. B. Create the SSL server certificate B.1. Create a CSR (Certificate Signing Request) [Choose Menu 3] For security reasons, it is strongly recommended to encrypt the private key. Enter 'Y' at this prompt, "Encrypt Private Key ? [N]". The "PEM Pass Phrase" will be used when decrypting the key. This password must be provided when loading the key in the SSL application such as Stunnel. B.2. Sign the CSR with the CA certificate [Choose Menu 6] After the CSR is signed with the CA certificate, it becomes an X.509 digital certificate. C. Put both of the certificate & private key in the same PEM file The PEM file specified with the Stunnel's "-p" option must contain both certificate & key. As the certificate tool creates them in separate files, they must be consolidated into the same file. Example: $ copy/concatenate server.crt, server.key stunnel.pem D. Set the appropriate protection to the PEM file As the PEM file contains private key(s), it must be protected against any unauthorized access. Especially when the key is not encrypted, this is essential to SSL security. Example: $ set security /protection=(G,W) stunnel.pem 3. Running Stunnel 3.1. Copy STUNNEL.CONF to STUNNEL_CLIENT.CONF & STUNNEL_SERVER.CONF (located in SSL$ROOT:[STUNNEL.STUNNEL-4_20.VMS]). STUNNEL_STARTUP_CLIENT.COM & STUNNEL_STARTUP_SERVER.COM exist to set Stunnel client & server commands respectively. Examples of Stunnel commands for securing Telnet are shown below (assumption: the client & server commands run on separate hosts. The server's IP address in this example is 192.168.0.1). A. On the server, STUNNEL_SERVER.CONF needs to be modified as follows: cert = stunnel.pem debug = debug [telnet] accept = 993 connect = 23 B. On the client, STUNNEL_CLIENT.CONF needs to be modified as follows: cert = stunnel.pem client = yes debug = debug [telnet] accept = 999 connect = 192.168.0.1:993 For more details about Stunnel commands and formats, refer to the online documentation found at (http://www.stunnel.org). ** Some debugging stuff useful for troubleshooting (important!) To identify activities & errors of Stunnel client/server the following lines needs to be added to STUNNEL_SERVER.CONF and STUNNEL_CLIENT.CONF debug = 7 output = stunnel_xxx.log (where XXX is either "client" or "server") 3.2. Run STUNNEL_STARTUP_SERVER.COM (@STUNNEL_STARTUP_SERVER.COM) (located in SSL$ROOT:[STUNNEL.STUNNEL-4_20.VMS]). on the server This command procedure starts up a detached process (The name of the process will be STUNNEL_SRV 3.3. Run STUNNEL_STARTUP_CLIENT.COM (@STUNNEL_STARTUP_CLIENT.COM) (located in SSL$ROOT:[STUNNEL.STUNNEL-4_20.VMS]). on the client This command procedure starts up a detached process with the process name STUNNEL_CLI 3.4. Start a client application on the client In this example, telnet will be run on the client after starting the Stunnel server & client command procedures. How to start the client depends on the application. As this client needs to connect to the local Stunnel daemon, the client application must have an interface to set a port number. 3.5. Shutting down Stunnel Use this command procedure to stop the Stunnel (client and server) detached process: $ @STUNNEL_SHUTDOWN.COM (located in SSL$ROOT:[STUNNEL.STUNNEL-4_20.VMS]). ---------------------------------------------------------------------------- Examples of Stunnel commands: << Securing Telnet >> 1. Start Stunnel server (using 993 for a server port in this example) $ stunnel STUNNEL_SERVER.CONF STUNNEL_SERVER.CONF needs to be modified as follows: cert = stunnel.pem debug = debug [telnet] accept = 993 connect = 23 2. Start Stunnel client (using 999 for a server port in this example) $ stunnel STUNNEL_CLIENT.CONF STUNNEL_CLIENT.CONF needs to be modified as follows: cert = stunnel.pem client = yes debug = debug [telnet] accept = 999 connect = 192.168.0.1:993 3. Start Telnet (client) at the host running Stunnel client Telnet client should be run on the host running the Stunnel client $ telnet 127.0.0.1 999 OR $ telnet 999 (e.g. if the local host's IP address is 192.168.0.2, specify $ telnet 192.168.0.2 999) << Securing FTP >> ** Notes: Stunnel can secure only the control channel of FTP. This means the username & password are encrypted with Stunnel, but transferred file data transferred is not encrypted. Specifying 127.0.0.1 or "localhost" to use port forwarding through an encrypted Stunnel port does NOT work with FTP. To secure an FTP control channel connection use the following steps. 1. Start Stunnel server (We are using 994 for a server port in this example) $ stunnel STUNNEL_SERVER.CONF STUNNEL_SERVER.CONF needs to be modified as follows: cert = stunnel.pem debug = debug [ftp] accept = 994 connect = 21 2. Start Stunnel client (using 998 for a server port in this example) $ stunnel STUNNEL_CLIENT.CONF STUNNEL_CLIENT.CONF needs to be modified as follows: cert = stunnel.pem client = yes debug = debug [ftp] accept = 998 connect = 192.168.0.1:994 3. Start FTP (client) at the host running Stunnel client FTP client should be run on the host running the Stunnel client $ ftp 998 Example: if the local Client host's IP address is 192.168.0.2, specify $ ftp 192.168.0.2 998 << Securing multiple Applications >> Here are the sample STUNNEL_SERVER.CONF and STUNNEL_CLIENT.CONF files to secure multiple Applications. A. On the server, STUNNEL_SERVER.CONF needs to be modified as follows: cert = stunnel.pem debug = debug [telnet] accept = 993 connect = 23 [ftp] accept = 994 connect = 21 [REXEC] accept = 5512 connect = 512 [RSH] accept = 5514 connect = 514 B. On the client, STUNNEL_CLIENT.CONF needs to be modified as follows: cert = stunnel.pem client = yes debug = debug [telnet] accept = 999 connect = 192.168.0.1:993 [ftp] accept = 998 connect = 192.168.0.1:994 [REXEC] accept = 5512 connect = 192.168.0.1:512 [RSH] accept = 5514 connect = 192.168.0.1:514