1TLSWrap v1.04 2------------- 3 4Copyright (c) 2002-2006 Tomas Svensson <ts@codepix.com> 5 6TLSWrap is a TLS/SSL FTP wrapper/proxy for UNIX and Windows, allowing you 7to use your favourite FTP client with any TLS/SSL-enabled FTP server. 8 9Features: 10 11* Full encryption of both control and data connections (it's possible to 12 only encrypt the control channel). 13 14* One process handles all connections (non-blocking I/O). 15 16* A helper process (thread on Windows) does all hostname lookups so that 17 the main process is free for other work during slow lookups. 18 19* Both C source and native Windows executable available. 20 21* Runs as a system service on MS Windows, if desired. 22 23 24Tested and confirmed to work on the following operating systems (using GCC 25unless otherwise specified): 26 27Compaq Tru64 UNIX V5.1A (Alpha with Compaq C V6.4-009) 28Debian GNU/Linux 2.2r5 (i386, StrongARM) 29FreeBSD 5.4 (i386) 30NetBSD 1.5.2 (i386, Alpha) 31OpenBSD 3.2 (i386, Alpha) 32Redhat Linux 7.1 (i386 with Intel(R) C++ Compiler for 32-bit applications, Version 5.0.1) 33Redhat Linux 7.2 (IA64 with Intel(R) C++ Itanium(TM) Compiler 5.0.1) 34Slackware Linux 8.0 (i386) 35Solaris 7 (SPARC with both GCC and WorkShop Compilers 5.0 98/12/15 C 5.0) 36Solaris 9 (SPARC) 37Windows 2000 (i386 with Cygwin) 38Windows 2000 (i386 with Intel(R) C++ Compiler for 32-bit applications, Version 8.1) 39Windows 2000 (i386 with Microsoft (R) 32-bit C/C++ Optimizing Compiler Version 12.00.8804 for 80x86) 40Windows XP (i386 with Microsoft (R) 32-bit C/C++ Optimizing Compiler Version 14.00.50215.44 for 80x86) 41 42 43How to install: 44 45./configure 46make 47make install 48 49If your system lacks /dev/urandom, do NOT link a possibly existing 50/dev/random but instead use a entropy gathering daemon like PRNGD (PRNGD 51is never drained and can never block (unlike the original EGD or 52/dev/random). PRNGD can be found on: 53http://www.aet.tu-cottbus.de/personen/jaenicke/postfix_tls/prngd.html 54 55How to use it: 56 57TLSWRAP listens to port 7000 by default, see below how to change it. Connect 58to this port (127.0.0.1:7000) instead of the normal FTP server and replace 59your username with username@hostname:port and use your password as normal. 60If you put a # in from of the username, the data channel encryption will be 61disabled and you can do site-to-site transfers ("FXP" or "ftp proxy"). 62The character % in front of the username enables "Implicit SSL" and +<mode> 63enables "security mode" <mode>, for example, use +3user@host:port to enable 64security mode 3. For more details on security modes, see below. 65 66You can also connect from a remote computer, for example if you have a 67UNIX-based Internet/NAT router then run this on the server and you can 68connect with Windows clients and connect safely over the Internet. 69 70New since 0.7 beta 3: You who connect remotely *must* specify an IP 71to listen to with -h, the default (127.0.0.1) is only available locally. 72 73Command line options: 74 75 -a filename 76 Specifies the name of a PEM file with CA certificates. All specified 77 certificates must be valid. These are used with security modes 3 and 4. 78 79 -c max 80 Maximum number of client connections to handle. Defaults to 5. 81 82 -C list 83 Select permitted SSL ciphers each separated by a colon. 84 Defaults to RC4-SHA:RC4-MD5:DHE-DSS-RC4-SHA:DES-CBC3-SHA: 85 DES-CBC3-MD5:EDH-RSA-DES-CBC3-SHA:EDH-DSS-DES-CBC3-SHA, 86 you may want ALL instead. 87 88 -d 89 Debug mode. Causes the program to not detach from the 90 controlling terminal and to print debug information to 91 standard output. 92 93 -E socket 94 Entropy Gathering Daemon socket to use to feed OpenSSL 95 random number generator (Available only if compiled 96 with OpenSSL 0.9.5a or higher). Default locations will 97 be searched even without this option (/var/run/egd-pool, 98 /dev/egd-pool and /etc/egd-pool). 99 100 -h host 101 Specify the hostname or IP to bind the listening socket to. Defaults to 102 127.0.0.1. 103 104 -I options 105 Windows only: Use -I <options> to install TLSWrap as a service, to be 106 started with <options> on system boot. If the options contain spaces, 107 enclose them with ", e.g. 'tlswrap -I "-l 6000"'. To install with the 108 default options, use the command 'tlswrap -I ""'. The service is 109 automatically started after installation. 110 111 -k 112 Windows only: wait for a key after printing messages related to Windows 113 services. 114 115 -l port 116 Port to listen for clients on, defaults to 7000. 117 118 -p directory 119 Specifies the directory from which server certificates will be loaded and 120 saved. The certificates should be named <server-IP>-<data/ctrl>.pem. 121 122 For details on how to use server certificates, see the details on the 123 security modes. 124 125 -P directory 126 Specifies the directory from which user certificates/certificate chains 127 will be loaded. After this, TLSWrap will try to load <server-IP>.pem 128 from the user certificate directory. 129 130 The certificates must be in PEM format and must be sorted starting with the 131 subject's certificate (actual client certificate), followed by intermediate 132 CA certificates if applicable, and ending at the highest level (root) CA. 133 134 -R 135 Windows only: Stops (if it is running) and removes the TLSWrap service. 136 137 -s mode 138 Specifies the default security mode. These are as follows: 139 140 0 - No certificate verification is done. (Default for now.) 141 142 1 - Relaxed whitelisting 143 -------------------- 144 On the first connection to a server, its certificates (control and 145 data connections are treated separately, for quite obvious reasons), will 146 will be saved in the certs dir (see below) as <server-IP>-<data/ctrl>.pem. 147 148 On subsequent connections, TLSWrap will verify the stored certificates 149 against those presented by the server. If the control connection 150 certificate doesn't match, tlswrap will say "530 TLSWrap certificate 151 verification failed, disconnecting." and disconnect. If the data 152 certificate doesn't match, it will print "425 TLSWrap data certificate 153 verification failed.", the data transfer will be aborted but TLSWrap will 154 stay connected with the server. 155 156 No other checks (such as expiration dates, CRLs, CAs) will be made on 157 the certificates. 158 159 2 - Strict whitelisting 160 ------------------- 161 Identical to mode 1 above, but with the difference that no new 162 certificates will be added. If TLSWrap can't find certificate file(s) 163 for a server, it will just disconnect. 164 165 3 - Relaxed PKI path validation 166 --------------------------- 167 This mode requires one or more X.509 CA certificates (or certificate chains) 168 in the form of a PEM file. All certificates must be valid. To specify CA 169 certificates, use -a <name_of_ca_PEM_file>. 170 171 Upon connection with a server, an encrypted TLS session is first eshtablished. 172 This yields the server's X.509 certificate which is validated using the 173 previously specified CA certificates. No certificate fields are used. 174 175 4 - Strict PKI path validation 176 -------------------------- 177 This works like above mode, but the certificate information is verified as 178 follows: 179 180 If the X.509v3 subject alternative name extension is present, then 181 the DNS name and IP address fields will be matched against the server's. 182 If there is no subjectAltName extension the commonName (CN) will be 183 compared against the DNS name. If either check fail then the connection 184 will be terminated. 185 186 ## This is the proper way to use X.509 certificates ## 187 188 -t tokens 189 Specifies the 5 characters to 1) disable data encryption, 190 2) separate the username and the hostname, 3) separate the hostname and 191 port, 4) enable "implicit ssl", and 5) change the security mode. 192 defaults to "#@:%+". 193 194Contact info: 195 196Send bugreports to ts@codepix.com. 197