diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/CHAIN-SSL | 54 | ||||
| -rw-r--r-- | doc/CHANGES | 341 | ||||
| -rw-r--r-- | doc/LICENSE | 70 | ||||
| -rwxr-xr-x | doc/README.rts | 78 | ||||
| -rw-r--r-- | doc/TLSVERSION_CIPHERSUITES | 62 | ||||
| -rw-r--r-- | doc/TLS_1_3 | 36 | ||||
| -rw-r--r-- | doc/TODO | 7 | ||||
| -rw-r--r-- | doc/UCSPI-SSL | 48 |
8 files changed, 696 insertions, 0 deletions
diff --git a/doc/CHAIN-SSL b/doc/CHAIN-SSL new file mode 100644 index 0000000..9180ae2 --- /dev/null +++ b/doc/CHAIN-SSL @@ -0,0 +1,54 @@ +SSL UCSPI Certificate Chain Support +----------------------------------- + +Scope: +----- + +This version of UCSPI-SSL allows the SSL server to issue certificate chains. +In this case, the SSL client does not need to verify the certificates on +his own behalf, rather the client uses the presented certificates from the server. +However, the final root certificate has to be known by the client. + + +Usage: +----- + +1. Concatinate all relevant X.509 certifcates in one file. + The first one is the certificate of the server, the last one + should be the root certificate. + +2. Tell the sslserver the name and location of this file. + Use the environment variable CERTCHAINFILE. + +3. Provide a separate keyfile for your own (the first certificate) + employing the environment variable KEYFILE. + +4. If this variable variable is present, it takes precedence over + CERTFILE. + + +UI considerations: +----------------- + +a) Providing a particular cipher for sslclient is now facilited with + option "-z cipher" instead of "-C cipher". + +b) Reversely, the location of the certificate chain file is available + via option "-C certchainfile". + +c) For sslserver use the environment variable CERTCHAINFILE. + + +Security considerations: +----------------------- + +Your own keyfile can be password protected. + + +Performance considerations: +-------------------------- + +The server needs to open one thread per certificate. +Thus, the server carries the burden to provide the certificates. + +Erwin Hoffmann - 2011-02-16 diff --git a/doc/CHANGES b/doc/CHANGES new file mode 100644 index 0000000..9510cdb --- /dev/null +++ b/doc/CHANGES @@ -0,0 +1,341 @@ +20011209 + Initial release. + version: 0.50 + +20021207 + Convert to new build project. + Update libraries. + Correct load ordering for ssl programs. + +20030118 + Option to set TCP environment variables. + Option to set SSL environment variables a la mod_perl. + Added sslperl. + Correct closure handling in ssl_io.c. + +20030128 + Correct setting of TCPREMOTEINFO. + +20040127 + Improved env tracking in handlers. + Updated tests. + +20040204 + Clean up signal handling, process usage. + +20040209 + Added nN options to sslclient. + +20040313 + Added conf-ssl. + Version 0.65. + +20040317 + Delete conf-home. + Permit nN opts in sslclient. + Version 0.66. + +20040320 + Allow sslclient to avoid server verification. + Support cipher selection. + Correct execution botch in sslperl. + Clean up ssl_io and signal interaction. + Version 0.67. + +20040502 + Read SSL setup info before dropping privilege. + Version 0.68. + +20050417 + Don't fail on setsid if already group leader (Gabriel Russell). + Add compatibility macros for older Perl. + Don't leak pointer returned from eval_pv. + Support for partial testing. + Remove dependency on daemontools from rts. + +20050515 + Partial-install bug fix in package/upgrade. + +20050605 + Don't lose file descriptors in sslclient (Paul Jarc). + +20050610 + Close socket for deny rule (Fred Lindberg). + +20050703 + Revise ssl_io. + Free ssl object in sslhandle.c. + Add progtimeout option. + +20050717 + Version 0.70. + +20090811 + Included ucspi-ssl-0.70_ucspitls-0.6.patch (STARTTLS support) + originally designed and provided by Scott Gifford (FEH). + +20100319 + Added Certchain support for sslserver and sslclient (FEH). + +20120217 + Integration and added man-pages (FEH). + Version 0.80. + +20120921 + Synced with ucspi-tcp6-0.95. + Version 0.82 + +20121003 + Fixed integration bug in ssl_very.c. + Included patches from Peter Conrad. + Version 0.83. + +20121005 + Bug fix in sslserver. Several small + corrections. + Version 0.83a + +20121019 + Fix for large X509 serial numbers on x86 (tx. Peter Conrad). + SAN DNSname has precedence over CN in subject. + Re-edited man pages and rts tests. + Version 0.84. + +20130602 + Added IPv6 support (tx. to Felix von Leitner and Brandon Turner). + UI: Changed sslserver client cert call from '-i/-I' to '-z/-Z' + for compatibility reasons. + Added '-4/-6' support for client scripts. + Version 0.90. + +20130804 + Added output environment variables TCP6* for sslserver. + sslperl, sslhandle, and sslprint are not IPv6 ready yet. + Version 0.91 test. + +20130910 + Added IPv6 capabilities to sslhandle, sslprint, sslperl. + Changed verification of X.509 certs. + Removed obsolete socket_4 calls in sslserver. + Version 0.92 beta. + +20140112 + Streamlined code with ucspi-tcp6-1.00. + Supplied new certs with customized SAN. + Make rts working (at least some how). + +20140331 + Added support for personalized client certs. + New option '-m' in sslserver, complementing '-z'. + CCAFILE='-' disables client cert request. + Version 0.94 beta. + +20141221 + Added verbose log output for SSL connection informations. + Version 0.95a beta. + +20140208 + Fixed wrongly nested CONNECT error code for sslclient.c + producing wrong warning messages while connecting to + an IPv4 address. + Added call of '-ldl' in ssl.lib. + Version 0.95b beta. + +20151101 + Mitigation of SSL connection hanging during + coincident change of daylight-saving settings. + +20160228 + Fixed bug in sslserver's dnsip lookup in case of paranoid settings + and additonal existance of IPv6 AAAA records for incoming IPv4 connection. + Version 0.96. + +20160802 + Serveral fixes from 'troy@' included to cope with compiler errors and + to solve a bug in function getbitasaddress in ip4_bit.c (= ucspi-tcp6-1.02). + Reordered conf-* variables in main dir to allow easier generation of + packages (i.e. RPM). Fixed script to identify different HW architecture + and OS. This version works in 32 bit mode on Raspian Linux / RasPi 7. + + Added ECDH capabilites (tx to Frank Bergmann for the patches). + Version 0.97. + +20161226 + Added compatibility with LibreSSL. + Fixed missing negative return call treatment from 'poll' (tx Frank Bergmann). + Tentative 'emake' fix for Gentoo build. + Version 0.98a. + +20170209 + Added OpenSSL 1.1 tweaks -- works under Debian (9) 'Stretch'. + Version 0.99. + +20170308 + Included PID in sslserver + sslhandle abend logs in case of SSL failure. + Version 0.99a. + +20170617 + Convenience release: Removed references to 'gcc' and used 'cc' instead. + Version 0.99b. + +20170712 + Convenience release: Added `correct` pid display in error log. + +20171028 + Fixed cosmetic bug in sslserver displaying parent and not child pid in log. + Tx Bruce Guenter. + +20171105 + Clean ups. + +20180811 + Fixed missing 'return 0' in ssl_params.c for ECDH handshake (tx. J.W.). + Version 0.99e + +---- + +20180809 + Complete refurbish based on fehQlibs. + Native handling of IPv4/IPv6 address for sslclient. + Version 0.10 + +20180810 + Added experimental 'ecdhparam' file. + Version 0.10.1 + +20180816 + Removed experimental 'ecdhparam' handling -- OpenSSL does not support it. + fehQlibs-08 required. + Version 0.10.2 + +20181010 + Finished TLS 1.3 integration (based on OpenSSL 1.1.1). + Removed compiler flags for ECDH -- now required. + fehQlibs-09 based. + Version 0.10.6 + +20181109 + Better handling of read EAGAIN (sslserver may hang). + Include socket_dualstack option (required for OS with IPv6_V6ONLY). + fehQlibs-10 required. + Version 0.10.7 + +20190318 + Added dualstack handling for servers applying the + pseudo IP address ':0' on call (common now for all servers). + Tailored TLS error handling for EAGAIN end error codes. + Rewrote IPv4 CIDR address evaluation for rules. + Version 0.10.8 + +20190505 + Fixed broken evaluation of CIDR and IPv6 addresses; + adjusted with ucspi-tcp6-1.10.5. + Improved compatibility with LibreSSL and included description. + Version 0.10.9 + +20190608 + Added DSA/DSS (+ECC) signature verification additionally to RSA. + Added compatibility with fehQlibs-12. + Version 0.10.10 + +20190728 + Compatibility improvements for the forthcoming s/qmail. + Fixed potential stack corruption in sslclient/sslhande/sslserver + while assigning hostname => 0. + Improved OpenSSL + LibreSSL compatibility: + LibreSSL 2.5 to 2.9 is working + OpenSSL 1.0.2 to 1.1.1 is working + Added SNI for sslclient. + Fixes for sslhandle. + Included new CIPHERLIST API for ssl_ciphers. + Removed dependency on conf-tcpbin; modules are expected to be in the path. + Modules rts.base and rts.sslperl are working now. + Version 0.10.11 + +20190810 + Added compatibility with fehQlibs-13. + Fixed wrong behavior of sslserver/sslclient given a local or remote IPv4 + address. sslhandle is now an own program (man sslhandle.3). + Code streamlined with ucspi-tcp6-1.11.0. + +20191012 + Removed paranthesis from host in https@: [$host]:$port -> $host:port. Tx, A.E. + Version 0.11.0 + +20191021 + Fixed TLSv1* macro's names in ucspissl.h to match ssl_context.c. +20191107 + Clearified usage of 'SSL_CTX_set_ciphersuites()' in ssl_ciphers.c. + Version 0.11.1 +202002117 + Adopted some fixes contributed by Alan S. (mtx): + DNS IP Name qualification; X.509 DNS name matching; certs are only read on demand. + Support of STARTTLS in sslclient is postponed to next minor version. + Version 0.11.2 +20200221 + Straightend error codes and exiting for sslserver/sslhandle instead of dropping + the session in case of errors. + Version 0.11.3 +20200303 + Fixed iopause return value evaluation in remoteinfo.c. +20200323 + Removed return call evaluation of iopause in ssl_io.c and ssl_timeout.c + Not clear, whether this is resulting the polling. + Version 0.11.4 +20200730 + Added pollmax limit to sslserver and sslhandle. + sslclient streamlined with tcpclient. fehQlibs-15 are required. + Version 0.11.5 +20200920 + GCC 10 compliance enforced; removed it-perl from basic install. + Version 0.11.6a +20210319 + fehQlibs-17 changes included regarding socket interface. + Synced with ucspi-tcp6-1.12.3 providing MAXCONIP capabilities. + Successful integration tests for OpenSSL 3.0.0-alpha13 and LibreSSL 3.3.1. + Version 0.12.1 +20210325 + Fixed sslserver's binding to IPv4/IPv6 addresses; code aligned with tcpserver. + Version 0.12.2 +20211017 + sslhandle to bind to IPv4 sockets, if told so. + Compatibility tests with OpenSSL 3.0. Still preliminary. + Version 0.12.3 +20220824 + Fixed early logmsg() call in sslserver. + Version 0.12.3 +20221228 + Checked compatibility with LibreSSL 3.6/3.7. + The selected ciphers are now shown during start of sslserver/sslhandle. + Fixed duplicate symbol in sslhandle (Who). + Version 0.12.4 +20230403 + Included tests on tai_now in ssl_timeout.c and removed obsolete pollmax variables. + ssl_io.c closes TLS connection gracefully upon SSL_ERROR_SSL recognition + and not continue looping. + Version 0.12.5 +20230403 + ssl_io uses now two specific return codes under condition 'BOMB' avoiding unnecessary + error messages in case of TLS client termination. + Version 0.12.6 +20230529 + sslserver MAXCONIP feature is working now from the cdb read by the children. + MAXCONIP works even the general limit is 0. + Fixed wrong '-m' option for sslserver. + Added ip and port information in case sslserver/sslclient can't bind to local addresses. + Tweaked rts to include external load libraries. + Version 0.12.7 +20231010 + Added new x509 certs and key material; all ECC now. + Fixed wrong evaluation of peer cert in ssl_verify (none-critical). + Version 0.12.8 +20231128 + Included IP info in sslserver's TLS error messages for a quick lookup. + Fixed sslhandle's wrong if nesting. + sslserver return FATAL (and not ERROR) in case TLS is requested but missing. + Enhanced compatibility with OpenSSL 3.x.y. + Version 0.12.9 +20231204 + Added argument '-y cdb' to sslserver in order to allow a rule checking + for IP addresses prior of the DNS/IDENT lookup (to cope with DDos attacks). + Version 0.12.10 diff --git a/doc/LICENSE b/doc/LICENSE new file mode 100644 index 0000000..aea2c94 --- /dev/null +++ b/doc/LICENSE @@ -0,0 +1,70 @@ +AUTHOR +====== + +Author: + Dr. Erwin Hoffmann - FEHCom Germany +Web-Site: + https://www.fehcom.de/ipnet/ucspi-ssl.html +E-Mail: + feh@fehcom.de + +CONTRIBUTIONS +============= + +ucspi-ssl is based on William E. Baxter's (superscript.com) version used by permission: + https://www.superscript.com/ +which is put into the Public Domain. + +ucspi-ssl uses enhancements from Scott Gifford's and Charly Brady's API +to support STARTTLS communication: + https://github.com/scottgifford/ucspi-ssl +License state unknown + +LICENSE +======= + +Given these restrictions: + +ucspi-ssl is free software placed into the Public Domain. + +This includes: + You can download and use ucspi-ssl (and parts of it) as you like. + You can modify the source code without notification to or permission by the author. +Please check: + http://www.cr.yp.to/softwarelaw.html +Note: + ucspi-ssl depends on third party software with different + license and/or distribution conditions; in particular + - OpenSSL + - LibreSSL + + +DEPENDENCIES +============ + +ucspi-ssl depends on the following package: + - fehQlibs found on https://www/ipnet/qlibs.html +which is Public Domain as well. + + +Note: +----- + +The author of the program may unsolicitedly change the dependencies. +Thus, it is your obligation to follow and consider any changes! + + +FITNESS +======= + +The author does not guarantee a specific fitness of ucspi-ssl. +If you use ucspi-ssl, it's on your own risk. + + +DISTRIBUTION +============ + +ucspi-ssl may be included in ports and packages under the following conditions: + The port/package has to show the current version number of ucspi-ssl. + This license file has to be included in the distribution. + diff --git a/doc/README.rts b/doc/README.rts new file mode 100755 index 0000000..60ef73b --- /dev/null +++ b/doc/README.rts @@ -0,0 +1,78 @@ +Rudimentary Test System (RTS) +============================= + +History +------- + +Starting with ucspi-tcp, DJB introduced a script called 'rts.test' +to do some unit/system tests for the modules included in here. + +This piece of software was never documented nor its purpose was defined. +William Baxter modified it to work with ucspi-ssl. +DJB used it in the release of djbdns. + + +Components +---------- + +Within (slash)package 'rts' consists of the following pieces: + + a) package/rts [component] is a generic shell script. + b) src/rts.[it], src/rts.[component] are the scripts containing the specific unit tests. + src/rts.it is usually the supervising script, + while src/rts.base includes typically the 'basic' unit tests, + src/rts.[component] is optional. + c) src/exp.[it], src.[bases] and perhaps src/exp.[component] + include the expected results (adapted). + +While [it] and [base] are mandatory, any further [component] needs +to be defined by the (slash)package installation. + + +Defaults and Adjustments +------------------------ + + 1. In order to use rts, the binaries are expected to be install + at their default directories. + 2. Since ucspi-ssl depends on *SSL libraries, the shared libs + shall be available in their default locations. + 3. If you use custom installed *SSL libs, you need to modify + the LD_LIBRARY_PATH. See the file rts.base to get the idea. + + +Invocation +---------- + +'rts' is typically called after a successful compilation and installation. +The $PATH variable includes the current directory of the executed rts.it (./compile). +In order to test the included modules one calls: + + package/rts --> all tests are done (including optional) + package/rts base --> basic unit tests + package/rts [component] --> optional component test + + +Results +------- + +The script rts.[component] is executed in + + ./compile/rts-temp + +to be raised upon call. The results are written to + + ./compile/out.[component] + +and then diff'ed against exp.[component], cleaned up for trivial +run dependencies (like port numbers) and the difference is displayed. + +If there is no difference, nothing is displayed => working as expected. + +However, even if differences are given, they may be due to environment/call +dependencies (like process ids) resulting in some mangled output. + +In case package/rts is called again, the previous results are overwritten. + + +--eh (May, 2023). + diff --git a/doc/TLSVERSION_CIPHERSUITES b/doc/TLSVERSION_CIPHERSUITES new file mode 100644 index 0000000..645e44a --- /dev/null +++ b/doc/TLSVERSION_CIPHERSUITES @@ -0,0 +1,62 @@ +TLS Version & Cipher Suites +--------------------------- + +ucspi-ssl provides two hooks to adjust the TLS version and the Cipher Suite: + +1. Client and Server (sslclient, sslhandle, sslserver): + +The TLS/SSL protocol versions + +- SSLv2 and +- SSLv3 + +are disabled in ucspissl.h. + +- TLSv1 is already included here, but is still commented out. + + +2. The Cipher Suite accepted by the Server (sslhandle, sslserver) + +a) Pre-TLS 1.3 + +Here, you can adjust the settings by means of CIPHER environment variables. +Some typical choices: + +#CIPHERS="'TLSv1+HIGH:!SSLv2:!aNULL:!eNULL:!3DES:@STRENGTH'" +#CIPHERS="TLSv1+HIGH:!SSLv2:!MD5" +CIPHERS="TLSv1.2+HIGH:TLSv1.1+HIGH:!TLSv1+HIGH:!aNULL:!eNULL:@STRENGTH" + +This variable can be statically defined for all connections or used +as environment variable specified with the tcprule database. + +OpenSSL supports even very old and inscure crypto primites like MD5 or DES; +however under current circumstances they are not negotiated. + +b) TLS 1.3 + +While previous TLS understand some phrasings like 'DEFAULT', 'HIGH' in TLS 1.3 +a new API and a new scheme is used +(https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_set_cipher_list.html): + +>> An empty list is permissible. The default value for the this setting is: + + "TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256" << + +This means 'TLS_AES_256_GCM_SHA384' has priority. However, you can tweak this to: + + "TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256" + +thus, the first choice is CHACHA20. In case AES_256 is present, it has +precedence over CHACHA20. + +Remember: In any case, only ECDHE is used as handshake protocol. + + +3. Online Resources + +OpenSSL: https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_set_cipher_list.html + +LibreSSL: https://fossies.org/linux/libressl/man/SSL_CTX_set_cipher_list.3 + + +--eh, Oktober 2023. diff --git a/doc/TLS_1_3 b/doc/TLS_1_3 new file mode 100644 index 0000000..51c7c42 --- /dev/null +++ b/doc/TLS_1_3 @@ -0,0 +1,36 @@ +Installing ucspi-ssl with TLS 1.3 support +----------------------------------------- + +ucspi-ssl-0.10 can use TLS 1.3 capabilities alongside +with your system's previous *SSL installation: + +a) OpenSSL 1.1.1: + +- Download OpenSSL and untar OpenSSL at some path; ie. /usr/local. +- Execute./conf && make. Don't do 'make install'!! + +- conf-ssl: Include path to the header files via -I <path>. + (-I/usr/local/openssl-1.1.1/include) +- conf-ssllib: Include path to the libraries via -L <path>. + (-L/usr/local/openssl-1.1.1 -lssl -lcrypto) + +b) LibreSSL 2.9.x: + +Download LibreSSL and untar LibreSSL at some path; ie. /usr/local. +Execute./conf && make. Don't do 'make install'!! +Do a + ln -s ssl/.libs/libssl.so . + ln -s crypto/.libs/libcrypto.so . +in the LibreSSL main directory. + +- conf-ssl: Include path to the header files via -I <path>. + (-I/usr/local/libressl-2.9.1/include) +- conf-ssllib: Include path to the libraries via -L <path>. + (-L/usr/local/libressl-2.9.1 -lssl -lcrypto) + + + +Recompile ucspi-ssl. +This should be it. + +E. Hoffmann, September 2019. diff --git a/doc/TODO b/doc/TODO new file mode 100644 index 0000000..1c9da9b --- /dev/null +++ b/doc/TODO @@ -0,0 +1,7 @@ +Program like stunnel (web). +Rules tests (web). +CRL support (feh). +OCSPI support (feh). +DANE support (feh). +SSL connection caching (feh). +Migrate whole openssl stuff to wolfssl (bergmann). diff --git a/doc/UCSPI-SSL b/doc/UCSPI-SSL new file mode 100644 index 0000000..69bd25e --- /dev/null +++ b/doc/UCSPI-SSL @@ -0,0 +1,48 @@ +SSL UCSPI protocol definition +Copyright 2001 +SuperScript Technology, Inc. sst@superscript.com + +This document defines the SSL protocol for UCSPI-1996 tools. An SSL +client communicates with an SSL server, on the same machine or on a +different machine, via the TCP/IP protocol through an Internet-domain +socket. The descriptors passed to a SSL UCSPI application are copies of +that socket, dup()ed from a single connect() or accept(). + +[address] consists of two arguments: [hostname] [port]. + +There are three possibilities for [hostname]: the number 0, referring to +the local host; a dotted-decimal IP address, such as 192.48.96.5; or a +name understood by the system's resolver, such as mail.uu.net. SSL UCSPI +servers use only the first IP address from the resolver; SSL UCSPI +clients try each address in turn. + +There are three possibilities for [port]: a positive numeric TCP port +number, such as 25; the number 0, which permits selection of any port +number; or a name understood by the system's getservbyname(), such as +smtp. + +The client and server set up the following environment variables: + + PROTO: the string SSL + SSLLOCALIP: the dotted-decimal IP address of the local host + SSLLOCALPORT: the local SSL port number, in decimal + SSLREMOTEIP: the dotted-decimal IP address of the remote host + SSLREMOTEPORT: the remote SSL port number, in decimal + SSLLOCALHOST, if possible: the resolver's name for SSLLOCALIP + SSLREMOTEHOST, if possible: the resolver's name for SSLREMOTEIP + SSLREMOTEINFO, if possible: the result of a 931/1413/IDENT/TAP query + +Uppercase letters in SSLLOCALHOST and SSLREMOTEHOST are converted to +lowercase. SSLREMOTEINFO is a connection-specific string supplied by the +remote host via 931/1413/IDENT/TAP. + +SSL UCSPI tools take a -R option to turn off 931/1413/IDENT/TAP +querying, and a -r option to turn it back on. SSL UCSPI tools take a -I +option to turn off checking for a client certificate, and a -i option to +turn it back on. SSL UCSPI clients take a -p [locport] option to +require a particular TCP port on the local side of the connection. SSL +UCSPI servers take a -1 option to print the local port number (in +decimal, followed by a newline) to descriptor 1 before closing +descriptor 1 and after preparing to receive connections. SSL UCSPI +servers and clients take a -3 option to read a null-terminated key +password from file descriptor 3. |