1=head1 NAME 2 3=encoding utf8 4 5stunnel - TLS offloading and load-balancing proxy 6 7 8=head1 SYNOPSIS 9 10=over 4 11 12=item B<Unix:> 13 14B<stunnel> [S<FILE>] | S<-fd N> | S<-help> | S<-version> | S<-sockets> | S<-options> 15 16=item B<WIN32:> 17 18B<stunnel> [ [ S<-install> | S<-uninstall> | S<-start> | S<-stop> | 19 S<-reload> | S<-reopen> | S<-exit> ] [S<-quiet>] [S<FILE>] ] | 20 S<-help> | S<-version> | S<-sockets> | S<-options> 21 22=back 23 24 25=head1 DESCRIPTION 26 27The B<stunnel> program is designed to work as I<TLS> encryption wrapper 28between remote clients and local (I<inetd>-startable) or remote 29servers. The concept is that having non-TLS aware daemons running on 30your system you can easily set them up to communicate with clients over 31secure I<TLS> channels. 32 33B<stunnel> can be used to add I<TLS> functionality to commonly used I<Inetd> 34daemons like POP-2, POP-3, and IMAP servers, to standalone daemons like 35NNTP, SMTP and HTTP, and in tunneling PPP over network sockets without 36changes to the source code. 37 38This product includes cryptographic software written by 39Eric Young (eay@cryptsoft.com) 40 41 42=head1 OPTIONS 43 44=over 4 45 46=item B<FILE> 47 48Use specified configuration file 49 50=item B<-fd N> (Unix only) 51 52Read the config file from specified file descriptor 53 54=item B<-help> 55 56Print B<stunnel> help menu 57 58=item B<-version> 59 60Print B<stunnel> version and compile time defaults 61 62=item B<-sockets> 63 64Print default socket options 65 66=item B<-options> 67 68Print supported TLS options 69 70=item B<-install> (Windows NT and later only) 71 72Install NT Service 73 74=item B<-uninstall> (Windows NT and later only) 75 76Uninstall NT Service 77 78=item B<-start> (Windows NT and later only) 79 80Start NT Service 81 82=item B<-stop> (Windows NT and later only) 83 84Stop NT Service 85 86=item B<-reload> (Windows NT and later only) 87 88Reload the configuration file of the running NT Service 89 90=item B<-reopen> (Windows NT and later only) 91 92Reopen the log file of the running NT Service 93 94=item B<-exit> (Win32 only) 95 96Exit an already started stunnel 97 98=item B<-quiet> (Win32 only) 99 100Don't display any message boxes 101 102=back 103 104 105=head1 CONFIGURATION FILE 106 107Each line of the configuration file can be either: 108 109=over 4 110 111=item * 112 113An empty line (ignored). 114 115=item * 116 117A comment starting with ';' (ignored). 118 119=item * 120 121An 'option_name = option_value' pair. 122 123=item * 124 125'[service_name]' indicating a start of a service definition. 126 127=back 128 129An address parameter of an option may be either: 130 131=over 4 132 133=item * 134 135A port number. 136 137=item * 138 139A colon-separated pair of IP address (either IPv4, IPv6, or domain name) and port number. 140 141=item * 142 143A Unix socket path (Unix only). 144 145=back 146 147=head2 GLOBAL OPTIONS 148 149=over 4 150 151=item B<chroot> = DIRECTORY (Unix only) 152 153directory to chroot B<stunnel> process 154 155B<chroot> keeps B<stunnel> in a chrooted jail. I<CApath>, I<CRLpath>, I<pid> 156and I<exec> are located inside the jail and the patches have to be relative 157to the directory specified with B<chroot>. 158 159Several functions of the operating system also need their files to be located within the chroot jail, e.g.: 160 161=over 4 162 163=item * 164 165Delayed resolver typically needs /etc/nsswitch.conf and /etc/resolv.conf. 166 167=item * 168 169Local time in log files needs /etc/timezone. 170 171=item * 172 173Some other functions may need devices, e.g. /dev/zero or /dev/null. 174 175=back 176 177=item B<compression> = deflate | zlib 178 179select data compression algorithm 180 181default: no compression 182 183Deflate is the standard compression method as described in RFC 1951. 184 185=item B<debug> = [FACILITY.]LEVEL 186 187debugging level 188 189Level is one of the syslog level names or numbers 190emerg (0), alert (1), crit (2), err (3), warning (4), notice (5), 191info (6), or debug (7). All logs for the specified level and 192all levels numerically less than it will be shown. Use I<debug = debug> or 193I<debug = 7> for greatest debugging output. The default is notice (5). 194 195The syslog facility 'daemon' will be used unless a facility name is supplied. 196(Facilities are not supported on Win32.) 197 198Case is ignored for both facilities and levels. 199 200=item B<EGD> = EGD_PATH (Unix only) 201 202path to Entropy Gathering Daemon socket 203 204Entropy Gathering Daemon socket to use to feed the B<OpenSSL> random number 205generator. 206 207=item B<engine> = auto | ENGINE_ID 208 209select hardware or software cryptographic engine 210 211default: software-only cryptography 212 213See Examples section for an engine configuration to use the certificate and the corresponding private key from a cryptographic device. 214 215=item B<engineCtrl> = COMMAND[:PARAMETER] 216 217control hardware engine 218 219=item B<engineDefault> = TASK_LIST 220 221set OpenSSL tasks delegated to the current engine 222 223The parameter specifies a comma-separated list of task to be delegated to the 224current engine. 225 226The following tasks may be available, if supported by the engine: ALL, RSA, 227DSA, ECDH, ECDSA, DH, RAND, CIPHERS, DIGESTS, PKEY, PKEY_CRYPTO, PKEY_ASN1. 228 229=item B<fips> = yes | no 230 231enable or disable FIPS 140-2 mode. 232 233This option allows you to disable entering FIPS mode if B<stunnel> was compiled 234with FIPS 140-2 support. 235 236default: no (since version 5.00) 237 238=item B<foreground> = yes | quiet | no (Unix only) 239 240foreground mode 241 242Stay in foreground (don't fork). 243 244With the I<yes> parameter it also logs to stderr in addition to 245the destinations specified with I<syslog> and I<output>. 246 247default: background in daemon mode 248 249=item B<iconActive> = ICON_FILE (GUI only) 250 251GUI icon to be displayed when there are established connections 252 253On Windows platform the parameter should be an .ico file containing a 16x16 254pixel image. 255 256=item B<iconError> = ICON_FILE (GUI only) 257 258GUI icon to be displayed when no valid configuration is loaded 259 260On Windows platform the parameter should be an .ico file containing a 16x16 261pixel image. 262 263=item B<iconIdle> = ICON_FILE (GUI only) 264 265GUI icon to be displayed when there are no established connections 266 267On Windows platform the parameter should be an .ico file containing a 16x16 268pixel image. 269 270=item B<log> = append | overwrite 271 272log file handling 273 274This option allows you to choose whether the log file (specified with the I<output> 275option) is appended or overwritten when opened or re-opened. 276 277default: append 278 279=item B<output> = FILE 280 281append log messages to a file 282 283/dev/stdout device can be used to send log messages to the standard 284output (for example to log them with daemontools splogger). 285 286=item B<pid> = FILE (Unix only) 287 288pid file location 289 290If the argument is empty, then no pid file will be created. 291 292I<pid> path is relative to the I<chroot> directory if specified. 293 294=item B<RNDbytes> = BYTES 295 296bytes to read from random seed files 297 298=item B<RNDfile> = FILE 299 300path to file with random seed data 301 302The OpenSSL library will use data from this file first to seed the random 303number generator. 304 305=item B<RNDoverwrite> = yes | no 306 307overwrite the random seed files with new random data 308 309default: yes 310 311=item B<service> = SERVICE (Unix only) 312 313stunnel service name 314 315The specified service name is used for syslog and as the I<inetd> mode service 316name for TCP Wrappers. While this option can technically be specified in the 317service sections, it is only useful in global options. 318 319default: stunnel 320 321=item B<syslog> = yes | no (Unix only) 322 323enable logging via syslog 324 325default: yes 326 327=item B<taskbar> = yes | no (WIN32 only) 328 329enable the taskbar icon 330 331default: yes 332 333=back 334 335 336=head2 SERVICE-LEVEL OPTIONS 337 338Each configuration section begins with a service name in square brackets. 339The service name is used for libwrap (TCP Wrappers) access control and lets 340you distinguish B<stunnel> services in your log files. 341 342Note that if you wish to run B<stunnel> in I<inetd> mode (where it 343is provided a network socket by a server such as I<inetd>, I<xinetd>, 344or I<tcpserver>) then you should read the section entitled I<INETD MODE> 345below. 346 347 348=over 4 349 350=item B<accept> = [HOST:]PORT 351 352accept connections on specified address 353 354If no host specified, defaults to all IPv4 addresses for the local host. 355 356To listen on all IPv6 addresses use: 357 358 accept = :::PORT 359 360=item B<CApath> = DIRECTORY 361 362Certificate Authority directory 363 364This is the directory in which B<stunnel> will look for certificates when using 365the I<verifyChain> or I<verifyPeer> options. Note that the certificates in 366this directory should be named XXXXXXXX.0 where XXXXXXXX is the hash value of 367the DER encoded subject of the cert. 368 369The hash algorithm has been changed in B<OpenSSL 1.0.0>. It is required to 370c_rehash the directory on upgrade from B<OpenSSL 0.x.x> to B<OpenSSL 1.x.x>. 371 372I<CApath> path is relative to the I<chroot> directory if specified. 373 374=item B<CAfile> = CA_FILE 375 376Certificate Authority file 377 378This file contains multiple CA certificates, to be used with the I<verifyChain> 379and I<verifyPeer> options. 380 381=item B<cert> = CERT_FILE 382 383certificate chain file name 384 385The parameter specifies the file containing certificates used by B<stunnel> 386to authenticate itself against the remote client or server. 387The file should contain the whole certificate chain starting from the actual 388server/client certificate, and ending with the self-signed root CA certificate. 389The file must be either in PEM or P12 format. 390 391A certificate chain is required in server mode, and optional in client mode. 392 393This parameter is also used as the certificate identifier when a hardware 394engine is enabled. 395 396=item B<checkEmail> = EMAIL 397 398email address of the peer certificate subject 399 400Multiple I<checkEmail> options are allowed in a single service section. 401Certificates are accepted if no subject checks were specified, or the email 402address of the peer certificate matches any of the email addresses specified 403with I<checkEmail>. 404 405This option requires OpenSSL 1.0.2 or later. 406 407=item B<checkHost> = HOST 408 409host of the peer certificate subject 410 411Multiple I<checkHost> options are allowed in a single service section. 412Certificates are accepted if no subject checks were specified, or the host name 413of the peer certificate matches any of the hosts specified with I<checkHost>. 414 415This option requires OpenSSL 1.0.2 or later. 416 417=item B<checkIP> = IP 418 419IP address of the peer certificate subject 420 421Multiple I<checkIP> options are allowed in a single service section. 422Certificates are accepted if no subject checks were specified, or the IP 423address of the peer certificate matches any of the IP addresses specified with 424I<checkIP>. 425 426This option requires OpenSSL 1.0.2 or later. 427 428=item B<ciphers> = CIPHER_LIST 429 430select permitted TLS ciphers (TLSv1.2 and below) 431 432This option does not impact TLSv1.3 ciphersuites. 433 434A colon-delimited list of the ciphers to allow in the TLS connection, 435for example DES-CBC3-SHA:IDEA-CBC-MD5. 436 437=item B<ciphersuites> = CIPHERSUITES_LIST 438 439select permitted TLSv1.3 ciphersuites 440 441A colon-delimited list of TLSv1.3 ciphersuites names in order of preference. 442 443This option requires OpenSSL 1.1.1 or later. 444 445default: TLS_CHACHA20_POLY1305_SHA256:TLS_AES_256_GCM_SHA384:TLS_AES_128_GCM_SHA256 446 447=item B<client> = yes | no 448 449client mode (remote service uses TLS) 450 451default: no (server mode) 452 453=item B<config> = COMMAND[:PARAMETER] 454 455B<OpenSSL> configuration command 456 457The B<OpenSSL> configuration command is executed with the specified parameter. 458This allows any configuration commands to be invoked from the stunnel 459configuration file. Supported commands are described on the 460I<SSL_CONF_cmd(3ssl)> manual page. 461 462Several I<config> lines can be used to specify multiple configuration commands. 463 464Use I<curves> option instead of enabling I<config = Curves:list_curves> to support elliptic curves. 465 466This option requires OpenSSL 1.0.2 or later. 467 468=item B<connect> = [HOST:]PORT 469 470connect to a remote address 471 472If no host is specified, the host defaults to localhost. 473 474Multiple I<connect> options are allowed in a single service section. 475 476If host resolves to multiple addresses and/or if multiple I<connect> 477options are specified, then the remote address is chosen using a 478round-robin algorithm. 479 480=item B<CRLpath> = DIRECTORY 481 482Certificate Revocation Lists directory 483 484This is the directory in which B<stunnel> will look for CRLs when using the 485I<verifyChain> and I<verifyPeer> options. Note that the CRLs in this directory 486should be named XXXXXXXX.r0 where XXXXXXXX is the hash value of the CRL. 487 488The hash algorithm has been changed in B<OpenSSL 1.0.0>. It is required to 489c_rehash the directory on upgrade from B<OpenSSL 0.x.x> to B<OpenSSL 1.x.x>. 490 491I<CRLpath> path is relative to the I<chroot> directory if specified. 492 493=item B<CRLfile> = CRL_FILE 494 495Certificate Revocation Lists file 496 497This file contains multiple CRLs, used with the I<verifyChain> and 498I<verifyPeer> options. 499 500=item B<curves> = list 501 502ECDH curves separated with ':' 503 504Only a single curve name is allowed for OpenSSL older than 1.1.1. 505 506To get a list of supported curves use: 507 508 openssl ecparam -list_curves 509 510default: 511 512 X25519:P-256:X448:P-521:P-384 (OpenSSL 1.1.1 or later) 513 514 prime256v1 (OpenSSL older than 1.1.1) 515 516=item B<logId> = TYPE 517 518connection identifier type 519 520This identifier allows you to distinguish log entries generated for each of the 521connections. 522 523Currently supported types: 524 525=over 4 526 527=item I<sequential> 528 529The numeric sequential identifier is only unique within a single instance of 530B<stunnel>, but very compact. It is most useful for manual log analysis. 531 532=item I<unique> 533 534This alphanumeric identifier is globally unique, but longer than the sequential 535number. It is most useful for automated log analysis. 536 537=item I<thread> 538 539The operating system thread identifier is neither unique (even within a single 540instance of B<stunnel>) nor short. It is most useful for debugging software 541or configuration issues. 542 543=item I<process> 544 545The operating system process identifier (PID) may be useful in the inetd mode. 546 547=back 548 549default: sequential 550 551=item B<debug> = LEVEL 552 553debugging level 554 555Level is a one of the syslog level names or numbers 556emerg (0), alert (1), crit (2), err (3), warning (4), notice (5), 557info (6), or debug (7). All logs for the specified level and 558all levels numerically less than it will be shown. 559The default is notice (5). 560 561While the I<debug = debug> or I<debug = 7> level generates the most verbose 562output, it is only intended to be used by stunnel developers. Please only use 563this value if you are a developer, or you intend to send your logs to our 564technical support. Otherwise, the generated logs B<will> be confusing. 565 566=item B<delay> = yes | no 567 568delay DNS lookup for the I<connect> option 569 570This option is useful for dynamic DNS, or when DNS is not available during 571B<stunnel> startup (road warrior VPN, dial-up configurations). 572 573Delayed resolver mode is automatically engaged when stunnel fails to resolve on 574startup any of the I<connect> targets for a service. 575 576Delayed resolver inflicts I<failover = prio>. 577 578default: no 579 580=item B<engineId> = ENGINE_ID 581 582select engine ID for the service 583 584=item B<engineNum> = ENGINE_NUMBER 585 586select engine number for the service 587 588The engines are numbered starting from 1. 589 590=item B<exec> = EXECUTABLE_PATH 591 592execute a local inetd-type program 593 594I<exec> path is relative to the I<chroot> directory if specified. 595 596The following environmental variables are set on Unix platforms: 597REMOTE_HOST, REMOTE_PORT, SSL_CLIENT_DN, SSL_CLIENT_I_DN. 598 599=item B<execArgs> = $0 $1 $2 ... 600 601arguments for I<exec> including the program name ($0) 602 603Quoting is currently not supported. 604Arguments are separated with an arbitrary amount of whitespace. 605 606=item B<failover> = rr | prio 607 608Failover strategy for multiple "connect" targets. 609 610=over 4 611 612=item I<rr> 613 614round robin - fair load distribution 615 616=item I<prio> 617 618priority - use the order specified in config file 619 620=back 621 622default: prio 623 624=item B<ident> = USERNAME 625 626use IDENT (RFC 1413) username checking 627 628=item B<include> = DIRECTORY 629 630include all configuration file parts located in DIRECTORY 631 632The files are included in the ascending alphabetical order of their names. The recommended filename convention is 633 634for global options: 635 636 00-global.conf 637 638for local service-level options: 639 640 01-service.conf 641 642 02-service.conf 643 644=item B<key> = KEY_FILE 645 646private key for the certificate specified with I<cert> option 647 648A private key is needed to authenticate the certificate owner. 649Since this file should be kept secret it should only be readable 650by its owner. On Unix systems you can use the following command: 651 652 chmod 600 keyfile 653 654This parameter is also used as the private key identifier when a hardware 655engine is enabled. 656 657default: the value of the I<cert> option 658 659=item B<libwrap> = yes | no 660 661Enable or disable the use of /etc/hosts.allow and /etc/hosts.deny. 662 663default: no (since version 5.00) 664 665=item B<local> = HOST 666 667By default, the IP address of the outgoing interface is used as the source for 668remote connections. Use this option to bind a static local IP address instead. 669 670=item B<OCSP> = URL 671 672select OCSP responder for certificate verification 673 674=item B<OCSPaia> = yes | no 675 676validate certificates with their AIA OCSP responders 677 678This option enables I<stunnel> to validate certificates with the list of 679OCSP responder URLs retrieved from their AIA (Authority Information Access) 680extension. 681 682=item B<OCSPflag> = OCSP_FLAG 683 684specify OCSP responder flag 685 686Several I<OCSPflag> can be used to specify multiple flags. 687 688currently supported flags: NOCERTS, NOINTERN, NOSIGS, NOCHAIN, NOVERIFY, 689NOEXPLICIT, NOCASIGN, NODELEGATED, NOCHECKS, TRUSTOTHER, RESPID_KEY, NOTIME 690 691=item B<OCSPnonce> = yes | no 692 693send and verify the OCSP nonce extension 694 695This option protects the OCSP protocol against replay attacks. Due to its 696computational overhead, the nonce extension is usually only supported on 697internal (e.g. corporate) responders, and not on public OCSP responders. 698 699=item B<options> = SSL_OPTIONS 700 701B<OpenSSL> library options 702 703The parameter is the B<OpenSSL> option name as described in the 704I<SSL_CTX_set_options(3ssl)> manual, but without I<SSL_OP_> prefix. 705I<stunnel -options> lists the options found to be allowed in the 706current combination of I<stunnel> and the I<OpenSSL> library used 707to build it. 708 709Several I<option> lines can be used to specify multiple options. 710An option name can be prepended with a dash ("-") to disable the option. 711 712For example, for compatibility with the erroneous Eudora TLS 713implementation, the following option can be used: 714 715 options = DONT_INSERT_EMPTY_FRAGMENTS 716 717default: 718 719 options = NO_SSLv2 720 options = NO_SSLv3 721 722Use I<sslVersionMax> or I<sslVersionMin> option instead of disabling specific TLS protocol 723versions when compiled with B<OpenSSL 1.1.0> or later. 724 725=item B<protocol> = PROTO 726 727application protocol to negotiate TLS 728 729This option enables initial, protocol-specific negotiation of the TLS 730encryption. 731The I<protocol> option should not be used with TLS encryption on a separate port. 732 733Currently supported protocols: 734 735=over 4 736 737=item I<cifs> 738 739Proprietary (undocummented) extension of CIFS protocol implemented in Samba. 740Support for this extension was dropped in Samba 3.0.0. 741 742=item I<connect> 743 744Based on RFC 2817 - I<Upgrading to TLS Within HTTP/1.1>, section 5.2 - I<Requesting a Tunnel with CONNECT> 745 746This protocol is only supported in client mode. 747 748=item I<imap> 749 750Based on RFC 2595 - I<Using TLS with IMAP, POP3 and ACAP> 751 752=item I<ldap> 753 754Based on RFC 2830 - I<Lightweight Directory Access Protocol (v3): Extension for Transport Layer Security> 755 756=item I<nntp> 757 758Based on RFC 4642 - I<Using Transport Layer Security (TLS) with Network News Transfer Protocol (NNTP)> 759 760This protocol is only supported in client mode. 761 762=item I<pgsql> 763 764Based on 765F<http://www.postgresql.org/docs/8.3/static/protocol-flow.html#AEN73982> 766 767=item I<pop3> 768 769Based on RFC 2449 - I<POP3 Extension Mechanism> 770 771=item I<proxy> 772 773Passing of the original client IP address with HAProxy PROXY protocol version 1 774F<https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt> 775 776=item I<smtp> 777 778Based on RFC 2487 - I<SMTP Service Extension for Secure SMTP over TLS> 779 780=item I<socks> 781 782SOCKS versions 4, 4a, and 5 are supported. The SOCKS protocol itself 783is encapsulated within TLS encryption layer to protect the final 784destination address. 785 786F<http://www.openssh.com/txt/socks4.protocol> 787 788F<http://www.openssh.com/txt/socks4a.protocol> 789 790The BIND command of the SOCKS protocol is not supported. 791The USERID parameter is ignored. 792 793See Examples section for sample configuration files for VPN based on SOCKS 794encryption. 795 796=back 797 798=item B<protocolAuthentication> = AUTHENTICATION 799 800authentication type for the protocol negotiations 801 802Currently, this option is only supported in the client-side 'connect' and 803'smtp' protocols. 804 805Supported authentication types for the 'connect' protocol are 'basic' or 806'ntlm'. The default 'connect' authentication type is 'basic'. 807 808Supported authentication types for the 'smtp' protocol are 'plain' or 'login'. 809The default 'smtp' authentication type is 'plain'. 810 811=item B<protocolDomain> = DOMAIN 812 813domain for the protocol negotiations 814 815Currently, this option is only supported in the client-side 'connect' protocol. 816 817=item B<protocolHeader> = HEADER 818 819header for the protocol negotiations 820 821Currently, this option is only supported in the client-side 'connect' protocol. 822 823=item B<protocolHost> = ADDRESS 824 825host address for the protocol negotiations 826 827For the 'connect' protocol negotiations, I<protocolHost> specifies HOST:PORT of 828the final TLS server to be connected to by the proxy. The proxy server 829directly connected by B<stunnel> must be specified with the I<connect> option. 830 831For the 'smtp' protocol negotiations, I<protocolHost> controls the client SMTP 832HELO/EHLO value. 833 834=item B<protocolPassword> = PASSWORD 835 836password for the protocol negotiations 837 838Currently, this option is only supported in the client-side 'connect' and 839'smtp' protocols. 840 841=item B<protocolUsername> = USERNAME 842 843username for the protocol negotiations 844 845Currently, this option is only supported in the client-side 'connect' and 846'smtp' protocols. 847 848=item B<PSKidentity> = IDENTITY 849 850PSK identity for the PSK client 851 852I<PSKidentity> can be used on B<stunnel> clients to select the PSK identity 853used for authentication. This option is ignored in server sections. 854 855default: the first identity specified in the I<PSKsecrets> file. 856 857=item B<PSKsecrets> = FILE 858 859file with PSK identities and corresponding keys 860 861Each line of the file in the following format: 862 863 IDENTITY:KEY 864 865Hexadecimal keys are automatically converted to binary form. 866Keys are required to be at least 16 bytes long, which implies 867at least 32 characters for hexadecimal keys. 868The file should neither be world-readable nor world-writable. 869 870=item B<pty> = yes | no (Unix only) 871 872allocate a pseudoterminal for 'exec' option 873 874=item B<redirect> = [HOST:]PORT 875 876redirect TLS client connections on certificate-based authentication failures 877 878This option only works in server mode. 879Some protocol negotiations are also incompatible with the I<redirect> option. 880 881=item B<renegotiation> = yes | no 882 883support TLS renegotiation 884 885Applications of the TLS renegotiation include some authentication scenarios, 886or re-keying long lasting connections. 887 888On the other hand this feature can facilitate a trivial CPU-exhaustion 889DoS attack: 890 891F<http://vincent.bernat.im/en/blog/2011-ssl-dos-mitigation.html> 892 893Please note that disabling TLS renegotiation does not fully mitigate 894this issue. 895 896default: yes (if supported by B<OpenSSL>) 897 898=item B<reset> = yes | no 899 900attempt to use the TCP RST flag to indicate an error 901 902This option is not supported on some platforms. 903 904default: yes 905 906=item B<retry> = yes | no 907 908reconnect a connect+exec section after it was disconnected 909 910default: no 911 912=item B<securityLevel> = LEVEL 913 914set the security level 915 916The meaning of each level is described below: 917 918=over 4 919 920=item level 0 921 922Everything is permitted. 923 924=item level 1 925 926The security level corresponds to a minimum of 80 bits of security. Any parameters offering below 80 bits of security are excluded. As a result RSA, DSA and DH keys shorter than 1024 bits and ECC keys shorter than 160 bits are prohibited. All export cipher suites are prohibited since they all offer less than 80 bits of security. SSL version 2 is prohibited. Any cipher suite using MD5 for the MAC is also prohibited. 927 928=item level 2 929 930Security level set to 112 bits of security. As a result RSA, DSA and DH keys shorter than 2048 bits and ECC keys shorter than 224 bits are prohibited. In addition to the level 1 exclusions any cipher suite using RC4 is also prohibited. SSL version 3 is also not allowed. Compression is disabled. 931 932=item level 3 933 934Security level set to 128 bits of security. As a result RSA, DSA and DH keys shorter than 3072 bits and ECC keys shorter than 256 bits are prohibited. In addition to the level 2 exclusions cipher suites not offering forward secrecy are prohibited. TLS versions below 1.1 are not permitted. Session tickets are disabled. 935 936=item level 4 937 938Security level set to 192 bits of security. As a result RSA, DSA and DH keys shorter than 7680 bits and ECC keys shorter than 384 bits are prohibited. Cipher suites using SHA1 for the MAC are prohibited. TLS versions below 1.2 are not permitted. 939 940=item level 5 941 942Security level set to 256 bits of security. As a result RSA, DSA and DH keys shorter than 15360 bits and ECC keys shorter than 512 bits are prohibited. 943 944=item default: 2 945 946=back 947 948The I<securityLevel> option is only available when compiled with B<OpenSSL 1.1.0> and later. 949 950=item B<requireCert> = yes | no 951 952require a client certificate for I<verifyChain> or I<verifyPeer> 953 954With I<requireCert> set to I<no>, the B<stunnel> server accepts client 955connections that did not present a certificate. 956 957Both I<verifyChain = yes> and I<verifyPeer = yes> imply I<requireCert = yes>. 958 959default: no 960 961=item B<setgid> = GROUP (Unix only) 962 963Unix group id 964 965As a global option: setgid() to the specified group in daemon mode and clear all other groups. 966 967As a service-level option: set the group of the Unix socket specified with "accept". 968 969=item B<setuid> = USER (Unix only) 970 971Unix user id 972 973As a global option: setuid() to the specified user in daemon mode. 974 975As a service-level option: set the owner of the Unix socket specified with "accept". 976 977=item B<sessionCacheSize> = NUM_ENTRIES 978 979session cache size 980 981I<sessionCacheSize> specifies the maximum number of the internal session cache 982entries. 983 984The value of 0 can be used for unlimited size. It is not recommended 985for production use due to the risk of a memory exhaustion DoS attack. 986 987=item B<sessionCacheTimeout> = TIMEOUT 988 989session cache timeout 990 991This is the number of seconds to keep cached TLS sessions. 992 993=item B<sessionResume> = yes | no 994 995allow or disallow session resumption 996 997default: yes 998 999=item B<sessiond> = HOST:PORT 1000 1001address of sessiond TLS cache server 1002 1003=item B<sni> = SERVICE_NAME:SERVER_NAME_PATTERN (server mode) 1004 1005Use the service as a slave service (a name-based virtual server) for Server 1006Name Indication TLS extension (RFC 3546). 1007 1008I<SERVICE_NAME> specifies the master service that accepts client connections 1009with the I<accept> option. I<SERVER_NAME_PATTERN> specifies the host name to 1010be redirected. The pattern may start with the '*' character, e.g. 1011'*.example.com'. Multiple slave services are normally specified for a single 1012master service. The I<sni> option can also be specified more than once within 1013a single slave service. 1014 1015This service, as well as the master service, may not be configured in client 1016mode. 1017 1018The I<connect> option of the slave service is ignored when the I<protocol> 1019option is specified, as I<protocol> connects to the remote host before TLS 1020handshake. 1021 1022Libwrap checks (Unix only) are performed twice: with the master service name 1023after TCP connection is accepted, and with the slave service name during the 1024TLS handshake. 1025 1026The I<sni> option is only available when compiled with B<OpenSSL 1.0.0> and 1027later. 1028 1029=item B<sni> = SERVER_NAME (client mode) 1030 1031Use the parameter as the value of TLS Server Name Indication (RFC 3546) 1032extension. 1033 1034Empty SERVER_NAME disables sending the SNI extension. 1035 1036The I<sni> option is only available when compiled with B<OpenSSL 1.0.0> and 1037later. 1038 1039=item B<socket> = a|l|r:OPTION=VALUE[:VALUE] 1040 1041Set an option on the accept/local/remote socket 1042 1043The values for the linger option are l_onof:l_linger. 1044The values for the time are tv_sec:tv_usec. 1045 1046Examples: 1047 1048 socket = l:SO_LINGER=1:60 1049 set one minute timeout for closing local socket 1050 socket = r:SO_OOBINLINE=yes 1051 place out-of-band data directly into the 1052 receive data stream for remote sockets 1053 socket = a:SO_REUSEADDR=no 1054 disable address reuse (enabled by default) 1055 socket = a:SO_BINDTODEVICE=lo 1056 only accept connections on loopback interface 1057 1058=item B<sslVersion> = SSL_VERSION 1059 1060select the TLS protocol version 1061 1062Supported versions: all, SSLv2, SSLv3, TLSv1, TLSv1.1, TLSv1.2, TLSv1.3 1063 1064Availability of specific protocols depends on the linked OpenSSL library. 1065Older versions of OpenSSL do not support TLSv1.1, TLSv1.2 and TLSv1.3. 1066Newer versions of OpenSSL do not support SSLv2. 1067 1068Obsolete SSLv2 and SSLv3 are currently disabled by default. 1069 1070Setting the option 1071 1072 sslVersion = SSL_VERSION 1073 1074is equivalent to options 1075 1076 sslVersionMax = SSL_VERSION 1077 sslVersionMin = SSL_VERSION 1078 1079when compiled with B<OpenSSL 1.1.0> and later. 1080 1081=item B<sslVersionMax> = SSL_VERSION 1082 1083maximum supported protocol versions 1084 1085Supported versions: all, SSLv3, TLSv1, TLSv1.1, TLSv1.2, TLSv1.3 1086 1087I<all> enable protocol versions up to the highest version supported by the 1088linked OpenSSL library. 1089 1090Availability of specific protocols depends on the linked OpenSSL library. 1091 1092The I<sslVersionMax> option is only available when compiled with B<OpenSSL 1.1.0> and later. 1093 1094default: all 1095 1096=item B<sslVersionMin> = SSL_VERSION 1097 1098minimum supported protocol versions 1099 1100Supported versions: all, SSLv3, TLSv1, TLSv1.1, TLSv1.2, TLSv1.3 1101 1102I<all> enable protocol versions down to the lowest version supported by the 1103linked OpenSSL library. 1104 1105Availability of specific protocols depends on the linked OpenSSL library. 1106 1107The I<sslVersionMin> option is only available when compiled with B<OpenSSL 1.1.0> and later. 1108 1109default: TLSv1 1110 1111=item B<stack> = BYTES (except for FORK model) 1112 1113CPU stack size of created threads 1114 1115Excessive thread stack size increases virtual memory usage. 1116Insufficient thread stack size may cause application crashes. 1117 1118default: 65536 bytes (sufficient for all platforms we tested) 1119 1120=item B<ticketKeySecret> = SECRET 1121 1122hexadecimal symmetric key used for session ticket confidentiality protection 1123 1124Session tickets defined in RFC 5077 provide an enhanced session resumption 1125capability, where the server-side caching is not required to maintain per 1126session state. 1127 1128Combining I<ticketKeySecret> and I<ticketMacSecret> options allow to resume a 1129negotiated session on other cluster nodes, or to resume a negotiated 1130session after server restart. 1131 1132The key is required to be either 16 or 32 bytes long, which implies exactly 32 1133or 64 hexadecimal digits. Colons may optionally be used between two-character 1134hexadecimal bytes. 1135 1136This option only works in server mode. 1137 1138The I<ticketKeySecret> option is only available when compiled with 1139B<OpenSSL 1.0.0> and later. 1140 1141Disabling I<NO_TICKET> option is required for the ticket support in OpenSSL 1142older than 1.1.1, but note that this option is incompatible with the 1143I<redirect> option. 1144 1145=item B<ticketMacSecret> = SECRET 1146 1147hexadecimal symmetric key used for session ticket integrity protection 1148 1149The key is required to be either 16 or 32 bytes long, which implies exactly 32 1150or 64 hexadecimal digits. Colons may optionally be used between two-character 1151hexadecimal bytes. 1152 1153This option only works in server mode. 1154 1155The I<ticketMacSecret> option is only available when compiled with 1156B<OpenSSL 1.0.0> and later. 1157 1158=item B<TIMEOUTbusy> = SECONDS 1159 1160time to wait for expected data 1161 1162=item B<TIMEOUTclose> = SECONDS 1163 1164time to wait for close_notify (set to 0 for buggy MSIE) 1165 1166=item B<TIMEOUTconnect> = SECONDS 1167 1168time to wait to connect to a remote host 1169 1170=item B<TIMEOUTidle> = SECONDS 1171 1172time to keep an idle connection 1173 1174=item B<transparent> = none | source | destination | both (Unix only) 1175 1176enable transparent proxy support on selected platforms 1177 1178Supported values: 1179 1180=over 4 1181 1182=item I<none> 1183 1184Disable transparent proxy support. This is the default. 1185 1186=item I<source> 1187 1188Re-write the address to appear as if a wrapped daemon is connecting 1189from the TLS client machine instead of the machine running B<stunnel>. 1190 1191This option is currently available in: 1192 1193=over 4 1194 1195=item Remote mode (I<connect> option) on I<Linux E<gt>=2.6.28> 1196 1197This configuration requires B<stunnel> to be executed as root and without 1198the I<setuid> option. 1199 1200This configuration requires the following setup for iptables and routing 1201(possibly in /etc/rc.local or equivalent file): 1202 1203 iptables -t mangle -N DIVERT 1204 iptables -t mangle -A PREROUTING -p tcp -m socket -j DIVERT 1205 iptables -t mangle -A DIVERT -j MARK --set-mark 1 1206 iptables -t mangle -A DIVERT -j ACCEPT 1207 ip rule add fwmark 1 lookup 100 1208 ip route add local 0.0.0.0/0 dev lo table 100 1209 echo 0 >/proc/sys/net/ipv4/conf/lo/rp_filter 1210 1211B<stunnel> must also to be executed as root and without the I<setuid> option. 1212 1213=item Remote mode (I<connect> option) on I<Linux 2.2.x> 1214 1215This configuration requires the kernel to be compiled with the I<transparent proxy> 1216option. 1217Connected service must be installed on a separate host. 1218Routing towards the clients has to go through the B<stunnel> box. 1219 1220B<stunnel> must also to be executed as root and without the I<setuid> option. 1221 1222=item Remote mode (I<connect> option) on I<FreeBSD E<gt>=8.0> 1223 1224This configuration requires additional firewall and routing setup. 1225B<stunnel> must also to be executed as root and without the I<setuid> option. 1226 1227=item Local mode (I<exec> option) 1228 1229This configuration works by pre-loading the I<libstunnel.so> shared library. 1230_RLD_LIST environment variable is used on Tru64, and LD_PRELOAD variable on 1231other platforms. 1232 1233=back 1234 1235=item I<destination> 1236 1237The original destination is used instead of the I<connect> option. 1238 1239A service section for transparent destination may look like this: 1240 1241 [transparent] 1242 client = yes 1243 accept = <stunnel_port> 1244 transparent = destination 1245 1246This configuration requires iptables setup to work, 1247possibly in /etc/rc.local or equivalent file. 1248 1249For a connect target installed on the same host: 1250 1251 /sbin/iptables -t nat -I OUTPUT -p tcp --dport <redirected_port> \ 1252 -m ! --uid-owner <stunnel_user_id> \ 1253 -j DNAT --to-destination <local_ip>:<stunnel_port> 1254 1255For a connect target installed on a remote host: 1256 1257 /sbin/iptables -I INPUT -i eth0 -p tcp --dport <stunnel_port> -j ACCEPT 1258 /sbin/iptables -t nat -I PREROUTING -p tcp --dport <redirected_port> \ 1259 -i eth0 -j DNAT --to-destination <local_ip>:<stunnel_port> 1260 1261The transparent destination option is currently only supported on Linux. 1262 1263=item I<both> 1264 1265Use both I<source> and I<destination> transparent proxy. 1266 1267=back 1268 1269Two legacy options are also supported for backward compatibility: 1270 1271=over 4 1272 1273=item I<yes> 1274 1275This option has been renamed to I<source>. 1276 1277=item I<no> 1278 1279This option has been renamed to I<none>. 1280 1281=back 1282 1283=item B<verify> = LEVEL 1284 1285verify the peer certificate 1286 1287This option is obsolete and should be replaced with the I<verifyChain> 1288and I<verifyPeer> options. 1289 1290=over 4 1291 1292=item level 0 1293 1294Request and ignore the peer certificate. 1295 1296=item level 1 1297 1298Verify the peer certificate if present. 1299 1300=item level 2 1301 1302Verify the peer certificate. 1303 1304=item level 3 1305 1306Verify the peer against a locally installed certificate. 1307 1308=item level 4 1309 1310Ignore the chain and only verify the peer certificate. 1311 1312=item default 1313 1314No verify. 1315 1316=back 1317 1318=item B<verifyChain> = yes | no 1319 1320verify the peer certificate chain starting from the root CA 1321 1322For server certificate verification it is essential to also require a specific 1323certificate with I<checkHost> or I<checkIP>. 1324 1325The self-signed root CA certificate needs to be stored either in the file 1326specified with I<CAfile>, or in the directory specified with I<CApath>. 1327 1328default: no 1329 1330=item B<verifyPeer> = yes | no 1331 1332verify the peer certificate 1333 1334The peer certificate needs to be stored either in the file 1335specified with I<CAfile>, or in the directory specified with I<CApath>. 1336 1337default: no 1338 1339=back 1340 1341 1342=head1 RETURN VALUE 1343 1344B<stunnel> returns zero on success, non-zero on error. 1345 1346 1347=head1 SIGNALS 1348 1349The following signals can be used to control B<stunnel> in Unix environment: 1350 1351=over 4 1352 1353=item SIGHUP 1354 1355Force a reload of the configuration file. 1356 1357Some global options will not be reloaded: 1358 1359=over 4 1360 1361=item * 1362 1363chroot 1364 1365=item * 1366 1367foreground 1368 1369=item * 1370 1371pid 1372 1373=item * 1374 1375setgid 1376 1377=item * 1378 1379setuid 1380 1381=back 1382 1383The use of the 'setuid' option will also prevent B<stunnel> from binding to privileged 1384(<1024) ports during configuration reloading. 1385 1386When the 'chroot' option is used, B<stunnel> will look for all its files (including 1387the configuration file, certificates, the log file and the pid file) within the chroot 1388jail. 1389 1390=item SIGUSR1 1391 1392Close and reopen the B<stunnel> log file. 1393This function can be used for log rotation. 1394 1395=item SIGUSR2 1396 1397Log the list of active connections. 1398 1399=item SIGTERM, SIGQUIT, SIGINT 1400 1401Shut B<stunnel> down. 1402 1403=back 1404 1405The result of sending any other signals to the server is undefined. 1406 1407 1408=head1 EXAMPLES 1409 1410In order to provide TLS encapsulation to your local I<imapd> service, use: 1411 1412 [imapd] 1413 accept = 993 1414 exec = /usr/sbin/imapd 1415 execArgs = imapd 1416 1417or in remote mode: 1418 1419 [imapd] 1420 accept = 993 1421 connect = 143 1422 1423In order to let your local e-mail client connect to a TLS-enabled I<imapd> 1424service on another server, configure the e-mail client to connect to localhost 1425on port 119 and use: 1426 1427 [imap] 1428 client = yes 1429 accept = 143 1430 connect = servername:993 1431 1432If you want to provide tunneling to your I<pppd> daemon on port 2020, 1433use something like: 1434 1435 [vpn] 1436 accept = 2020 1437 exec = /usr/sbin/pppd 1438 execArgs = pppd local 1439 pty = yes 1440 1441If you want to use B<stunnel> in I<inetd> mode to launch your imapd 1442process, you'd use this I<stunnel.conf>. 1443Note there must be no I<[service_name]> section. 1444 1445 exec = /usr/sbin/imapd 1446 execArgs = imapd 1447 1448To setup SOCKS VPN configure the following client service: 1449 1450 [socks_client] 1451 client = yes 1452 accept = 127.0.0.1:1080 1453 connect = vpn_server:9080 1454 verifyPeer = yes 1455 CAfile = stunnel.pem 1456 1457The corresponding configuration on the vpn_server host: 1458 1459 [socks_server] 1460 protocol = socks 1461 accept = 9080 1462 cert = stunnel.pem 1463 key = stunnel.key 1464 1465Now test your configuration on the client machine with: 1466 1467 curl --socks4a localhost http://www.example.com/ 1468 1469An example server mode SNI configuration: 1470 1471 [virtual] 1472 ; master service 1473 accept = 443 1474 cert = default.pem 1475 connect = default.internal.mydomain.com:8080 1476 1477 [sni1] 1478 ; slave service 1 1479 sni = virtual:server1.mydomain.com 1480 cert = server1.pem 1481 connect = server1.internal.mydomain.com:8081 1482 1483 [sni2] 1484 ; slave service 2 1485 sni = virtual:server2.mydomain.com 1486 cert = server2.pem 1487 connect = server2.internal.mydomain.com:8082 1488 verifyPeer = yes 1489 CAfile = server2-allowed-clients.pem 1490 1491An example of advanced engine configuration allows for authentication with private keys 1492stored in the Windows certificate store (Windows only). 1493With the CAPI engine you don't need to manually select the client key to use. 1494The client key is automatically selected based on the list of CAs trusted by the server. 1495 1496 engine = capi 1497 1498 [service] 1499 engineId = capi 1500 client = yes 1501 accept = 127.0.0.1:8080 1502 connect = example.com:8443 1503 1504An example of advanced engine configuration to use the certificate and the corresponding private key from a pkcs11 engine: 1505 1506 engine = pkcs11 1507 engineCtrl = MODULE_PATH:opensc-pkcs11.so 1508 engineCtrl = PIN:123456 1509 1510 [service] 1511 engineId = pkcs11 1512 client = yes 1513 accept = 127.0.0.1:8080 1514 connect = example.com:843 1515 cert = pkcs11:token=MyToken;object=MyCert 1516 key = pkcs11:token=MyToken;object=MyKey 1517 1518An example of advanced engine configuration to use the certificate and the corresponding private key from a SoftHSM token: 1519 1520 engine = pkcs11 1521 engineCtrl = MODULE_PATH:softhsm2.dll 1522 engineCtrl = PIN:12345 1523 1524 [service] 1525 engineId = pkcs11 1526 client = yes 1527 accept = 127.0.0.1:8080 1528 connect = example.com:843 1529 cert = pkcs11:token=MyToken;object=KeyCert 1530 1531 1532=head1 NOTES 1533 1534=head2 RESTRICTIONS 1535 1536B<stunnel> cannot be used for the FTP daemon because of the nature 1537of the FTP protocol which utilizes multiple ports for data transfers. 1538There are available TLS-enabled versions of FTP and telnet daemons, however. 1539 1540 1541=head2 INETD MODE 1542 1543The most common use of B<stunnel> is to listen on a network 1544port and establish communication with either a new port 1545via the connect option, or a new program via the I<exec> option. 1546However there is a special case when you wish to have 1547some other program accept incoming connections and 1548launch B<stunnel>, for example with I<inetd>, I<xinetd>, 1549or I<tcpserver>. 1550 1551For example, if you have the following line in I<inetd.conf>: 1552 1553 imaps stream tcp nowait root @bindir@/stunnel stunnel @sysconfdir@/stunnel/imaps.conf 1554 1555In these cases, the I<inetd>-style program is responsible 1556for binding a network socket (I<imaps> above) and handing 1557it to B<stunnel> when a connection is received. 1558Thus you do not want B<stunnel> to have any I<accept> option. 1559All the I<Service Level Options> should be placed in the 1560global options section, and no I<[service_name]> section 1561will be present. See the I<EXAMPLES> section for example 1562configurations. 1563 1564=head2 CERTIFICATES 1565 1566Each TLS-enabled daemon needs to present a valid X.509 certificate 1567to the peer. It also needs a private key to decrypt the incoming 1568data. The easiest way to obtain a certificate and a key is to 1569generate them with the free B<OpenSSL> package. You can find more 1570information on certificates generation on pages listed below. 1571 1572The I<.pem> file should contain the unencrypted private key and 1573a signed certificate (not certificate request). 1574So the file should look like this: 1575 1576 -----BEGIN RSA PRIVATE KEY----- 1577 [encoded key] 1578 -----END RSA PRIVATE KEY----- 1579 -----BEGIN CERTIFICATE----- 1580 [encoded certificate] 1581 -----END CERTIFICATE----- 1582 1583=head2 RANDOMNESS 1584 1585B<stunnel> needs to seed the PRNG (pseudo-random number generator) in 1586order for TLS to use good randomness. The following sources are loaded 1587in order until sufficient random data has been gathered: 1588 1589=over 4 1590 1591=item * 1592 1593The file specified with the I<RNDfile> flag. 1594 1595=item * 1596 1597The file specified by the RANDFILE environment variable, if set. 1598 1599=item * 1600 1601The file .rnd in your home directory, if RANDFILE not set. 1602 1603=item * 1604 1605The file specified with '--with-random' at compile time. 1606 1607=item * 1608 1609The contents of the screen if running on Windows. 1610 1611=item * 1612 1613The egd socket specified with the I<EGD> flag. 1614 1615=item * 1616 1617The egd socket specified with '--with-egd-sock' at compile time. 1618 1619=item * 1620 1621The /dev/urandom device. 1622 1623=back 1624 1625Note that on Windows machines that do not have console user interaction 1626(mouse movements, creating windows, etc.) the screen contents are not 1627variable enough to be sufficient, and you should provide a random file 1628for use with the I<RNDfile> flag. 1629 1630Note that the file specified with the I<RNDfile> flag should contain 1631random data -- that means it should contain different information 1632each time B<stunnel> is run. This is handled automatically 1633unless the I<RNDoverwrite> flag is used. If you wish to update this file 1634manually, the I<openssl rand> command in recent versions of B<OpenSSL>, 1635would be useful. 1636 1637Important note: If /dev/urandom is available, B<OpenSSL> often seeds the PRNG 1638with it while checking the random state. On systems with /dev/urandom 1639B<OpenSSL> is likely to use it even though it is listed at the very bottom of 1640the list above. This is the behaviour of B<OpenSSL> and not B<stunnel>. 1641 1642=head2 DH PARAMETERS 1643 1644B<stunnel> 4.40 and later contains hardcoded 2048-bit DH parameters. Starting 1645with B<stunnel> 5.18, these hardcoded DH parameters are replaced every 24 hours 1646with autogenerated temporary DH parameters. DH parameter generation may take 1647several minutes. 1648 1649Alternatively, it is possible to specify static DH parameters in the 1650certificate file, which disables generating temporary DH parameters: 1651 1652 openssl dhparam 2048 >> stunnel.pem 1653 1654 1655=head1 FILES 1656 1657=over 4 1658 1659=item F<@sysconfdir@/stunnel/stunnel.conf> 1660 1661B<stunnel> configuration file 1662 1663=back 1664 1665 1666=head1 BUGS 1667 1668The I<execArgs> option and the Win32 command line do not support quoting. 1669 1670 1671=head1 SEE ALSO 1672 1673=over 4 1674 1675=item L<tcpd(8)> 1676 1677access control facility for internet services 1678 1679=item L<inetd(8)> 1680 1681internet 'super-server' 1682 1683=item F<http://www.stunnel.org/> 1684 1685B<stunnel> homepage 1686 1687=item F<http://www.openssl.org/> 1688 1689B<OpenSSL> project website 1690 1691=back 1692 1693 1694=head1 AUTHOR 1695 1696=over 4 1697 1698=item Michał Trojnara 1699 1700<F<Michal.Trojnara@stunnel.org>> 1701 1702=back 1703 1704=for comment 1705vim:spelllang=en:spell 1706