1STUNNEL(8) stunnel STUNNEL(8)
2
6 stunnel - universal SSL tunnel
7
9 Unix:
10 stunnel [<filename>] | -fd n | -help | -version | -sockets
11 WIN32:
13 stunnel [ [-install | -uninstall | -start | -stop]
14 [-quiet] [<filename>] ] | -help | -version | -sockets
15
17 The stunnel program is designed to work as SSL encryption wrapper
18 between remote clients and local (inetd-startable) or remote servers.
19 The concept is that having non-SSL aware daemons running on your system
20 you can easily set them up to communicate with clients over secure SSL
21 channels.
22 stunnel can be used to add SSL functionality to commonly used Inetd
24 daemons like POP-2, POP-3, and IMAP servers, to standalone daemons like
25 NNTP, SMTP and HTTP, and in tunneling PPP over network sockets without
26 changes to the source code.
27 This product includes cryptographic software written by Eric Young
29 (eay@cryptsoft.com)
30
32 <filename>
33 Use specified configuration file
34 -fd n (Unix only)
36 Read the config file from specified file descriptor
37 -help
39 Print stunnel help menu
40 -version
42 Print stunnel version and compile time defaults
43 -sockets
45 Print default socket options
46 -install (NT/2000/XP only)
48 Install NT Service
49 -uninstall (NT/2000/XP only)
51 Uninstall NT Service
52 -start (NT/2000/XP only)
54 Start NT Service
55 -stop (NT/2000/XP only)
57 Stop NT Service
58 -quiet (NT/2000/XP only)
60 Don't display a message box when successfully installed or unin‐
61 stalled NT service
62
64 Each line of the configuration file can be either:
65 · an empty line (ignored)
67 · a comment starting with ';' (ignored)
69 · an 'option_name = option_value' pair
71 · '[service_name]' indicating a start of a service definition
73 GLOBAL OPTIONS
75 chroot = directory (Unix only)
77 directory to chroot stunnel process
78 chroot keeps stunnel in chrooted jail. CApath, CRLpath, pid and
80 exec are located inside the jail and the patches have to be rela‐
81 tive to the directory specified with chroot.
82 To have libwrap (TCP Wrappers) control effective in a chrooted
84 environment you also have to copy its configuration files
85 (/etc/hosts.allow and /etc/hosts.deny) there.
86 compression = zlib | rle
88 select data compression algorithm
89 default: no compression
91 debug = [facility.]level
93 debugging level
94 Level is a one of the syslog level names or numbers emerg (0),
96 alert (1), crit (2), err (3), warning (4), notice (5), info (6), or
97 debug (7). All logs for the specified level and all levels numeri‐
98 cally less than it will be shown. Use debug = debug or debug = 7
99 for greatest debugging output. The default is notice (5).
100 The syslog facility 'authpriv' will be used unless a facility name
102 is supplied. (Facilities are not supported on Win32.)
103 Case is ignored for both facilities and levels.
105 EGD = egd path (Unix only)
107 path to Entropy Gathering Daemon socket
108 Entropy Gathering Daemon socket to use to feed OpenSSL random num‐
110 ber generator. (Available only if compiled with OpenSSL 0.9.5a or
111 higher)
112 engine = auto | <engine id>
114 select hardware engine
115 default: software-only cryptography
117 There's an example in 'EXAMPLES' section.
119 engineCtrl = command[:parameter]
121 control hardware engine
122 Special commands "LOAD" and "INIT" can be used to load and initial‐
124 ize the engine cryptogaphic module.
125 foreground = yes | no (Unix only)
127 foreground mode
128 Stay in foreground (don't fork) and log to stderr instead of via
130 syslog (unless output is specified).
131 default: background in daemon mode
133 output = file
135 append log messages to a file instead of using syslog
136 /dev/stdout device can be used to redirect log messages to the
138 standard output (for example to log them with daemontools splog‐
139 ger).
140 pid = file (Unix only)
142 pid file location
143 If the argument is empty, then no pid file will be created.
145 pid path is relative to chroot directory if specified.
147 RNDbytes = bytes
149 bytes to read from random seed files
150 Number of bytes of data read from random seed files. With SSL ver‐
152 sions less than 0.9.5a, also determines how many bytes of data are
153 considered sufficient to seed the PRNG. More recent OpenSSL ver‐
154 sions have a builtin function to determine when sufficient random‐
155 ness is available.
156 RNDfile = file
158 path to file with random seed data
159 The SSL library will use data from this file first to seed the ran‐
161 dom number generator.
162 RNDoverwrite = yes | no
164 overwrite the random seed files with new random data
165 default: yes
167 service = servicename
169 use specified string as the service name
170 On Unix: inetd mode service name for TCP Wrapper library.
172 On NT/2000/XP: NT service name in the Control Panel.
174 default: stunnel
176 setgid = groupname (Unix only)
178 setgid() to groupname in daemon mode and clears all other groups
179 setuid = username (Unix only)
181 setuid() to username in daemon mode
182 socket = a|l|r:option=value[:value]
184 Set an option on accept/local/remote socket
185 The values for linger option are l_onof:l_linger. The values for
187 time are tv_sec:tv_usec.
188 Examples:
190 socket = l:SO_LINGER=1:60
192 set one minute timeout for closing local socket
193 socket = r:TCP_NODELAY=1
194 turn off the Nagle algorithm for remote sockets
195 socket = r:SO_OOBINLINE=1
196 place out-of-band data directly into the
197 receive data stream for remote sockets
198 socket = a:SO_REUSEADDR=0
199 disable address reuse (enabled by default)
200 socket = a:SO_BINDTODEVICE=lo
201 only accept connections on loopback interface
202 syslog = yes | no (Unix only)
204 enable logging via syslog
205 default: yes
207 taskbar = yes | no (WIN32 only)
209 enable the taskbar icon
210 default: yes
212 SERVICE-LEVEL OPTIONS
214 Each configuration section begins with service name in square brackets.
216 The service name is used for libwrap (TCP Wrappers) access control and
217 lets you distinguish stunnel services in your log files.
218 Note that if you wish to run stunnel in inetd mode (where it is pro‐
220 vided a network socket by a server such as inetd, xinetd, or tcpserver)
221 then you should read the section entitled INETD MODE below.
222 accept = [host:]port
224 accept connections on specified host:port
225 If no host specified, defaults to all IP addresses for the local
227 host.
228 CApath = directory
230 Certificate Authority directory
231 This is the directory in which stunnel will look for certificates
233 when using the verify. Note that the certificates in this directory
234 should be named XXXXXXXX.0 where XXXXXXXX is the hash value of the
235 DER encoded subject of the cert (the first 4 bytes of the MD5 hash
236 in least significant byte order).
237 CApath path is relative to chroot directory if specified.
239 CAfile = certfile
241 Certificate Authority file
242 This file contains multiple CA certificates, used with the verify.
244 cert = pemfile
246 certificate chain PEM file name
247 A PEM is always needed in server mode. Specifying this flag in
249 client mode will use this certificate chain as a client side cer‐
250 tificate chain. Using client side certs is optional. The certifi‐
251 cates must be in PEM format and must be sorted starting with the
252 certificate to the highest level (root CA).
253 ciphers = cipherlist
255 Select permitted SSL ciphers
256 A colon delimited list of the ciphers to allow in the SSL connec‐
258 tion. For example DES-CBC3-SHA:IDEA-CBC-MD5
259 client = yes | no
261 client mode (remote service uses SSL)
262 default: no (server mode)
264 connect = [host:]port
266 connect to a remote host:port
267 If no host is specified, the host defaults to localhost.
269 Multiple connect options are allowed in a single service section.
271 If host resolves to multiple addresses and/or if multiple connect
273 options are specified, then the remote address is chosen using a
274 round-robin algorithm.
275 CRLpath = directory
277 Certificate Revocation Lists directory
278 This is the directory in which stunnel will look for CRLs when
280 using the verify. Note that the CRLs in this directory should be
281 named XXXXXXXX.0 where XXXXXXXX is the hash value of the CRL.
282 CRLpath path is relative to chroot directory if specified.
284 CRLfile = certfile
286 Certificate Revocation Lists file
287 This file contains multiple CRLs, used with the verify.
289 delay = yes | no
291 delay DNS lookup for 'connect' option
292 engineNum = engine number
294 select engine number to read private key
295 The engines are numbered starting from 1.
297 exec = executable_path (Unix only)
299 execute local inetd-type program
300 exec path is relative to chroot directory if specified.
302 execargs = $0 $1 $2 ... (Unix only)
304 arguments for exec including program name ($0)
305 Quoting is currently not supported. Arguments are separated with
307 arbitrary number of whitespaces.
308 ident = username
310 use IDENT (RFC 1413) username checking
311 key = keyfile
313 private key for certificate specified with cert option
314 Private key is needed to authenticate certificate owner. Since
316 this file should be kept secret it should only be readable to its
317 owner. On Unix systems you can use the following command:
318 chmod 600 keyfile
320 default: value of cert option
322 local = host
324 IP of the outgoing interface is used as source for remote connec‐
325 tions. Use this option to bind a static local IP address, instead.
326 OCSP = url
328 select OCSP server for certificate verification
329 OCSPflag = flag
331 specify OCSP server flag
332 Several OCSPflag can be used to specify multiple flags.
334 currently supported flags: NOCERTS, NOINTERN NOSIGS, NOCHAIN,
336 NOVERIFY, NOEXPLICIT, NOCASIGN, NODELEGATED, NOCHECKS, TRUSTOTHER,
337 RESPID_KEY, NOTIME
338 options = SSL_options
340 OpenSSL library options
341 The parameter is the OpenSSL option name as described in the
343 SSL_CTX_set_options(3ssl) manual, but without SSL_OP_ prefix. Sev‐
344 eral options can be used to specify multiple options.
345 For example for compatibility with erroneous Eudora SSL implementa‐
347 tion the following option can be used:
348 options = DONT_INSERT_EMPTY_FRAGMENTS
350 protocol = proto
352 application protocol to negotiate SSL
353 currently supported: cifs, connect, imap, nntp, pop3, smtp
355 protocolAuthentication = auth_type
357 authentication type for protocol negotiations
358 currently supported: basic, NTLM
360 Currently authentication type only applies to 'connect' protocol.
362 default: basic
364 protocolHost = host:port
366 destination address for protocol negotiations
367 protocolPassword = password
369 password for protocol negotiations
370 protocolUsername = username
372 username for protocol negotiations
373 pty = yes | no (Unix only)
375 allocate pseudo terminal for 'exec' option
376 retry = yes | no (Unix only)
378 reconnect a connect+exec section after it's disconnected
379 default: no
381 session = timeout
383 session cache timeout
384 sslVersion = version
386 select version of SSL protocol
387 Allowed options: all, SSLv2, SSLv3, TLSv1
389 stack = bytes (except for FORK model)
391 thread stack size
392 TIMEOUTbusy = seconds
394 time to wait for expected data
395 TIMEOUTclose = seconds
397 time to wait for close_notify (set to 0 for buggy MSIE)
398 TIMEOUTconnect = seconds
400 time to wait to connect a remote host
401 TIMEOUTidle = seconds
403 time to keep an idle connection
404 transparent = yes | no (Unix only)
406 transparent proxy mode
407 Re-write address to appear as if wrapped daemon is connecting from
409 the SSL client machine instead of the machine running stunnel.
410 This option is only available in local mode (exec option) by
411 LD_PRELOADing env.so shared library or in remote mode (connect
412 option) on Linux 2.2 kernel compiled with transparent proxy option
413 and then only in server mode. Note that this option will not com‐
414 bine with proxy mode (connect) unless the client's default route to
415 the target machine lies through the host running stunnel, which
416 cannot be localhost.
417 verify = level
419 verify peer certificate
420 level 1 - verify peer certificate if present
422 level 2 - verify peer certificate
423 level 3 - verify peer with locally installed certificate
424 default - no verify
425
427 stunnel returns zero on success, non-zero on error.
428
430 In order to provide SSL encapsulation to your local imapd service, use
431 [imapd]
433 accept = 993
434 exec = /usr/sbin/imapd
435 execargs = imapd
436 If you want to provide tunneling to your pppd daemon on port 2020, use
438 something like
439 [vpn]
441 accept = 2020
442 exec = /usr/sbin/pppd
443 execargs = pppd local
444 pty = yes
445 If you want to use stunnel in inetd mode to launch your imapd process,
447 you'd use this stunnel.conf. Note there must be no [service_name] sec‐
448 tion.
449 exec = /usr/sbin/imapd
451 execargs = imapd
452 Here is an example of advanced engine configuration to read private key
454 from an OpenSC engine
455 engine=dynamic
457 engineCtrl=SO_PATH:/usr/lib/opensc/engine_pkcs11.so
458 engineCtrl=ID:pkcs11
459 engineCtrl=LIST_ADD:1
460 engineCtrl=LOAD
461 engineCtrl=MODULE_PATH:/usr/lib/pkcs11/opensc-pkcs11.so
462 engineCtrl=INIT
463 [service]
465 engineNum=1
466 key=id_45
467
469 stunnel.conf
470 stunnel configuration file
471 stunnel.pem
473 stunnel certificate and private key
474
476 Option execargs does not support quoting.
477
479 stunnel cannot be used for the FTP daemon because of the nature of the
480 FTP protocol which utilizes multiple ports for data transfers. There
481 are available SSL enabled versions of FTP and telnet daemons, however.
482
484 INETD MODE
485 The most common use of stunnel is to listen on a network port and
487 establish communication with either a new port via the connect option,
488 or a new program via the exec option. However there is a special case
489 when you wish to have some other program accept incoming connections
490 and launch stunnel, for example with inetd, xinetd, or tcpserver.
491 For example, if you have the following line in inetd.conf:
493 imaps stream tcp nowait root /usr/bin/stunnel stunnel /etc/stunnel/imaps.conf
495 In these cases, the inetd-style program is responsible for binding a
497 network socket (imaps above) and handing it to stunnel when a connec‐
498 tion is received. Thus you do not want stunnel to have any accept
499 option. All the Service Level Options should be placed in the global
500 options section, and no [service_name] section will be present. See
501 the EXAMPLES section for example configurations.
502 CERTIFICATES
504 Each SSL enabled daemon needs to present a valid X.509 certificate to
506 the peer. It also needs a private key to decrypt the incoming data. The
507 easiest way to obtain a certificate and a key is to generate them with
508 the free OpenSSL package. You can find more information on certificates
509 generation on pages listed below.
510 The order of contents of the .pem file is important. It should contain
512 the unencrypted private key first, then a signed certificate (not cer‐
513 tificate request). There should be also empty lines after certificate
514 and private key. Plaintext certificate information appended on the top
515 of generated certificate should be discarded. So the file should look
516 like this:
517 -----BEGIN RSA PRIVATE KEY-----
519 [encoded key]
520 -----END RSA PRIVATE KEY-----
521 [empty line]
522 -----BEGIN CERTIFICATE-----
523 [encoded certificate]
524 -----END CERTIFICATE-----
525 [empty line]
526 RANDOMNESS
528 stunnel needs to seed the PRNG (pseudo random number generator) in
530 order for SSL to use good randomness. The following sources are loaded
531 in order until sufficient random data has been gathered:
532 · The file specified with the RNDfile flag.
534 · The file specified by the RANDFILE environment variable, if set.
536 · The file .rnd in your home directory, if RANDFILE not set.
538 · The file specified with '--with-random' at compile time.
540 · The contents of the screen if running on Windows.
542 · The egd socket specified with the EGD flag.
544 · The egd socket specified with '--with-egd-sock' at compile time.
546 · The /dev/urandom device.
548 With recent (>=OpenSSL 0.9.5a) version of SSL it will stop loading ran‐
550 dom data automatically when sufficient entropy has been gathered. With
551 previous versions it will continue to gather from all the above sources
552 since no SSL function exists to tell when enough data is available.
553 Note that on Windows machines that do not have console user interaction
555 (mouse movements, creating windows, etc) the screen contents are not
556 variable enough to be sufficient, and you should provide a random file
557 for use with the RNDfile flag.
558 Note that the file specified with the RNDfile flag should contain ran‐
560 dom data -- that means it should contain different information each
561 time stunnel is run. This is handled automatically unless the RNDover‐
562 write flag is used. If you wish to update this file manually, the
563 openssl rand command in recent versions of OpenSSL, would be useful.
564 One important note -- if /dev/urandom is available, OpenSSL has a habit
566 of seeding the PRNG with it even when checking the random state, so on
567 systems with /dev/urandom you're likely to use it even though it's
568 listed at the very bottom of the list above. This isn't stunnel's be‐
569 haviour, it's OpenSSLs.
570
572 tcpd(8)
573 access control facility for internet services
574 inetd(8)
576 internet 'super-server'
577 http://stunnel.mirt.net/
579 stunnel homepage
580 http://www.stunnel.org/
582 stunnel Frequently Asked Questions
583 http://www.openssl.org/
585 OpenSSL project website
586
588 Michal Trojnara
589 <Michal.Trojnara@mirt.net>
5904.08 2008.03.27 STUNNEL(8)