From c2fc3cb977d35fa66bc9a73f53879b8d282992f8 Mon Sep 17 00:00:00 2001 From: "William A. Rowe Jr" Date: Thu, 30 May 2002 17:37:54 +0000 Subject: [PATCH] As we find the right places for this content, move them out in bits git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@95405 13f79535-47bb-0310-9956-ffa450edef68 --- modules/ssl/README | 193 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 193 insertions(+) create mode 100644 modules/ssl/README diff --git a/modules/ssl/README b/modules/ssl/README new file mode 100644 index 0000000000..15de7fe649 --- /dev/null +++ b/modules/ssl/README @@ -0,0 +1,193 @@ + _ _ + _ __ ___ ___ __| | ___ ___| | + | '_ ` _ \ / _ \ / _` | / __/ __| | + | | | | | | (_) | (_| | \__ \__ \ | ``mod_ssl combines the flexibility of + |_| |_| |_|\___/ \__,_|___|___/___/_| Apache with the security of OpenSSL.'' + |_____| + mod_ssl ``Ralf Engelschall has released an + Apache Interface to OpenSSL excellent module that integrates + http://www.modssl.org/ Apache and SSLeay.'' + Version 2.8 -- Tim J. Hudson + + SYNOPSIS + + This Apache module provides strong cryptography for the Apache 1.3 webserver + via the Secure Sockets Layer (SSL v2/v3) and Transport Layer Security (TLS + v1) protocols by the help of the SSL/TLS implementation library OpenSSL which + is based on SSLeay from Eric A. Young and Tim J. Hudson. The mod_ssl package + was created in April 1998 by Ralf S. Engelschall and was originally derived + from software developed by Ben Laurie for use in the Apache-SSL HTTP server + project. + + SOURCES + + Here is a short overview of the source files: + + * README .................. This file ;) + # Makefile.in ............. Makefile template for Unix platform + # config.m4 ............... Autoconf stub for the Apache config mechanism + # mod_ssl.c ............... main source file containing API structures + # mod_ssl.h ............... common header file of mod_ssl + # ssl_engine_config.c ..... module configuration handling + # ssl_engine_dh.c ......... DSA/DH support + # ssl_engine_init.c ....... module initialization + # ssl_engine_io.c ......... I/O support + # ssl_engine_kernel.c ..... SSL engine kernel + # ssl_engine_log.c ........ logfile support + # ssl_engine_mutex.c ...... mutual exclusion support + # ssl_engine_pphrase.c .... pass-phrase handling + # ssl_engine_rand.c ....... PRNG support + # ssl_engine_vars.c ....... Variable Expansion support + # ssl_expr.c .............. expression handling main source + # ssl_expr.h .............. expression handling common header + # ssl_expr_scan.c ......... expression scanner automaton (pre-generated) + # ssl_expr_scan.l ......... expression scanner source + # ssl_expr_parse.c ........ expression parser automaton (pre-generated) + # ssl_expr_parse.h ........ expression parser header (pre-generated) + # ssl_expr_parse.y ........ expression parser source + # ssl_expr_eval.c ......... expression machine evaluation + # ssl_scache.c ............ session cache abstraction layer + # ssl_scache_dbm.c ........ session cache via DBM file + ~ ssl_scache_shmcb.c ...... session cache via shared memory cyclic buffer + ~ ssl_scache_shmht.c ...... session cache via shared memory hash table + # ssl_util.c .............. utility functions + # ssl_util_ssl.c .......... the OpenSSL companion source + # ssl_util_ssl.h .......... the OpenSSL companion header + # ssl_util_table.c ........ the hash table library source + # ssl_util_table.h ........ the hash table library header + + Legend: # = already ported to Apache 2.0 and is cleaned up + * = ported to Apache 2.0 but still needs cleaning up + ~ = ported to Apache 2.0 but still needs work + - = port still not finished + + The source files are written in clean ANSI C and pass the ``gcc -O -g + -ggdb3 -Wall -Wshadow -Wpointer-arith -Wcast-align -Wmissing-prototypes + -Wmissing-declarations -Wnested-externs -Winline'' compiler test + (assuming `gcc' is GCC 2.95.2 or newer) without any complains. When + you make changes or additions make sure the source still passes this + compiler test. + + FUNCTIONS + + Inside the source code you will be confronted with the following types of + functions which can be identified by their prefixes: + + ap_xxxx() ............... Apache API function + ssl_xxxx() .............. mod_ssl function + SSL_xxxx() .............. OpenSSL function (SSL library) + OpenSSL_xxxx() .......... OpenSSL function (SSL library) + X509_xxxx() ............. OpenSSL function (Crypto library) + PEM_xxxx() .............. OpenSSL function (Crypto library) + EVP_xxxx() .............. OpenSSL function (Crypto library) + RSA_xxxx() .............. OpenSSL function (Crypto library) + + DATA STRUCTURES + + Inside the source code you will be confronted with the following + data structures: + + server_rec .............. Apache (Virtual) Server + conn_rec ................ Apache Connection + request_rec ............. Apache Request + SSLModConfig ............ mod_ssl (Global) Module Configuration + SSLSrvConfig ............ mod_ssl (Virtual) Server Configuration + SSLDirConfig ............ mod_ssl Directory Configuration + SSLConnConfig ........... mod_ssl Connection Configuration + SSLFilterRec ............ mod_ssl Filter Context + SSL_CTX ................. OpenSSL Context + SSL_METHOD .............. OpenSSL Protocol Method + SSL_CIPHER .............. OpenSSL Cipher + SSL_SESSION ............. OpenSSL Session + SSL ..................... OpenSSL Connection + BIO ..................... OpenSSL Connection Buffer + + For an overview how these are related and chained together have a look at the + page in README.dsov.{fig,ps}. It contains overview diagrams for those data + structures. It's designed for DIN A4 paper size, but you can easily generate + a smaller version inside XFig by specifing a magnification on the Export + panel. + + EXPERIMENTAL CODE + + Experimental code is always encapsulated as following: + + | #ifdef SSL_EXPERIMENTAL_xxxx + | ... + | #endif + + This way it is only compiled in when this define is enabled with + the APACI --enable-rule=SSL_EXPERIMENTAL option and as long as the + C pre-processor variable SSL_EXPERIMENTAL_xxxx_IGNORE is _NOT_ + defined (via CFLAGS). Or in other words: SSL_EXPERIMENTAL enables all + SSL_EXPERIMENTAL_xxxx variables, except if SSL_EXPERIMENTAL_xxxx_IGNORE + is already defined. Currently the following features are experimental: + + o SSL_EXPERIMENTAL_ENGINE + The ability to support the new forthcoming OpenSSL ENGINE stuff. + Until this development branch of OpenSSL is merged into the main + stream, you have to use openssl-engine-0.9.x.tar.gz for this. + mod_ssl automatically recognizes this OpenSSL variant and then can + activate external crypto devices through SSLCryptoDevice directive. + + INCOMPATIBILITIES + + The following intentional incompatibilities exist between mod_ssl 2.x + from Apache 1.3 and this mod_ssl version for Apache 2.0: + + o The complete EAPI-based SSL_VENDOR stuff was removed. + o The complete EAPI-based SSL_COMPAT stuff was removed. + o The variable MOD_SSL is no longer provided automatically + + MAJOR CHANGES + + The following major changes were made between mod_ssl 2.x + from Apache 1.3 and this mod_ssl version for Apache 2.0: + + o The DBM based session cache is now based on APR's DBM API only. + o The shared memory based session cache is now based on APR's APIs. + o SSL I/O is now implemented in terms of filters rather than BUFF + o Eliminated ap_global_ctx. Storing Persistant information in + process_rec->pool->user_data. The ssl_pphrase_Handle_CB() and + ssl_config_global_* () functions have an extra parameter now - + "server_rec *" - which is used to retrieve the SSLModConfigRec. + o Properly support restarts, allowing mod_ssl to be added to a server + that is already running and to change server certs/keys on restart + o Various performance enhancements + o proxy support is no longer an "extension", much of the mod_ssl core + was re-written (ssl_engine_{init,kernel,config}.c) to be generic so + it could be re-used in proxy mode. + - the optional function ssl_proxy_enable is provide for mod_proxy + to enable proxy support + - proxy support now requires 'SSLProxyEngine on' to be configured + - proxy now supports SSLProxyCARevocation{Path,File} in addition to + the original SSLProxy* directives + o per-directory SSLCACertificate{File,Path} is now thread-safe but + requires SSL_set_cert_store patch to OpenSSL + o RSA sslc is supported via ssl_toolkit_compat.h + o the ssl_engine_{ds,ext}.c source files are obsolete and no longer + exist + + TODO + + o SSL renegotiations in combination with POST request + o Port all remaining code (code inside #if 0...#endif blocks) + o Do we need SSL_set_read_ahead()? + o the ssl_expr api is NOT THREAD SAFE. race conditions exist: + -in ssl_expr_comp() if SSLRequire is used in .htaccess + (ssl_expr_info is global) + -is ssl_expr_eval() if there is an error + (ssl_expr_error is global) + o SSLRequire directive (parsing of) leaks memory + o Diffie-Hellman-Parameters for temporary keys are hardcoded in + ssl_engine_dh.c, while the comment in ssl_engine_kernel.c says: + "it is suggested that keys be changed daily or every 500 + transactions, and more often if possible." + o ssl_var_lookup could be rewritten to be MUCH faster + o CRL callback should be pluggable + o session cache store should be pluggable + o init functions should return status code rather than ssl_die() + o ssl_engine_pphrase.c needs to be reworked so it is generic enough + to also decrypt proxy keys + o the shmcb code should just align its memory segment rather than + jumping through all the "safe" memcpy and memset hoops -- 2.40.0