################################################################# # STUNNEL_README_VAX.TXT (How to use Stunnel on OpenVMS) # # # # 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 3.26 for OpenVMS") - OpenVMS VAX version 7.3 or higher - SSL V1.1 for OpenVMS or higher - Compaq/DEC C version 6.4 or higher (Note: Executable images for Alpha & VAX are provided with this kit. You do not need the C compiler unless you build another Stunnel image.) - TCP/IP version 5.3 or higher !!! IMPORTANT !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! Stunnel cannot be used to secure FTP with TCP/IP v5.3 ECO 2 or later versions. Use SRCP (see instructions below) with these versions of TCP/IP over Stunnel. Also SSH is available for OpenVMS Alpha. (http://h71000.www7.hp.com/openvms/products/ssh/ssh.html) !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ----------------------------------------------------------- This section contains the instructions on how to extract a Stunnel directory from STUNNEL-3_26.BCK. ----------------------------------------------------------- Extract STUNNEL-3_26.BCK with the backup command. Example: $ create/dir SSL$ROOT:[stunnel] $ backup STUNNEL-3_26.BCK/save SSL$ROOT:[STUNNEL...] This command extracts the Stunnel backup saveset in SSL$ROOT:[STUNNEL] and creates the SSL$ROOT:[STUNNEL.STUNNEL-3_26] 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-3_26 directory. This file describes how to build, start up and shutdown Stunnel in addition to the requirements for the application. ----------------------------------------------------------- 1. Make sure the SSL product ("SSL V1.1 for OpenVMS"(*)) is properly installed Because the Stunnel executable image (Stunnel.exe) is linked with the OpenSSL shareable images, "SSL V1.1 for OpenVMS" (provided by HP) is required for Stunnel for OpenVMS Alpha. (*) "SSL for OpenVMS" is a port of OpenSSL (www.openssl.org) to OpenVMS Alpha & VAX. 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. Build Stunnel for OpenVMS: Stunnel images for Alpha & VAX (STUNNEL_ALPHA.EXE & STUNNEL_VAX.EXE) are included in this kit. If you wish to build a new image on your system, follow the instruction below. - Move to the "VMS" directory ($ set default [.STUNNEL-3_26.VMS]) $ @BUILD_STUNNEL.COM Another image will be created after completing this build command procedure. (STUNNEL_ALPHA.EXE for Alpha and STUNNEL_VAX.EXE for VAX) 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. To run the certificate tool: $ @SSL$ROOT:[COM]SSL$CERT_TOOL.COM Follow the steps with this tool: A. If you don't have a CA certificate (self-signed or from 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' for 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. Run Stunnel 3.1. Edit STUNNEL_STARTUP_CLIENT.COM & STUNNEL_STARTUP_SERVER.COM (located in [.STUNNEL-3_26.VMS]) to specify Stunnel commands. In order to run Stunnel with these command procedures, the "stunnel_command" symbol must be set to a proper Stunnel command in those files. 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 is assumed to be 192.168.0.1). A. On the server, the server command (in STUNNEL_STARTUP_SERVER.COM) is: $ stunnel_command = "STUNNEL -d 992 -r 127.0.0.1:23 -p stunnel.pem -o stunnel_server.log" B. On the client, the client command (in STUNNEL_STARTUP_CLIENT.COM) is: $ stunnel_command = "STUNNEL -c -d 992 -r 192.168.0.1:992 -o stunnel_client.log" For more details about Stunnel commands and formats, refer to the online documentation found at (http://www.stunnel.org). !! Log messages (important!) By default, log messages are written into OPCOM with Stunnel for OpenVMS. However, it is recommended to create a log file with the "-o" option rather then using OPCOM. As shown in the examples above, specifying a log file with every Stunnel command makes it easier to identify activities & errors of every Stunnel client/server. 3.2. Run STUNNEL_STARTUP_SERVER.COM (@STUNNEL_STARTUP_SERVER.COM) on the server This command procedure starts up a detached process (The name of the process will be: STUNNEL + "port # after -d option" (for example "Stunnel992"). 3.3. Run STUNNEL_STARTUP_CLIENT.COM (@STUNNEL_STARTUP_CLIENT.COM) on the client This command procedure starts up a detached process (its name is STUNNEL'port # after -d option'. 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 detached process: $ @STUNNEL_SHUTDOWN.COM "PORT#" A port number on which the Stunnel daemon of the detached process is running must be specified. For example, to stop the "STUNNEL992" process, "@STUNNEL_SHUTDOWN.COM 992" is the command. ---------------------------------------------------------------------------- Examples of Stunnel commands: << Securing Telnet >> 1. Start Stunnel server (using 992 for a server port in this example) $ stunnel -d 992 -r 127.0.0.1:23 -p stunnel.pem -o stunnel_server.log OR $ stunnel -d 992 -r "IP address of the local host":23 -p stunnel.pem -o stunnel_server.log (e.g. if the local host's IP address is 192.168.0.1, $ stunnel -d 992 -r 192.168.0.1:23 -p stunnel.pem -o server.log) 2. Start Stunnel client (using 992 for a server port in this example) $ stunnel -c -d 992 -r "IP address of the remote host":992 -o stunnel_client.log "This remote host" is the host running the Stunnel server. (e.g. if the remote host's IP address is 192.168.0.1, $ stunnel -c -d 992 -r 192.168.0.1:992 -o stunnel_client.log) 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 992 OR $ telnet "IP address of the local host" 992 (e.g. if the local host's IP address is 192.168.0.2, $ telnet 192.168.0.2 992) << Securing FTP >> !!! IMPORTANT !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! Stunnel cannot be used to secure FTP with TCP/IP v5.3 ECO 2 or later versions. Use SRCP (see instructions below) with these versions of TCP/IP over Stunnel. Also SSH is available for OpenVMS Alpha. (http://h71000.www7.hp.com/openvms/products/ssh/ssh.html) !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! !! 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 990 for a server port in this example) $ stunnel -d 990 -r "IP address of the local host":21 -p stunnel.pem -o stunnel_server.log Example: If the local host's server IP address is 192.168.0.1. $ stunnel -d 990 -r 192.168.0.1:21 -p stunnel.pem -o stunnel_server.log) 2. Start Stunnel client (using 990 for a server port in this example) $ stunnel -c -d 990 -r "IP address of the remote server host":990 -o stunnel_client.log "This remote host" is the host running the Stunnel server established in STEP 1. Example: If the remote Server host's IP address is 192.168.0.1, $ stunnel -c -d 990 -r 192.168.0.1:990 -o stunnel_client.log) 3. Start FTP (client) at the host running Stunnel client FTP client should be run on the host running the Stunnel client $ ftp "IP address of the local host" 990 Example: if the local Client host's IP address is 192.168.0.2, $ ftp 192.168.0.2 990 << Securing RCP >> RCP can choose either the REXEC or RSH protocol based on its options. Thus it is better to create two Stunnel-secured channels (for both protocols) before running RCP commands. 1. Start Stunnel servers (using 5512 & 5514 for server ports in this example) < For REXEC > $ stunnel -d 5512 -r "IP address of the local server host":512 -p stunnel.pem -o stunnel_server.log Example: If the local server host's IP address is 192.168.0.1, $ stunnel -d 5512 -r 192.168.0.1:512 -p stunnel.pem -o stunnel_server.log) < For RSH > $ stunnel -d 5514 -r "IP address of the local host":514 -p stunnel.pem -o stunnel_server.log Example: If the local server host's IP address is 192.168.0.1, $ stunnel -d 5514 -r 192.168.0.1:514 -p stunnel.pem -o stunnel_server.log) 2. Start Stunnel clients (using 5512 & 5514 for a server port in this example) < For REXEC > $ stunnel -c -d 5512 -r "IP address of the remote server host":5512 -o stunnel_client.log Example: If the remote server host's IP address is 192.168.0.1, $ stunnel -c -d 5512 -r 192.168.0.1:5512 -o stunnel_client.log) < For RSH > $ stunnel -c -d 5514 -r "IP address of the remote host(server)":5514 -o stunnel_client.log Example: If the remote server host's IP address is 192.168.0.1, $ stunnel -c -d 5514 -r 192.168.0.1:5514 -o stunnel_client.log) 3. Start RCP on the node running the Stunnel client RCP should be run on the node running the Stunnel client Use SRCP.COM (in [.STUNNEL-3_26.VMS]) to use RCP with Stunnel. Check SRCP.COM for more details. Example: Using REXEC protocol $ @SRCP 5512 /user=username /password="passwd" localhost:remote_file.txt local_file.txt (remote_file.txt is located on the remote host, though)