mirror of
https://github.com/apache/httpd.git
synced 2026-01-06 09:01:14 +03:00
e34ebac504
git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@94547 13f79535-47bb-0310-9956-ffa450edef68
192 lines
8.9 KiB
Plaintext
192 lines
8.9 KiB
Plaintext
_ _
|
|
_ __ ___ ___ __| | ___ ___| |
|
|
| '_ ` _ \ / _ \ / _` | / __/ __| |
|
|
| | | | | | (_) | (_| | \__ \__ \ | ``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 <IfDefine> 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
|