From e3fbbd9e2da558fda3e13b8b53d54c301e93704c Mon Sep 17 00:00:00 2001 From: Bill Stoddard Date: Mon, 5 Nov 2001 17:42:41 +0000 Subject: [PATCH] Begin adding the SSL doc to the httpd-2.0 tree. Start with the html files. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@91752 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/ssl/index.html | 223 +++ docs/manual/ssl/index.html.en | 223 +++ docs/manual/ssl/ssl_compat.html | 551 ++++++ docs/manual/ssl/ssl_faq.html | 1643 ++++++++++++++++++ docs/manual/ssl/ssl_glossary.html | 413 +++++ docs/manual/ssl/ssl_howto.html | 929 ++++++++++ docs/manual/ssl/ssl_intro.html | 919 ++++++++++ docs/manual/ssl/ssl_overview.html | 476 ++++++ docs/manual/ssl/ssl_reference.html | 2539 ++++++++++++++++++++++++++++ 9 files changed, 7916 insertions(+) create mode 100644 docs/manual/ssl/index.html create mode 100644 docs/manual/ssl/index.html.en create mode 100644 docs/manual/ssl/ssl_compat.html create mode 100644 docs/manual/ssl/ssl_faq.html create mode 100644 docs/manual/ssl/ssl_glossary.html create mode 100644 docs/manual/ssl/ssl_howto.html create mode 100644 docs/manual/ssl/ssl_intro.html create mode 100644 docs/manual/ssl/ssl_overview.html create mode 100644 docs/manual/ssl/ssl_reference.html diff --git a/docs/manual/ssl/index.html b/docs/manual/ssl/index.html new file mode 100644 index 0000000000..fb39a4440b --- /dev/null +++ b/docs/manual/ssl/index.html @@ -0,0 +1,223 @@ + + +mod_ssl: Title Page + + + + + + + +
+ + + + +
+
+ + + + + + + + + + +
+ + + + + + + +
+ User Manual +
+ mod_ssl version 2.8    +
+
+
+ mod_ssl - The Apache Interface to OpenSSL +
+ + + + + + + +
+ Ralf S. Engelschall
+ rse@engelschall.com
+ www.engelschall.com
+ 		+      + +next page
Overview + 		+ +
+
+
+
+ + diff --git a/docs/manual/ssl/index.html.en b/docs/manual/ssl/index.html.en new file mode 100644 index 0000000000..fb39a4440b --- /dev/null +++ b/docs/manual/ssl/index.html.en @@ -0,0 +1,223 @@ + + +mod_ssl: Title Page + + + + + + + +
+ + + + +
+
+ + + + + + + + + + +
+ + + + + + + +
+ User Manual +
+ mod_ssl version 2.8    +
+
+
+ mod_ssl - The Apache Interface to OpenSSL +
+ + + + + + + +
+ Ralf S. Engelschall
+ rse@engelschall.com
+ www.engelschall.com
+ 		+      + +next page
Overview + 		+ +
+
+
+
+ + diff --git a/docs/manual/ssl/ssl_compat.html b/docs/manual/ssl/ssl_compat.html new file mode 100644 index 0000000000..391c0668c6 --- /dev/null +++ b/docs/manual/ssl/ssl_compat.html @@ -0,0 +1,551 @@ + + +mod_ssl: Compatibility + + + + + + + + + + +
+ + + + +
+
+ + + + + + + + + + + + + +
+ + + + + +
+ mod_ssl + + Chapter 4 +
+
+ + + + + +
+previous page
Reference + 		+next page
HowTo +
+
+
+ Compatibility +
+
+ + + + + + + +
+ +All PCs are compatible. But some of +them are more compatible than others. + +
+ +Unknown + +
+
+

+ + + + + + +
+H +ere we talk about backward compatibility to other SSL solutions. As you +perhaps know, mod_ssl is not the only existing SSL solution for Apache. +Actually there are four additional major products available on the market: Ben +Laurie's freely available Apache-SSL +(from where mod_ssl were originally derived in 1998), RedHat's commercial Secure Web +Server (which is based on mod_ssl), Covalent's commercial Raven SSL Module (also based on mod_ssl) +and finally C2Net's commercial product Stronghold (based on a +different evolution branch named Sioux up to Stronghold 2.x and based on +mod_ssl since Stronghold 3.x). + +   + +
+ + + + + + + +
+ +Table Of Contents + +
+ +        Configuration Directives
+        Environment Variables
+        Custom Log Functions
+ +
+
+
+

+The idea in mod_ssl is mainly the following: because mod_ssl provides mostly a +superset of the functionality of all other solutions we can easily provide +backward compatibility for most of the cases. Actually there are three +compatibility areas we currently address: configuration directives, +environment variables and custom log functions. +

Configuration Directives

+For backward compatibility to the configuration directives of other SSL +solutions we do an on-the-fly mapping: directives which have a direct +counterpart in mod_ssl are mapped silently while other directives lead to a +warning message in the logfiles. The currently implemented directive mapping +is listed in Table 1. Currently full backward +compatibilty is provided only for Apache-SSL 1.x and mod_ssl 2.0.x. +Compatibility to Sioux 1.x and Stronghold 2.x is only partial because of +special functionality in these interfaces which mod_ssl (still) doesn't +provide. +

+

+ + + +
Table 1: Configuration Directive Mapping
+ + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Old Directivemod_ssl DirectiveComment
Apache-SSL 1.x & mod_ssl 2.0.x compatibility:
SSLEnableSSLEngine oncompactified
SSLDisableSSLEngine offcompactified
SSLLogFile fileSSLLog filecompactified
SSLRequiredCiphers specSSLCipherSuite specrenamed
SSLRequireCipher c1 ...SSLRequire %{SSL_CIPHER} in {"c1", ...}generalized
SSLBanCipher c1 ...SSLRequire not (%{SSL_CIPHER} in {"c1", ...})generalized
SSLFakeBasicAuthSSLOptions +FakeBasicAuthmerged
SSLCacheServerPath dir-functionality removed
SSLCacheServerPort integer-functionality removed
Apache-SSL 1.x compatibility:
SSLExportClientCertificatesSSLOptions +ExportCertDatamerged
SSLCacheServerRunDir dir-functionality not supported
Sioux 1.x compatibility:
SSL_CertFile fileSSLCertificateFile filerenamed
SSL_KeyFile fileSSLCertificateKeyFile filerenamed
SSL_CipherSuite argSSLCipherSuite argrenamed
SSL_X509VerifyDir argSSLCACertificatePath argrenamed
SSL_Log fileSSLLogFile filerenamed
SSL_Connect flagSSLEngine flagrenamed
SSL_ClientAuth argSSLVerifyClient argrenamed
SSL_X509VerifyDepth argSSLVerifyDepth argrenamed
SSL_FetchKeyPhraseFrom arg-not directly mappable; use SSLPassPhraseDialog
SSL_SessionDir dir-not directly mappable; use SSLSessionCache
SSL_Require expr-not directly mappable; use SSLRequire
SSL_CertFileType arg-functionality not supported
SSL_KeyFileType arg-functionality not supported
SSL_X509VerifyPolicy arg-functionality not supported
SSL_LogX509Attributes arg-functionality not supported
Stronghold 2.x compatibility:
StrongholdAccelerator dir-functionality not supported
StrongholdKey dir-functionality not supported
StrongholdLicenseFile dir-functionality not supported
SSLFlag flagSSLEngine flagrenamed
SSLSessionLockFile fileSSLMutex filerenamed
SSLCipherList specSSLCipherSuite specrenamed
RequireSSLSSLRequireSSLrenamed
SSLErrorFile file-functionality not supported
SSLRoot dir-functionality not supported
SSL_CertificateLogDir dir-functionality not supported
AuthCertDir dir-functionality not supported
SSL_Group name-functionality not supported
SSLProxyMachineCertPath dir-functionality not supported
SSLProxyMachineCertFile file-functionality not supported
SSLProxyCACertificatePath dir-functionality not supported
SSLProxyCACertificateFile file-functionality not supported
SSLProxyVerifyDepth number-functionality not supported
SSLProxyCipherList spec-functionality not supported
+
+
+
+

+
+

Environment Variables

+When you use ``SSLOptions +CompatEnvVars'' additional environment +variables are generated. They all correspond to existing official mod_ssl +variables. The currently implemented variable derivation is listed in Table 2. +

+

+ + + +
Table 2: Environment Variable Derivation
+ + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Old Variablemod_ssl VariableComment
SSL_PROTOCOL_VERSIONSSL_PROTOCOLrenamed
SSLEAY_VERSIONSSL_VERSION_LIBRARYrenamed
HTTPS_SECRETKEYSIZESSL_CIPHER_USEKEYSIZErenamed
HTTPS_KEYSIZESSL_CIPHER_ALGKEYSIZErenamed
HTTPS_CIPHERSSL_CIPHERrenamed
HTTPS_EXPORTSSL_CIPHER_EXPORTrenamed
SSL_SERVER_KEY_SIZESSL_CIPHER_ALGKEYSIZErenamed
SSL_SERVER_CERTIFICATESSL_SERVER_CERTrenamed
SSL_SERVER_CERT_STARTSSL_SERVER_V_STARTrenamed
SSL_SERVER_CERT_ENDSSL_SERVER_V_ENDrenamed
SSL_SERVER_CERT_SERIALSSL_SERVER_M_SERIALrenamed
SSL_SERVER_SIGNATURE_ALGORITHMSSL_SERVER_A_SIGrenamed
SSL_SERVER_DNSSL_SERVER_S_DNrenamed
SSL_SERVER_CNSSL_SERVER_S_DN_CNrenamed
SSL_SERVER_EMAILSSL_SERVER_S_DN_Emailrenamed
SSL_SERVER_OSSL_SERVER_S_DN_Orenamed
SSL_SERVER_OUSSL_SERVER_S_DN_OUrenamed
SSL_SERVER_CSSL_SERVER_S_DN_Crenamed
SSL_SERVER_SPSSL_SERVER_S_DN_SPrenamed
SSL_SERVER_LSSL_SERVER_S_DN_Lrenamed
SSL_SERVER_IDNSSL_SERVER_I_DNrenamed
SSL_SERVER_ICNSSL_SERVER_I_DN_CNrenamed
SSL_SERVER_IEMAILSSL_SERVER_I_DN_Emailrenamed
SSL_SERVER_IOSSL_SERVER_I_DN_Orenamed
SSL_SERVER_IOUSSL_SERVER_I_DN_OUrenamed
SSL_SERVER_ICSSL_SERVER_I_DN_Crenamed
SSL_SERVER_ISPSSL_SERVER_I_DN_SPrenamed
SSL_SERVER_ILSSL_SERVER_I_DN_Lrenamed
SSL_CLIENT_CERTIFICATESSL_CLIENT_CERTrenamed
SSL_CLIENT_CERT_STARTSSL_CLIENT_V_STARTrenamed
SSL_CLIENT_CERT_ENDSSL_CLIENT_V_ENDrenamed
SSL_CLIENT_CERT_SERIALSSL_CLIENT_M_SERIALrenamed
SSL_CLIENT_SIGNATURE_ALGORITHMSSL_CLIENT_A_SIGrenamed
SSL_CLIENT_DNSSL_CLIENT_S_DNrenamed
SSL_CLIENT_CNSSL_CLIENT_S_DN_CNrenamed
SSL_CLIENT_EMAILSSL_CLIENT_S_DN_Emailrenamed
SSL_CLIENT_OSSL_CLIENT_S_DN_Orenamed
SSL_CLIENT_OUSSL_CLIENT_S_DN_OUrenamed
SSL_CLIENT_CSSL_CLIENT_S_DN_Crenamed
SSL_CLIENT_SPSSL_CLIENT_S_DN_SPrenamed
SSL_CLIENT_LSSL_CLIENT_S_DN_Lrenamed
SSL_CLIENT_IDNSSL_CLIENT_I_DNrenamed
SSL_CLIENT_ICNSSL_CLIENT_I_DN_CNrenamed
SSL_CLIENT_IEMAILSSL_CLIENT_I_DN_Emailrenamed
SSL_CLIENT_IOSSL_CLIENT_I_DN_Orenamed
SSL_CLIENT_IOUSSL_CLIENT_I_DN_OUrenamed
SSL_CLIENT_ICSSL_CLIENT_I_DN_Crenamed
SSL_CLIENT_ISPSSL_CLIENT_I_DN_SPrenamed
SSL_CLIENT_ILSSL_CLIENT_I_DN_Lrenamed
SSL_EXPORTSSL_CIPHER_EXPORTrenamed
SSL_KEYSIZESSL_CIPHER_ALGKEYSIZErenamed
SSL_SECKEYSIZESSL_CIPHER_USEKEYSIZErenamed
SSL_SSLEAY_VERSIONSSL_VERSION_LIBRARYrenamed
SSL_STRONG_CRYPTO-Not supported by mod_ssl
SSL_SERVER_KEY_EXP-Not supported by mod_ssl
SSL_SERVER_KEY_ALGORITHM-Not supported by mod_ssl
SSL_SERVER_KEY_SIZE-Not supported by mod_ssl
SSL_SERVER_SESSIONDIR-Not supported by mod_ssl
SSL_SERVER_CERTIFICATELOGDIR-Not supported by mod_ssl
SSL_SERVER_CERTFILE-Not supported by mod_ssl
SSL_SERVER_KEYFILE-Not supported by mod_ssl
SSL_SERVER_KEYFILETYPE-Not supported by mod_ssl
SSL_CLIENT_KEY_EXP-Not supported by mod_ssl
SSL_CLIENT_KEY_ALGORITHM-Not supported by mod_ssl
SSL_CLIENT_KEY_SIZE-Not supported by mod_ssl
+
+
+
+

+
+

Custom Log Functions

+When mod_ssl is built into Apache or at least loaded (under DSO situation) +additional functions exist for the Custom Log Format of mod_log_config as documented in the Reference +Chapter. Beside the ``%{varname}x'' +eXtension format function which can be used to expand any variables provided +by any module, an additional Cryptography +``%{name}c'' cryptography format function +exists for backward compatibility. The currently implemented function calls +are listed in Table 3. +

+

+ + + +
Table 3: Custom Log Cryptography Function
+ + +
+ + + + + + + + + + + +
Function CallDescription
%...{version}c SSL protocol version
%...{cipher}c SSL cipher
%...{subjectdn}c Client Certificate Subject Distinguished Name
%...{issuerdn}c Client Certificate Issuer Distinguished Name
%...{errcode}c Certificate Verification Error (numerical)
%...{errstr}c Certificate Verification Error (string)
+
+
+
+

+
+ + + + + + + + + + +
+ + + + + +
+previous page
Reference + 		+next page
HowTo +
+
+ + + + +
+ mod_ssl 2.8, User Manual
+ The Apache Interface to OpenSSL + + 		+ Copyright © 1998-2001 + Ralf S. Engelschall
+ All Rights Reserved
+ +
+
+

+
+ + diff --git a/docs/manual/ssl/ssl_faq.html b/docs/manual/ssl/ssl_faq.html new file mode 100644 index 0000000000..e3d3aa8f26 --- /dev/null +++ b/docs/manual/ssl/ssl_faq.html @@ -0,0 +1,1643 @@ + + +mod_ssl: F.A.Q. + + + + + + + + + + +
+ + + + +
+
+ + + + + + + + + + + + + +
+ + + + + +
+ mod_ssl + + Chapter 6 +
+
+ + + + + +
+previous page
HowTo + 		+next page
Glossary +
+
+
+ F.A.Q. +
+
+ + + + + + + +
+ +``The wise man doesn't give the right answers, +he poses the right questions.'' + +
+ +Claude Levi-Strauss + +
+
+

+ + + + + + +
+T +his chapter is a collection of frequently asked questions (FAQ) and +corresponding answers following the popular USENET tradition. Most of these +questions occured on the Newsgroup +comp.infosystems.www.servers.unix or the mod_ssl Support +Mailing List +modssl-users@modssl.org. They are collected at this place +to avoid answering the same questions over and over. +

+Please read this chapter at least once when installing mod_ssl or at least +search for your problem here before submitting a problem report to the +author. +

 +   + +
+ + + + + + + +
+ +Table Of Contents + +
+ +        About the module
+                What is the history of mod_ssl?
+                Apache-SSL vs. mod_ssl: differences?
+                mod_ssl vs. commercial alternatives?
+                mod_ssl/Apache versions?
+                mod_ssl and Year 2000?
+                mod_ssl and Wassenaar Arrangement?
+        About Installation
+                Core dumps for HTTPS requests?
+                Core dumps for Apache+mod_ssl+PHP3?
+                Undefined symbols on startup?
+                Permission problem on SSLMutex
+                Shared memory and process size?
+                Shared memory and pathname?
+                PRNG and not enough entropy?
+        About Configuration
+                HTTP and HTTPS with a single server?
+                Where is the HTTPS port?
+                How to test HTTPS manually?
+                Why does my connection hang?
+                Why do I get connection refused?
+                Why are the SSL_XXX variables missing?
+                How to switch with relative hyperlinks?
+        About Certificates
+                What are Keys, CSRs and Certs?
+                Difference on startup?
+                How to create a dummy cert?
+                How to create a real cert?
+                How to create my own CA?
+                How to change a pass phrase?
+                How to remove a pass phrase?
+                How to verify a key/cert pair?
+                Bad Certificate Error?
+                Why does a 2048-bit key not work?
+                Why is client auth broken?
+                How to convert from PEM to DER?
+                Verisign and the magic getca program?
+                Global IDs or SGC?
+                Global IDs and Cert Chain?
+        About SSL Protocol
+                Random SSL errors under heavy load?
+                Why has the server a higher load?
+                Why are connections horribly slow?
+                Which ciphers are supported?
+                How to use Anonymous-DH ciphers
+                Why do I get 'no shared ciphers'?
+                HTTPS and name-based vhosts
+                The lock icon in Netscape locks very late
+                Why do I get I/O errors with MSIE clients?
+                Why do I get I/O errors with NS clients?
+        About Support
+                Resources in case of problems?
+                Support in case of problems?
+                How to write a problem report?
+                I got a core dump, can you help me?
+                How to get a backtrace?
+ +
+
+
+

About the module

+
    +

    +

  • + + +What is the history of mod_ssl? +   + [L] +

    + The mod_ssl v1 package was initially created in April 1998 by Ralf S. Engelschall via porting Ben Laurie's Apache-SSL 1.17 source patches for + Apache 1.2.6 to Apache 1.3b6. Because of conflicts with Ben + Laurie's development cycle it then was re-assembled from scratch for + Apache 1.3.0 by merging the old mod_ssl 1.x with the newer Apache-SSL + 1.18. From this point on mod_ssl lived its own life as mod_ssl v2. The + first publically released version was mod_ssl 2.0.0 from August 10th, + 1998. As of this writing (August 1999) the current mod_ssl version is 2.4.0. +

    + After one year of very active development with over 1000 working hours and + over 40 releases mod_ssl reached its current state. The result is an + already very clean source base implementing a very rich functionality. + The code size increased by a factor of 4 to currently a total of over + 10.000 lines of ANSI C consisting of approx. 70% code and 30% code + documentation. From the original Apache-SSL code currently approx. 5% is + remaining only. +

    +

  • + + +What are the functional differences between mod_ssl and Apache-SSL, from where +it is originally derived? +   + [L] +

    + This neither can be answered in short (there were too many code changes) + nor can be answered at all by the author (there would immediately be flame + wars with no reasonable results at the end). But as you easily can guess + from the 5% of remaining Apache-SSL code, a lot of differences exists, + although user-visible backward compatibility exists for most things. +

    + When you really want a detailed comparison you have to read the entries in + the large CHANGES file that is in the mod_ssl + distribution. Usually this is much too hard-core. So I recommend you to + either believe in the opinion and recommendations of other users (the + simplest approach) or do a comparison yourself (the most reasonable + approach). For the latter, grab distributions of mod_ssl (from http://www.modssl.org) and Apache-SSL + (from http://www.apache-ssl.org), + install both packages, read their documentation and try them out yourself. + Then choose the one which pleases you most. +

    + A few final hints to help direct your comparison: quality of documentation + ("can you easily find answers and are they sufficient?"), quality of + source code ("is the source code reviewable so you can make sure there + aren't any trapdoors or inherent security risks because of bad programming + style?"), easy and clean installation ("can the SSL functionality easily + added to an Apache source tree without manual editing or patching?"), + clean integration into Apache ("is the SSL functionality encapsulated and + cleanly separated from the remaining Apache functionality?"), support for + Dynamic Shared Object (DSO) facility ("can the SSL functionality built as + a separate DSO for maximum flexibility?"), Win32 port ("is the SSL + functionality available also under the Win32 platform?"), amount and + quality of functionality ("is the provided SSL functionality and control + possibilities sufficient for your situation?"), quality of problem tracing + ("is it possible for you to easily trace down the problems via logfiles, + etc?"), etc. pp. +

    +

  • + + +What are the major differences between mod_ssl and +the commercial alternatives like Raven or Stronghold? +   + [L] +

    + In the past (until September 20th, 2000) the major difference was + the RSA license which one received (very cheaply in contrast to + a direct licensing from RSA DSI) with the commercial Apache SSL + products. On the other hand, one needed this license only in the US, + of course. So for non-US citizens this point was useless. But now + even for US citizens the situations changed because the RSA patent + expired on September 20th, 2000 and RSA DSI also placed the RSA + algorithm explicitly into the public domain. +

    + Second, there is the point that one has guaranteed support from + the commercial vendors. On the other hand, if you monitored the + Open Source quality of mod_ssl and the support activities + found on + modssl-users@modssl.org, you could ask yourself + whether you are really convinced that you can get better support + from a commercial vendor. +

    + Third, people often think they would receive perhaps at least a + better technical SSL solution than mod_ssl from the commercial + vendors. But this is not really true, because all commercial + alternatives (Raven 1.4.x, Stronghold 3.x, RedHat SWS 2.x, etc.) + are actually based on mod_ssl and OpenSSL. The reason for + this common misunderstanding is mainly because some vendors make no + attempt to make it reasonably clear that their product is actually + mod_ssl based. So, do not think, just because the commercial + alternatives are usually more expensive, that you are also receiving + an alternative technical SSL solution. This is usually not + the case. Actually the vendor versions of Apache, mod_ssl and OpenSSL + often stay behind the latest free versions and perhaps this way still do not + include important bug and security fixes. On the other hand, + it sometimes occurs that a vendor version includes useful changes + which are not available through the official freely available + packages. But most vendors play fair and contribute back those + changes to the free software world, of course. +

    + So, in short: There are lots of commercial versions of the popular + Apache+mod_ssl+OpenSSL server combination available. Every user + should decide carefully whether they really need to buy a commercial + version or whether it would not be sufficient to directly use the + free and official versions of the Apache, mod_ssl and OpenSSL + packages. +

    +

  • + + +How do I know which mod_ssl version is for which Apache version? +   + [L] +

    + That's trivial: mod_ssl uses version strings of the syntax + <mod_ssl-version>-<apache-version>, for + instance 2.4.0-1.3.9. This directly indicates that it's + mod_ssl version 2.4.0 for Apache version 1.3.9. And this also means you + only can apply this mod_ssl version to exactly this Apache + version (unless you use the --force option to mod_ssl's + configure command ;-). +

    +

  • + + +Is mod_ssl Year 2000 compliant? +   + [L] +

    + Yes, mod_ssl is Year 2000 compliant. +

    + Because first mod_ssl internally never stores years as two digits. + Instead it always uses the ANSI C & POSIX numerical data type + time_t type, which on almost all Unix platforms at the moment + is a signed long (usually 32-bits) representing seconds since + epoch of January 1st, 1970, 00:00 UTC. This signed value overflows in + early January 2038 and not in the year 2000. Second, date and time + presentations (for instance the variable ``%{TIME_YEAR}'') + are done with full year value instead of abbreviating to two digits. +

    + Additionally according to a Year 2000 + statement from the Apache Group, the Apache webserver is Year 2000 + compliant, too. But whether OpenSSL or the underlaying Operating System + (either a Unix or Win32 platform) is Year 2000 compliant is a different + question which cannot be answered here. +

    +

  • + + +What about mod_ssl and the Wassenaar Arrangement? +   + [L] +

    + First, let us explain what Wassenaar and it's Arrangement on + Export Controls for Conventional Arms and Dual-Use Goods and + Technologies is: This is a international regime, established 1995, to + control trade in conventional arms and dual-use goods and technology. It + replaced the previous CoCom regime. 33 countries are signatories: + Argentina, Australia, Austria, Belgium, Bulgaria, Canada, Czech Republic, + Denmark, Finland, France, Germany, Greece, Hungary, Ireland, Italy, Japan, + Luxembourg, Netherlands, New Zealand, Norway, Poland, Portugal, Republic + of Korea, Romania, Russian Federation, Slovak Republic, Spain, Sweden, + Switzerland, Turkey, Ukraine, United Kingdom and United States. For more + details look at http://www.wassenaar.org/. +

    + In short: The aim of the Wassenaar Arrangement is to prevent the build up + of military capabilities that threaten regional and international security + and stability. The Wassenaar Arrangement controls the export of + cryptography as a dual-use good, i.e., one that has both military and + civilian applications. However, the Wassenaar Arrangement also provides an + exemption from export controls for mass-market software and free software. +

    + In the current Wassenaar ``List of Dual Use Goods and Technologies And + Munitions'', under ``GENERAL SOFTWARE NOTE'' (GSN) it says + ``The Lists do not control "software" which is either: 1. [...] 2. "in + the public domain".'' And under ``DEFINITIONS OF TERMS USED IN + THESE LISTS'' one can find the definition: ``"In the public + domain": This means "technology" or "software" which has been made + available without restrictions upon its further dissemination. N.B. + Copyright restrictions do not remove "technology" or "software" from being + "in the public domain".'' +

    + So, both mod_ssl and OpenSSL are ``in the public domain'' for the purposes + of the Wassenaar Agreement and its ``List of Dual Use Goods and + Technologies And Munitions List''. +

    + Additionally the Wassenaar Agreement itself has no direct consequence for + exporting cryptography software. What is actually allowed or forbidden to + be exported from the countries has still to be defined in the local laws + of each country. And at least according to official press releases from + the German BMWi (see here) and the + Switzerland Bawi (see here) there + will be no forthcoming export restriction for free cryptography software + for their countries. Remember that mod_ssl is created in Germany and + distributed from Switzerland. +

    + So, mod_ssl and OpenSSL are not affected by the Wassenaar Agreement. +

+

+
+

About Installation

+
    +

    +

  • + + +When I access my website the first time via HTTPS I get a core dump? +   + [L] +

    + There can be a lot of reasons why a core dump can occur, of course. + Ranging from buggy third-party modules, over buggy vendor libraries up to + a buggy mod_ssl version. But the above situation is often caused by old or + broken vendor DBM libraries. To solve it either build mod_ssl with the + built-in SDBM library (specify --enable-rule=SSL_SDBM at the + APACI command line) or switch from ``SSLSessionCache dbm:'' to the + newer ``SSLSessionCache shm:'' variant (after you have rebuilt + Apache with MM, of course). +

    +

  • + + +My Apache dumps core when I add both mod_ssl and PHP3? +   + [L] +

    + Make sure you add mod_ssl to the Apache source tree first and then do a + fresh configuration and installation of PHP3. For SSL support EAPI patches + are required which have to change internal Apache structures. PHP3 needs + to know about these in order to work correctly. Always make sure that + -DEAPI is contained in the compiler flags when PHP3 is build. +

    +

  • + + +When I startup Apache I get errors about undefined symbols like ap_global_ctx? +   + [L] +

    + This actually means you installed mod_ssl as a DSO, but without rebuilding + Apache with EAPI. Because EAPI is a requirement for mod_ssl, you need an + extra patched Apache (containing the EAPI patches) and you have to build + this Apache with EAPI enabled (explicitly specify + --enable-rule=EAPI at the APACI command line). +

    +

  • + + +When I startup Apache I get permission errors related to SSLMutex? +   + [L] +

    + When you receive entries like ``mod_ssl: Child could not open + SSLMutex lockfile /opt/apache/logs/ssl_mutex.18332 (System error follows) + [...] System: Permission denied (errno: 13)'' this is usually + caused by to restrictive permissions on the parent directories. + Make sure that all parent directories (here /opt, + /opt/apache and /opt/apache/logs) have the x-bit + set at least for the UID under which Apache's children are running (see + the User directive of Apache). +

    +

  • + + +When I use the MM library and the shared memory cache each process grows +1.5MB according to `top' although I specified 512000 as the cache size? +   + [L] +

    + The additional 1MB are caused by the global shared memory pool EAPI + allocates for all modules and which is not used by mod_ssl for + various reasons. So the actually allocated shared memory is always + 1MB more than what you specify on SSLSessionCache. + But don't be confused by the display of `top': although is + indicates that each process grow, this is not reality, of + course. Instead the additional memory consumption is shared by + all processes, i.e. the 1.5MB are allocated only once per Apache + instance and not once per Apache server process. +

    +

  • + + +Apache creates files in a directory declared by the internal +EAPI_MM_CORE_PATH define. Is there a way to override the path using a +configuration directive? +   + [L] +

    + No, there is not configuration directive, because for technical + bootstrapping reasons, a directive not possible at all. Instead + use ``CFLAGS='-DEAPI_MM_CORE_PATH="/path/to/wherever/"' + ./configure ...'' when building Apache or use option + -d when starting httpd. +

    +

  • + + +When I fire up the server, mod_ssl stops with the error +"Failed to generate temporary 512 bit RSA private key", why? +And a "PRNG not seeded" error occurs if I try "make certificate". +   + [L] +

    + Cryptographic software needs a source of unpredictable data + to work correctly. Many open source operating systems provide + a "randomness device" that serves this purpose (usually named + /dev/random). On other systems, applications have to + seed the OpenSSL Pseudo Random Number Generator (PRNG) manually with + appropriate data before generating keys or performing public key + encryption. As of version 0.9.5, the OpenSSL functions that need + randomness report an error if the PRNG has not been seeded with + at least 128 bits of randomness. So mod_ssl has to provide enough + entropy to the PRNG to work correctly. For this one has to use the + SSLRandomSeed directives (to solve the run-time problem) + and create a $HOME/.rnd file to make sure enough + entropy is available also for the "make certificate" + step (in case the "make certificate" procedure is not + able to gather enough entropy theirself by searching for system + files). +

+

+
+

About Configuration

+
    +

    +

  • + + +Is it possible to provide HTTP and HTTPS with a single server? +   + [L] +

    + Yes, HTTP and HTTPS use different server ports, so there is no direct + conflict between them. Either run two separate server instances (one binds + to port 80, the other to port 443) or even use Apache's elegant virtual + hosting facility where you can easily create two virtual servers which + Apache dispatches: one responding to port 80 and speaking HTTP and one + responding to port 443 speaking HTTPS. +

    +

  • + + +I know that HTTP is on port 80, but where is HTTPS? +   + [L] +

    + You can run HTTPS on any port, but the standards specify port 443, which + is where any HTTPS compliant browser will look by default. You can force + your browser to look on a different port by specifying it in the URL like + this (for port 666): https://secure.server.dom:666/ +

    +

  • + + +How can I speak HTTPS manually for testing purposes? +   + [L] +

    + While you usually just use +

    + $ telnet localhost 80
    + GET / HTTP/1.0 +

    + for simple testing the HTTP protocol of Apache, it's not such easy for + HTTPS because of the SSL protocol between TCP and HTTP. But with the + help of OpenSSL's s_client command you can do a similar + check even for HTTPS: +

    + $ openssl s_client -connect localhost:443 -state -debug
    + GET / HTTP/1.0 +

    + Before the actual HTTP response you receive detailed information about the + SSL handshake. For a more general command line client which directly + understands both the HTTP and HTTPS scheme, can perform GET and POST + methods, can use a proxy, supports byte ranges, etc. you should have a + look at nifty cURL + tool. With it you can directly check if your Apache is running fine on + Port 80 and 443 as following: +

    + $ curl http://localhost/
    + $ curl https://localhost/
    +

    +

  • + + +Why does the connection hang when I connect to my SSL-aware Apache server? +   + [L] +

    + Because you connected with HTTP to the HTTPS port, i.e. you used an URL of + the form ``http://'' instead of ``https://''. + This also happens the other way round when you connect via HTTPS to a HTTP + port, i.e. when you try to use ``https://'' on a server that + doesn't support SSL (on this port). Make sure you are connecting to a + virtual server that supports SSL, which is probably the IP associated with + your hostname, not localhost (127.0.0.1). +

    +

  • + + +Why do I get ``Connection Refused'' messages when trying to access my freshly +installed Apache+mod_ssl server via HTTPS? +   + [L] +

    + There can be various reasons. Some of the common mistakes is that people + start Apache with just ``apachectl start'' (or + ``httpd'') instead of ``apachectl startssl'' (or + ``httpd -DSSL''. Or you're configuration is not correct. At + least make sure that your ``Listen'' directives match your + ``<VirtualHost>'' directives. And if all fails, please do + yourself a favor and start over with the default configuration mod_ssl + provides you. +

    +

  • + + +In my CGI programs and SSI scripts the various documented +SSL_XXX variables do not exists. Why? +   + [L] +

    + Just make sure you have ``SSLOptions +StdEnvVars'' + enabled for the context of your CGI/SSI requests. +

    +

  • + + +How can I use relative hyperlinks to switch between HTTP and HTTPS? +   + [L] +

    + Usually you have to use fully-qualified hyperlinks because + you have to change the URL scheme. But with the help of some URL + manipulations through mod_rewrite you can achieve the same effect while + you still can use relative URLs: + 

    +    RewriteEngine on
+    RewriteRule   ^/(.*):SSL$   https://%{SERVER_NAME}/$1 [R,L]
+    RewriteRule   ^/(.*):NOSSL$ http://%{SERVER_NAME}/$1  [R,L]
+
    + This rewrite ruleset lets you use hyperlinks of the form + 
    +    <a href="document.html:SSL">
+
    +
+

+
+

About Certificates

+
    +

    +

  • + + +What are RSA Private Keys, CSRs and Certificates? +   + [L] +

    + The RSA private key file is a digital file that you can use to decrypt + messages sent to you. It has a public component which you distribute (via + your Certificate file) which allows people to encrypt those messages to + you. A Certificate Signing Request (CSR) is a digital file which contains + your public key and your name. You send the CSR to a Certifying Authority + (CA) to be converted into a real Certificate. A Certificate contains your + RSA public key, your name, the name of the CA, and is digitally signed by + your CA. Browsers that know the CA can verify the signature on that + Certificate, thereby obtaining your RSA public key. That enables them to + send messages which only you can decrypt. + See the Introduction chapter for a general + description of the SSL protocol. +

    +

  • + + +Seems like there is a difference on startup between the original Apache and an SSL-aware Apache? +   + [L] +

    + Yes, in general, starting Apache with a built-in mod_ssl is just like + starting an unencumbered Apache, except for the fact that when you have a + pass phrase on your SSL private key file. Then a startup dialog pops up + asking you to enter the pass phrase. +

    + To type in the pass phrase manually when starting the server can be + problematic, for instance when starting the server from the system boot + scripts. As an alternative to this situation you can follow the steps + below under ``How can I get rid of the pass-phrase dialog at Apache + startup time?''. +

    +

  • + + +How can I create a dummy SSL server Certificate for testing purposes? +   + [L] +

    + A Certificate does not have to be signed by a public CA. You can use your + private key to sign the Certificate which contains your public key. You + can install this Certificate into your server, and people using Netscape + Navigator (not MSIE) will be able to connect after clicking OK to a + warning dialogue. You can get MSIE to work, and your customers can + eliminate the dialogue, by installing that Certificate manually into their + browsers. +

    + Just use the ``make certificate'' command at the top-level + directory of the Apache source tree right before installing Apache via + ``make install''. This creates a self-signed SSL Certificate + which expires after 30 days and isn't encrypted (which means you don't + need to enter a pass-phrase at Apache startup time). +

    + BUT REMEMBER: YOU REALLY HAVE TO CREATE A REAL CERTIFICATE FOR THE LONG + RUN! HOW THIS IS DONE IS DESCRIBED IN THE NEXT ANSWER. +

    +

  • + + +Ok, I've got my server installed and want to create a real SSL +server Certificate for it. How do I do it? +   + [L] +

    + Here is a step-by-step description: +

    +

      +
    1. Make sure OpenSSL is really installed and in your PATH. + But some commands even work ok when you just run the + ``openssl'' program from within the OpenSSL source tree as + ``./apps/openssl''. +

      +

    2. Create a RSA private key for your Apache server + (will be Triple-DES encrypted and PEM formatted): +

      + $ openssl genrsa -des3 -out server.key 1024 +

      + Please backup this server.key file and remember the + pass-phrase you had to enter at a secure location. + You can see the details of this RSA private key via the command: +

      + $ openssl rsa -noout -text -in server.key +

      + And you could create a decrypted PEM version (not recommended) + of this RSA private key via: +

      + $ openssl rsa -in server.key -out server.key.unsecure +

      +

    3. Create a Certificate Signing Request (CSR) with the server RSA private + key (output will be PEM formatted): +

      + $ openssl req -new -key server.key -out server.csr +

      + Make sure you enter the FQDN ("Fully Qualified Domain Name") of the + server when OpenSSL prompts you for the "CommonName", i.e. when you + generate a CSR for a website which will be later accessed via + https://www.foo.dom/, enter "www.foo.dom" here. + You can see the details of this CSR via the command +

      + $ openssl req -noout -text -in server.csr +

      +

    4. You now have to send this Certificate Signing Request (CSR) to + a Certifying Authority (CA) for signing. The result is then a real + Certificate which can be used for Apache. Here you have two options: + First you can let the CSR sign by a commercial CA like Verisign or + Thawte. Then you usually have to post the CSR into a web form, pay for + the signing and await the signed Certificate you then can store into a + server.crt file. For more information about commercial CAs have a look + at the following locations: +

      +

      +

      + Second you can use your own CA and now have to sign the CSR yourself by + this CA. Read the next answer in this FAQ on how to sign a CSR with + your CA yourself. + You can see the details of the received Certificate via the command: +

      + $ openssl x509 -noout -text -in server.crt +

      +

    5. Now you have two files: server.key and + server.crt. These now can be used as following inside your + Apache's httpd.conf file: + 
      +       SSLCertificateFile    /path/to/this/server.crt
+       SSLCertificateKeyFile /path/to/this/server.key
+
      + The server.csr file is no longer needed. +
    +

    +

  • + + +How can I create and use my own Certificate Authority (CA)? +   + [L] +

    + The short answer is to use the CA.sh or CA.pl + script provided by OpenSSL. The long and manual answer is this: +

    +

      +
    1. Create a RSA private key for your CA + (will be Triple-DES encrypted and PEM formatted): +

      + $ openssl genrsa -des3 -out ca.key 1024 +

      + Please backup this ca.key file and remember the + pass-phrase you currently entered at a secure location. + You can see the details of this RSA private key via the command +

      + $ openssl rsa -noout -text -in ca.key +

      + And you can create a decrypted PEM version (not recommended) of this + private key via: +

      + $ openssl rsa -in ca.key -out ca.key.unsecure +

      +

    2. Create a self-signed CA Certificate (X509 structure) + with the RSA key of the CA (output will be PEM formatted): +

      + $ openssl req -new -x509 -days 365 -key ca.key -out ca.crt +

      + You can see the details of this Certificate via the command: +

      + $ openssl x509 -noout -text -in ca.crt +

      +

    3. Prepare a script for signing which is needed because + the ``openssl ca'' command has some strange requirements + and the default OpenSSL config doesn't allow one easily to use + ``openssl ca'' directly. So a script named + sign.sh is distributed with the mod_ssl distribution + (subdir pkg.contrib/). Use this script for signing. +

      +

    4. Now you can use this CA to sign server CSR's in order to create real + SSL Certificates for use inside an Apache webserver (assuming + you already have a server.csr at hand): +

      + $ ./sign.sh server.csr +

      + This signs the server CSR and results in a server.crt file. +

    +

    +

  • + + +How can I change the pass-phrase on my private key file? +   + [L] +

    + You simply have to read it with the old pass-phrase and write it again + by specifying the new pass-phrase. You can accomplish this with the following + commands: +

    + $ openssl rsa -des3 -in server.key -out server.key.new
    + $ mv server.key.new server.key
    +

    + Here you're asked two times for a PEM pass-phrase. At the first + prompt enter the old pass-phrase and at the second prompt + enter the new pass-phrase. +

    +

  • + + +How can I get rid of the pass-phrase dialog at Apache startup time? +   + [L] +

    + The reason why this dialog pops up at startup and every re-start + is that the RSA private key inside your server.key file is stored in + encrypted format for security reasons. The pass-phrase is needed to be + able to read and parse this file. When you can be sure that your server is + secure enough you perform two steps: +

    +

      +
    1. Remove the encryption from the RSA private key (while + preserving the original file): +

      + $ cp server.key server.key.org
      + $ openssl rsa -in server.key.org -out server.key +

      +

    2. Make sure the server.key file is now only readable by root: +

      + $ chmod 400 server.key +

    +

    + Now server.key will contain an unencrypted copy of the key. + If you point your server at this file it will not prompt you for a + pass-phrase. HOWEVER, if anyone gets this key they will be able to + impersonate you on the net. PLEASE make sure that the permissions on that + file are really such that only root or the web server user can read it + (preferably get your web server to start as root but run as another + server, and have the key readable only by root). +

    + As an alternative approach you can use the ``SSLPassPhraseDialog + exec:/path/to/program'' facility. But keep in mind that this is + neither more nor less secure, of course. +

    +

  • + + +How do I verify that a private key matches its Certificate? +   + [L] +

    + The private key contains a series of numbers. Two of those numbers form + the "public key", the others are part of your "private key". The "public + key" bits are also embedded in your Certificate (we get them from your + CSR). To check that the public key in your cert matches the public + portion of your private key, you need to view the cert and the key and + compare the numbers. To view the Certificate and the key run the + commands: +

    + $ openssl x509 -noout -text -in server.crt
    + $ openssl rsa -noout -text -in server.key +

    + The `modulus' and the `public exponent' portions in the key and the + Certificate must match. But since the public exponent is usually 65537 + and it's bothering comparing long modulus you can use the following + approach: +

    + $ openssl x509 -noout -modulus -in server.crt | openssl md5
    + $ openssl rsa -noout -modulus -in server.key | openssl md5 +

    + And then compare these really shorter numbers. With overwhelming + probability they will differ if the keys are different. BTW, if I want to + check to which key or certificate a particular CSR belongs you can compute +

    + $ openssl req -noout -modulus -in server.csr | openssl md5 +

    +

  • + + +What does it mean when my connections fail with an "alert bad certificate" +error? +   + [L] +

    + Usually when you see errors like ``OpenSSL: error:14094412: SSL + routines:SSL3_READ_BYTES:sslv3 alert bad certificate'' in the SSL + logfile, this means that the browser was unable to handle the server + certificate/private-key which perhaps contain a RSA-key not equal to 1024 + bits. For instance Netscape Navigator 3.x is one of those browsers. +

    +

  • + + +Why does my 2048-bit private key not work? +   + [L] +

    + The private key sizes for SSL must be either 512 or 1024 for compatibility + with certain web browsers. A keysize of 1024 bits is recommended because + keys larger than 1024 bits are incompatible with some versions of Netscape + Navigator and Microsoft Internet Explorer, and with other browsers that + use RSA's BSAFE cryptography toolkit. +

    +

  • + + +Why is client authentication broken after upgrading from +SSLeay version 0.8 to 0.9? +   + [L] +

    + The CA certificates under the path you configured with + SSLCACertificatePath are found by SSLeay through hash + symlinks. These hash values are generated by the `openssl x509 -noout + -hash' command. But the algorithm used to calculate the hash for a + certificate has changed between SSLeay 0.8 and 0.9. So you have to remove + all old hash symlinks and re-create new ones after upgrading. Use the + Makefile mod_ssl placed into this directory. +

    +

  • + + +How can I convert a certificate from PEM to DER format? +   + [L] +

    + The default certificate format for SSLeay/OpenSSL is PEM, which actually + is Base64 encoded DER with header and footer lines. For some applications + (e.g. Microsoft Internet Explorer) you need the certificate in plain DER + format. You can convert a PEM file cert.pem into the + corresponding DER file cert.der with the following command: + $ openssl x509 -in cert.pem -out cert.der -outform DER +

    +

  • + + +I try to install a Verisign certificate. Why can't I find neither the +getca nor getverisign programs Verisign mentions? +   + [L] +

    + This is because Verisign has never provided specific instructions + for Apache+mod_ssl. Rather they tell you what you should do + if you were using C2Net's Stronghold (a commercial Apache + based server with SSL support). The only thing you have to do + is to save the certificate into a file and give the name of + that file to the SSLCertificateFile directive. + Remember that you need to give the key file in as well (see + SSLCertificateKeyFile directive). For a better + CA-related overview on SSL certificate fiddling you can look at + Thawte's mod_ssl instructions. +

    +

  • + + +Can I use the Server Gated Cryptography (SGC) facility (aka Verisign Global +ID) also with mod_ssl? +   + [L] +

    + Yes, mod_ssl since version 2.1 supports the SGC facility. You don't have + to configure anything special for this, just use a Global ID as your + server certificate. The step up of the clients are then + automatically handled by mod_ssl under run-time. For details please read + the README.GlobalID document in the mod_ssl distribution. +

    +

  • + + +After I have installed my new Verisign Global ID server certificate, the +browsers complain that they cannot verify the server certificate? +   + [L] +

    + That is because Verisign uses an intermediate CA certificate between + the root CA certificate (which is installed in the browsers) and + the server certificate (which you installed in the server). You + should have received this additional CA certificate from Verisign. + If not, complain to them. Then configure this certificate with the + SSLCertificateChainFile directive in the server. This + makes sure the intermediate CA certificate is send to the browser + and this way fills the gap in the certificate chain. +

+

+
+

About SSL Protocol

+
    +

    +

  • + + +Why do I get lots of random SSL protocol errors under heavy server load? +   + [L] +

    + There can be a number of reasons for this, but the main one + is problems with the SSL session Cache specified by the + SSLSessionCache directive. The DBM session cache is most + likely the source of the problem, so trying the SHM session cache or + no cache at all may help. +

    +

  • + + +Why has my webserver a higher load now that I run SSL there? +   + [L] +

    + Because SSL uses strong cryptographic encryption and this needs a lot of + number crunching. And because when you request a webpage via HTTPS even + the images are transfered encrypted. So, when you have a lot of HTTPS + traffic the load increases. +

    +

  • + + +Often HTTPS connections to my server require up to 30 seconds for establishing +the connection, although sometimes it works faster? +   + [L] +

    + Usually this is caused by using a /dev/random device for + SSLRandomSeed which is blocking in read(2) calls if not + enough entropy is available. Read more about this problem in the refernce + chapter under SSLRandomSeed. +

    +

  • + + +What SSL Ciphers are supported by mod_ssl? +   + [L] +

    + Usually just all SSL ciphers which are supported by the + version of OpenSSL in use (can depend on the way you built + OpenSSL). Typically this at least includes the following: +

    +

      +
    • RC4 with MD5 +
    • RC4 with MD5 (export version restricted to 40-bit key) +
    • RC2 with MD5 +
    • RC2 with MD5 (export version restricted to 40-bit key) +
    • IDEA with MD5 +
    • DES with MD5 +
    • Triple-DES with MD5 +
    +

    + To determine the actual list of supported ciphers you can + run the following command: +

    + $ openssl ciphers -v
    +

    +

  • + + +I want to use Anonymous Diffie-Hellman (ADH) ciphers, but I always get ``no +shared cipher'' errors? +   + [L] +

    + In order to use Anonymous Diffie-Hellman (ADH) ciphers, it is not enough + to just put ``ADH'' into your SSLCipherSuite. + Additionally you have to build OpenSSL with + ``-DSSL_ALLOW_ADH''. Because per default OpenSSL does not + allow ADH ciphers for security reasons. So if you are actually enabling + these ciphers make sure you are informed about the side-effects. +

    +

  • + + +I always just get a 'no shared ciphers' error if +I try to connect to my freshly installed server? +   + [L] +

    + Either you have messed up your SSLCipherSuite + directive (compare it with the pre-configured example in + httpd.conf-dist) or you have choosen the DSA/DH + algorithms instead of RSA under "make certificate" + and ignored or overseen the warnings. Because if you have choosen + DSA/DH, then your server no longer speaks RSA-based SSL ciphers + (at least not until you also configure an additional RSA-based + certificate/key pair). But current browsers like NS or IE only speak + RSA ciphers. The result is the "no shared ciphers" error. To fix + this, regenerate your server certificate/key pair and this time + choose the RSA algorithm. +

    +

  • + + +Why can't I use SSL with name-based/non-IP-based virtual hosts? +   + [L] +

    + The reason is very technical. Actually it's some sort of a chicken and + egg problem: The SSL protocol layer stays below the HTTP protocol layer + and encapsulates HTTP. When an SSL connection (HTTPS) is established + Apache/mod_ssl has to negotiate the SSL protocol parameters with the + client. For this mod_ssl has to consult the configuration of the virtual + server (for instance it has to look for the cipher suite, the server + certificate, etc.). But in order to dispatch to the correct virtual server + Apache has to know the Host HTTP header field. For this the + HTTP request header has to be read. This cannot be done before the SSL + handshake is finished. But the information is already needed at the SSL + handshake phase. Bingo! +

    +

  • + + +When I use Basic Authentication over HTTPS the lock icon in Netscape browsers +still show the unlocked state when the dialog pops up. Does this mean the +username/password is still transmitted unencrypted? +   + [L] +

    + No, the username/password is already transmitted encrypted. The icon in + Netscape browsers is just not really synchronized with the SSL/TLS layer + (it toggles to the locked state when the first part of the actual webpage + data is transferred which is not quite correct) and this way confuses + people. The Basic Authentication facility is part of the HTTP layer and + this layer is above the SSL/TLS layer in HTTPS. And before any HTTP data + communication takes place in HTTPS the SSL/TLS layer has already done the + handshake phase and switched to encrypted communication. So, don't get + confused by this icon. +

    +

  • + + +When I connect via HTTPS to an Apache+mod_ssl+OpenSSL server with Microsoft Internet +Explorer (MSIE) I get various I/O errors. What is the reason? +   + [L] +

    + The first reason is that the SSL implementation in some MSIE versions has + some subtle bugs related to the HTTP keep-alive facility and the SSL close + notify alerts on socket connection close. Additionally the interaction + between SSL and HTTP/1.1 features are problematic with some MSIE versions, + too. You've to work-around these problems by forcing + Apache+mod_ssl+OpenSSL to not use HTTP/1.1, keep-alive connections or + sending the SSL close notify messages to MSIE clients. This can be done by + using the following directive in your SSL-aware virtual host section: + 

    +    SetEnvIf User-Agent ".*MSIE.*" \
+             nokeepalive ssl-unclean-shutdown \
+             downgrade-1.0 force-response-1.0
    + Additionally it is known some MSIE versions have also problems + with particular ciphers. Unfortunately one cannot workaround these + bugs only for those MSIE particular clients, because the ciphers + are already used in the SSL handshake phase. So a MSIE-specific + SetEnvIf doesn't work to solve these problems. Instead one + has to do more drastic adjustments to the global parameters. But + before you decide to do this, make sure your clients really have + problems. If not, do not do this, because it affects all(!) your + clients, i.e., also your non-MSIE clients. +

    + The next problem is that 56bit export versions of MSIE 5.x browsers have a + broken SSLv3 implementation which badly interacts with OpenSSL versions + greater than 0.9.4. You can either accept this and force your clients to + upgrade their browsers, or you downgrade to OpenSSL 0.9.4 (hmmm), or you + can decide to workaround it by accepting the drawback that your workaround + will horribly affect also other browsers: + 

    +    SSLProtocol all -SSLv3
    + This completely disables the SSLv3 protocol and lets those browsers work. + But usually this is an even less acceptable workaround. A more reasonable + workaround is to address the problem more closely and disable only the + ciphers which cause trouble. + 
    +    SSLCipherSuite ALL:!ADH:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP
    + This also lets the broken MSIE versions work, but only removes the + newer 56bit TLS ciphers. +

    + Another problem with MSIE 5.x clients is that they refuse to connect to + URLs of the form https://12.34.56.78/ (IP-addresses are used + instead of the hostname), if the server is using the Server Gated + Cryptography (SGC) facility. This can only be avoided by using the fully + qualified domain name (FQDN) of the website in hyperlinks instead, because + MSIE 5.x has an error in the way it handles the SGC negotiation. +

    + And finally there are versions of MSIE which seem to require that + an SSL session can be reused (a totally non standard-conforming + behaviour, of course). Connection with those MSIE versions only work + if a SSL session cache is used. So, as a work-around, make sure you + are using a session cache (see SSLSessionCache directive). +

    +

  • + + +When I connect via HTTPS to an Apache+mod_ssl server with Netscape Navigator I +get I/O errors and the message "Netscape has encountered bad data from the +server" What's the reason? +   + [L] +

    + The problem usually is that you had created a new server certificate with + the same DN, but you had told your browser to accept forever the old + server certificate. Once you clear the entry in your browser for the old + certificate, everything usually will work fine. Netscape's SSL + implementation is correct, so when you encounter I/O errors with Netscape + Navigator it is most of the time caused by the configured certificates. +

+

+
+

About Support

+
    +

    +

  • + + +What information resources are available in case of mod_ssl problems? +   + [L] +

    +The following information resources are available. +In case of problems you should search here first. +

    +

      +
    1. Answers in the User Manual's F.A.Q. List (this)
      + + http://www.modssl.org/docs/2.8/ssl_faq.html
      + First look inside the F.A.Q. (this text), perhaps your problem is such + popular that it was already answered a lot of times in the past. +

      +

    2. Postings from the modssl-users Support Mailing List + + http://www.modssl.org/support/
      + Second search for your problem in one of the existing archives of the + modssl-users mailing list. Perhaps your problem popped up at least once for + another user, too. +

      +

    3. Problem Reports in the Bug Database + + http://www.modssl.org/support/bugdb/
      + Third look inside the mod_ssl Bug Database. Perhaps + someone else already has reported the problem. +
    +

    +

  • + + +What support contacts are available in case of mod_ssl problems? +   + [L] +

    +The following lists all support possibilities for mod_ssl, in order of +preference, i.e. start in this order and do not pick the support possibility +you just like most, please. +

    +

      +
    1. Write a Problem Report into the Bug Database
      + + http://www.modssl.org/support/bugdb/
      + This is the preferred way of submitting your problem report, because this + way it gets filed into the bug database (it cannot be lost) and + send to the modssl-users mailing list (others see the current problems and + learn from answers). +

      +

    2. Write a Problem Report to the modssl-users Support Mailing List
      + + modssl-users @ modssl.org
      + This is the second way of submitting your problem report. You have to + subscribe to the list first, but then you can easily discuss your problem + with both the author and the whole mod_ssl user community. +

      +

    3. Write a Problem Report to the author
      + + rse @ engelschall.com
      + This is the last way of submitting your problem report. Please avoid this + in your own interest because the author is really a very busy men. Your + mail will always be filed to one of his various mail-folders and is + usually not processed as fast as a posting on modssl-users. +
    +

    +

  • + + +What information and details I've to provide to +the author when writing a bug report? +   + [L] +

    +You have to at least always provide the following information: +

    +

      +
    • Apache, mod_ssl and OpenSSL version information
      + The mod_ssl version you should really know. For instance, it's the version + number in the distribution tarball. The Apache version can be determined + by running ``httpd -v''. The OpenSSL version can be + determined by running ``openssl version''. Alternatively when + you have Lynx installed you can run the command ``lynx -mime_header + http://localhost/ | grep Server'' to determine all information in a + single step. +

      +

    • The details on how you built and installed Apache+mod_ssl+OpenSSL
      + For this you can provide a logfile of your terminal session which shows + the configuration and install steps. Alternatively you can at least + provide the author with the APACI `configure'' command line + you used (assuming you used APACI, of course). +

      +

    • In case of core dumps please include a Backtrace
      + In case your Apache+mod_ssl+OpenSSL should really dumped core please attach + a stack-frame ``backtrace'' (see the next question on how to get it). + Without this information the reason for your core dump cannot be found. + So you have to provide the backtrace, please. +

      +

    • A detailed description of your problem
      + Don't laugh, I'm totally serious. I already got a lot of problem reports + where the people not really said what's the actual problem is. So, in your + own interest (you want the problem be solved, don't you?) include as much + details as possible, please. But start with the essentials first, of + course. +
    +

    +

  • + + +I got a core dump, can you help me? +   + [L] +

    + In general no, at least not unless you provide more details about the code + location where Apache dumped core. What is usually always required in + order to help you is a backtrace (see next question). Without this + information it is mostly impossible to find the problem and help you in + fixing it. +

    +

  • + + +Ok, I got a core dump but how do I get a backtrace to find out the reason for it? +   + [L] +

    +Follow the following steps: +

    +

      +
    1. Make sure you have debugging symbols available in at least + Apache and mod_ssl. On platforms where you use GCC/GDB you have to build + Apache+mod_ssl with ``OPTIM="-g -ggdb3"'' to achieve this. On + other platforms at least ``OPTIM="-g"'' is needed. +

      +

    2. Startup the server and try to produce the core-dump. For this you perhaps + want to use a directive like ``CoreDumpDirectory /tmp'' to + make sure that the core-dump file can be written. You then should get a + /tmp/core or /tmp/httpd.core file. When you + don't get this, try to run your server under an UID != 0 (root), because + most "current" kernels do not allow a process to dump core after it has + done a setuid() (unless it does an exec()) for + security reasons (there can be privileged information left over in + memory). Additionally you can run ``/path/to/httpd -X'' + manually to force Apache to not fork. +

      +

    3. Analyze the core-dump. For this run ``gdb /path/to/httpd + /tmp/httpd.core'' or a similar command has to run. In GDB you then + just have to enter the ``bt'' command and, voila, you get the + backtrace. For other debuggers consult your local debugger manual. Send + this backtrace to the author. +
    +
+

+
+ + + + + + + + + + +
+ + + + + +
+previous page
HowTo + 		+next page
Glossary +
+
+ + + + +
+ mod_ssl 2.8, User Manual
+ The Apache Interface to OpenSSL + + 		+ Copyright © 1998-2001 + Ralf S. Engelschall
+ All Rights Reserved
+ +
+
+

+
+ + diff --git a/docs/manual/ssl/ssl_glossary.html b/docs/manual/ssl/ssl_glossary.html new file mode 100644 index 0000000000..6c50706867 --- /dev/null +++ b/docs/manual/ssl/ssl_glossary.html @@ -0,0 +1,413 @@ + + +mod_ssl: Glossary + + + + + + + + +
+ + + + +
+
+ + + + + + + + + + + + + +
+ + + + + +
+ mod_ssl + + Chapter 7 +
+
+ + + + + +
+previous page
F.A.Q. List + 		+
+
+
+ Glossary +
+
+ + + + + + + +
+ +``I know you believe you understand what you think I said, but I am not sure you +realize that what you heard is not what I meant.'' + +
+ +Richard Nixon + +
+
+
+
Authentication
+
The positive identification of a network entity such as a server, a + client, or a user. In SSL context the server and client + Certificate verification process. +

+

Access Control
+
The restriction of access to network realms. In Apache context + usually the restriction of access to certain URLs. +

+

Algorithm
+
An unambiguous formula or set of rules for solving a problem in a finite + number of steps. Algorithms for encryption are usually called Ciphers. +

+

Certificate
+
A data record used for authenticating network entities such + as a server or a client. A certificate contains X.509 information pieces + about its owner (called the subject) and the signing Certificate + Authority (called the issuer), plus the owner's public key and the + signature made by the CA. Network entities verify these signatures using + CA certificates. +

+

Certification Authority (CA)
+
A trusted third party whose purpose is to sign certificates for network + entities it has authenticated using secure means. Other network entities + can check the signature to verify that a CA has authenticated the bearer + of a certificate. +

+

Certificate Signing Request (CSR)
+
An unsigned certificate for submission to a Certification Authority, + which signs it with the Private Key of their CA Certificate. Once + the CSR is signed, it becomes a real certificate. +

+

Cipher
+
An algorithm or system for data encryption. Examples are DES, IDEA, RC4, etc. +

+

Ciphertext
+
The result after a Plaintext passed a Cipher. +

+

Configuration Directive
+
A configuration command that controls one or more aspects of a program's + behavior. In Apache context these are all the command names in the first + column of the configuration files. +

+

CONNECT
+
A HTTP command for proxying raw data channels over HTTP. It can be used to + encapsulate other protocols, such as the SSL protocol. +

+

Digital Signature
+
An encrypted text block that validates a certificate or other file. A + Certification Authority creates a signature by generating a + hash of the Public Key embedded in a Certificate, then + encrypting the hash with its own Private Key. Only the CA's + public key can decrypt the signature, verifying that the CA has + authenticated the network entity that owns the Certificate. +

+

Export-Crippled
+
Diminished in cryptographic strength (and security) in order to comply + with the United States' Export Administration Regulations (EAR). + Export-crippled cryptographic software is limited to a small key size, + resulting in Ciphertext which usually can be decrypted by brute + force. +

+

Fully-Qualified Domain-Name (FQDN)
+
The unique name of a network entity, consisting of a hostname and a domain + name that can resolve to an IP address. For example, www is a + hostname, whatever.com is a domain name, and + www.whatever.com is a fully-qualified domain name. +

+

HyperText Transfer Protocol (HTTP)
+
The HyperText Transport Protocol is the standard transmission protocol used + on the World Wide Web. +

+

HTTPS
+
The HyperText Transport Protocol (Secure), the standard encrypted + communication mechanism on the World Wide Web. This is actually just HTTP + over SSL. +

+

Message Digest
+
A hash of a message, which can be used to verify that the contents of + the message have not been altered in transit. +

+

OpenSSL
+
The Open Source toolkit for SSL/TLS; + see http://www.openssl.org/ +

+

Pass Phrase
+
The word or phrase that protects private key files. + It prevents unauthorized users from encrypting them. Usually it's just + the secret encryption/decryption key used for Ciphers. +

+

Plaintext
+
The unencrypted text. +

+

Private Key
+
The secret key in a Public Key Cryptography system, used to + decrypt incoming messages and sign outgoing ones. +

+

Public Key
+
The publically available key in a Public Key Cryptography system, used to + encrypt messages bound for its owner and to decrypt signatures made by its + owner. +

+

Public Key Cryptography
+
The study and application of asymmetric encryption systems, which use one + key for encryption and another for decryption. A corresponding pair of + such keys constitutes a key pair. Also called Asymmetric Crypography. +

+

Secure Sockets Layer (SSL)
+
A protocol created by Netscape Communications Corporation for + general communication authentication and encryption over TCP/IP networks. + The most popular usage is HTTPS, i.e. the HyperText Transfer + Protocol (HTTP) over SSL. +

+

Session
+
The context information of an SSL communication. +

+

SSLeay
+
The original SSL/TLS implementation library developed by + Eric A. Young <eay@aus.rsa.com>; + see http://www.ssleay.org/ +

+

Symmetric Cryptography
+
The study and application of Ciphers that use a single secret key + for both encryption and decryption operations. +

+

Transport Layer Security (TLS)
+
The successor protocol to SSL, created by the Internet Engineering Task + Force (IETF) for general communication authentication and encryption over + TCP/IP networks. TLS version 1 and is nearly identical with SSL version 3. +

+

Uniform Resource Locator (URL)
+
The formal identifier to locate various resources on the World Wide Web. + The most popular URL scheme is http. SSL uses the + scheme https +

+

X.509
+
An authentication certificate scheme recommended by the International + Telecommunication Union (ITU-T) which is used for SSL/TLS authentication. +
+

+
+ + + + + + + + + + +
+ + + + + +
+previous page
F.A.Q. List + 		+
+
+ + + + +
+ mod_ssl 2.8, User Manual
+ The Apache Interface to OpenSSL + + 		+ Copyright © 1998-2001 + Ralf S. Engelschall
+ All Rights Reserved
+ +
+
+

+
+ + diff --git a/docs/manual/ssl/ssl_howto.html b/docs/manual/ssl/ssl_howto.html new file mode 100644 index 0000000000..01ff7a99ac --- /dev/null +++ b/docs/manual/ssl/ssl_howto.html @@ -0,0 +1,929 @@ + + +mod_ssl: HowTo + + + + + + + + + + +
+ + + + +
+
+ + + + + + + + + + + + + +
+ + + + + +
+ mod_ssl + + Chapter 5 +
+
+ + + + + +
+previous page
Compatibility + 		+next page
F.A.Q. List +
+
+
+ HowTo +
+
+ + + + + + + +
+ +``The solution of this problem is trivial + and is left as an exercise for the reader.'' + +
+ +Standard textbook cookie + +
+
+

+ + + + + + +
+H +ow to solve particular security constraints for an SSL-aware webserver +is not always obvious because of the coherences between SSL, HTTP and Apache's +way of processing requests. This chapter gives instructions on how to solve +such typical situations. Treat is as a first step to find out the final +solution, but always try to understand the stuff before you use it. Nothing is +worse than using a security solution without knowing it's restrictions and +coherences. + +   + +
+ + + + + + + +
+ +Table Of Contents + +
+ +        Cipher Suites and Enforced Strong Security
+                SSLv2 only server
+                strong encryption only server
+                server gated cryptography
+                stronger per-directory requirements
+        Client Authentication and Access Control
+                simple certificate-based client authentication
+                selective certificate-based client authentication
+                particular certificate-based client authentication
+                intranet vs. internet authentication
+ +
+
+
+

Cipher Suites and Enforced Strong Security

+
    +

    +

  • + + +How can I create a real SSLv2-only server? +   + [L] +

    +The following creates an SSL server which speaks only the SSLv2 protocol and +its ciphers. +

    + + + + + + + + + + + + + + + + + + + + + + + + +
      httpd.conf  
    + + + + +
    +
    +
+SSLProtocol -all +SSLv2
+SSLCipherSuite SSLv2:+HIGH:+MEDIUM:+LOW:+EXP
+
+
    +
    +
    +

    +

  • + + +How can I create an SSL server which accepts strong encryption only? +   + [L] +

    +The following enables only the seven strongest ciphers: +

    + + + + + + + + + + + + + + + + + + + + + + + + +
      httpd.conf  
    + + + + +
    +
    +
+SSLProtocol all
+SSLCipherSuite HIGH:MEDIUM
+
+
    +
    +
    +

    +

  • + + +How can I create an SSL server which accepts strong encryption only, +but allows export browsers to upgrade to stronger encryption? +   + [L] +

    +This facility is called Server Gated Cryptography (SGC) and details you can +find in the README.GlobalID document in the mod_ssl distribution. +In short: The server has a Global ID server certificate, signed by a special +CA certificate from Verisign which enables strong encryption in export +browsers. This works as following: The browser connects with an export cipher, +the server sends it's Global ID certificate, the browser verifies it and +subsequently upgrades the cipher suite before any HTTP communication takes +place. The question now is: How can we allow this upgrade, but enforce strong +encryption. Or in other words: Browser either have to initially connect with +strong encryption or have to upgrade to strong encryption, but are not allowed +to keep the export ciphers. The following does the trick: +

    + + + + + + + + + + + + + + + + + + + + + + + + +
      httpd.conf  
    + + + + +
    +
    +
+#   allow all ciphers for the inital handshake,
+#   so export browsers can upgrade via SGC facility
+SSLCipherSuite ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP:+eNULL
+<Directory /usr/local/apache/htdocs>
+#   but finally deny all browsers which haven't upgraded
+SSLRequire %{SSL_CIPHER_USEKEYSIZE} >= 128
+</Directory>
+
+
    +
    +
    +

    +

  • + + +How can I create an SSL server which accepts all types of ciphers in general, +but requires a strong ciphers for access to a particular URL? +   + [L] +

    +Obviously you cannot just use a server-wide SSLCipherSuite which +restricts the ciphers to the strong variants. But mod_ssl allows you to +reconfigure the cipher suite in per-directory context and automatically forces +a renegotiation of the SSL parameters to meet the new configuration. So, the +solution is: +

    + + + + + + + + + + + + + + + + + + + + + + + + +
      httpd.conf  
    + + + + +
    +
    +
+#   be liberal in general
+SSLCipherSuite ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP:+eNULL
+<Location /strong/area>
+#   but https://hostname/strong/area/ and below requires strong ciphers
+SSLCipherSuite HIGH:MEDIUM
+</Location>
+
+
    +
    +
    +

+

Client Authentication and Access Control

+
    +

    +

  • + + +How can I authenticate clients based on certificates when I know all my +clients? +   + [L] +

    +When you know your user community (i.e. a closed user group situation), as +it's the case for instance in an Intranet, you can use plain certificate +authentication. All you have to do is to create client certificates signed by +your own CA certificate ca.crt and then verifiy the clients +against this certificate. +

    + + + + + + + + + + + + + + + + + + + + + + + + +
      httpd.conf  
    + + + + +
    +
    +
+#   require a client certificate which has to be directly
+#   signed by our CA certificate in ca.crt
+SSLVerifyClient require
+SSLVerifyDepth 1
+SSLCACertificateFile conf/ssl.crt/ca.crt
+
+
    +
    +
    +

    +

  • + + +How can I authenticate my clients for a particular URL based on certificates +but still allow arbitrary clients to access the remaining parts of the server? +   + [L] +

    +For this we again use the per-directory reconfiguration feature of mod_ssl: +

    + + + + + + + + + + + + + + + + + + + + + + + + +
      httpd.conf  
    + + + + +
    +
    +
+SSLVerifyClient none
+SSLCACertificateFile conf/ssl.crt/ca.crt
+<Location /secure/area>
+SSLVerifyClient require
+SSLVerifyDepth 1
+</Location>
+
+
    +
    +
    +

    +

  • + + +How can I authenticate only particular clients for a some URLs based +on certificates but still allow arbitrary clients to access the remaining +parts of the server? +   + [L] +

    +The key is to check for various ingredients of the client certficate. Usually +this means to check the whole or part of the Distinguished Name (DN) of the +Subject. For this two methods exists: The mod_auth based variant +and the SSLRequire variant. The first method is good when the +clients are of totally different type, i.e. when their DNs have no common +fields (usually the organisation, etc.). In this case you've to establish a +password database containing all clients. The second method is better +when your clients are all part of a common hierarchy which is encoded into the +DN. Then you can match them more easily. +

    +The first method: +

    + + + + + + + + + + + + + + + + + + + + + + + + +
      /usr/local/apache/conf/httpd.conf  
    + + + + +
    +
    +
+SSLVerifyClient      none
+<Directory /usr/local/apache/htdocs/secure/area>
+SSLVerifyClient      require
+SSLVerifyDepth       5
+SSLCACertificateFile conf/ssl.crt/ca.crt
+SSLCACertificatePath conf/ssl.crt
+SSLOptions           +FakeBasicAuth
+SSLRequireSSL
+AuthName             "Snake Oil Authentication"
+AuthType             Basic
+AuthUserFile         /usr/local/apache/conf/httpd.passwd
+require              valid-user
+</Directory>
+
+
    +
    +
    +

    + + + + + + + + + + + + + + + + + + + + + + + + +
      /usr/local/apache/conf/httpd.passwd  
    + + + + +
    +
    +
+/C=DE/L=Munich/O=Snake Oil, Ltd./OU=Staff/CN=Foo:xxj31ZMTZzkVA
+/C=US/L=S.F./O=Snake Oil, Ltd./OU=CA/CN=Bar:xxj31ZMTZzkVA
+/C=US/L=L.A./O=Snake Oil, Ltd./OU=Dev/CN=Quux:xxj31ZMTZzkVA
+
+
    +
    +
    +

    +The second method: +

    + + + + + + + + + + + + + + + + + + + + + + + + +
      httpd.conf  
    + + + + +
    +
    +
+SSLVerifyClient      none
+<Directory /usr/local/apache/htdocs/secure/area>
+SSLVerifyClient      require
+SSLVerifyDepth       5
+SSLCACertificateFile conf/ssl.crt/ca.crt
+SSLCACertificatePath conf/ssl.crt
+SSLOptions           +FakeBasicAuth
+SSLRequireSSL
+SSLRequire           %{SSL_CLIENT_S_DN_O}  eq "Snake Oil, Ltd." and \
+                     %{SSL_CLIENT_S_DN_OU} in {"Staff", "CA", "Dev"}
+</Directory>
+
+
    +
    +
    +

    +

  • + + How can +I require HTTPS with strong ciphers and either basic authentication or client +certificates for access to a subarea on the Intranet website for clients +coming from the Internet but still allow plain HTTP access for clients on the +Intranet? +   + [L] +

    +Let us assume the Intranet can be distinguished through the IP network +192.160.1.0/24 and the subarea on the Intranet website has the URL +/subarea. Then configure the following outside your HTTPS virtual +host (so it applies to both HTTPS and HTTP): +

    + + + + + + + + + + + + + + + + + + + + + + + + +
      httpd.conf  
    + + + + +
    +
    +
+SSLCACertificateFile conf/ssl.crt/company-ca.crt
+
+<Directory /usr/local/apache/htdocs>
+#   Outside the subarea only Intranet access is granted
+Order                deny,allow
+Deny                 from all
+Allow                from 192.168.1.0/24
+</Directory>
+
+<Directory /usr/local/apache/htdocs/subarea>
+#   Inside the subarea any Intranet access is allowed
+#   but from the Internet only HTTPS + Strong-Cipher + Password
+#   or the alternative HTTPS + Strong-Cipher + Client-Certificate
+
+#   If HTTPS is used, make sure a strong cipher is used.
+#   Additionally allow client certs as alternative to basic auth.
+SSLVerifyClient      optional
+SSLVerifyDepth       1
+SSLOptions           +FakeBasicAuth +StrictRequire
+SSLRequire           %{SSL_CIPHER_USEKEYSIZE} >= 128
+
+#   Force clients from the Internet to use HTTPS
+RewriteEngine        on
+RewriteCond          %{REMOTE_ADDR} !^192\.168\.1\.[0-9]+$
+RewriteCond          %{HTTPS} !=on
+RewriteRule          .* - [F]
+
+#   Allow Network Access and/or Basic Auth
+Satisfy              any
+
+#   Network Access Control
+Order                deny,allow
+Deny                 from all
+Allow                192.168.1.0/24
+
+#   HTTP Basic Authentication
+AuthType             basic
+AuthName             "Protected Intranet Area"
+AuthUserFile         conf/protected.passwd
+Require              valid-user
+</Directory>
+
+
    +
    +
    +

+

+
+ + + + + + + + + + +
+ + + + + +
+previous page
Compatibility + 		+next page
F.A.Q. List +
+
+ + + + +
+ mod_ssl 2.8, User Manual
+ The Apache Interface to OpenSSL + + 		+ Copyright © 1998-2001 + Ralf S. Engelschall
+ All Rights Reserved
+ +
+
+

+
+ + diff --git a/docs/manual/ssl/ssl_intro.html b/docs/manual/ssl/ssl_intro.html new file mode 100644 index 0000000000..fae805f07a --- /dev/null +++ b/docs/manual/ssl/ssl_intro.html @@ -0,0 +1,919 @@ + + +mod_ssl: Introduction + + + + + + + + + + +
+ + + + +
+
+ + + + + + + + + + + + + +
+ + + + + +
+ mod_ssl + + Chapter 2 +
+
+ + + + + +
+previous page
Overview + 		+next page
Reference +
+
+
+ Introduction +
+
+ + + + + + + +
+ +``The nice thing about standards is that there are so many to choose from. +And if you really don't like all the standards you just have to wait another +year until the one arises you are looking for.'' + +
+ +A. Tanenbaum, ``Introduction to Computer Networks'' + +
+
+

+ + + + + + +
+A +s an introduction this chapter is aimed at readers who are familiar +with the Web, HTTP, and Apache, but are not security experts. It is not +intended to be a definitive guide to the SSL protocol, nor does it discuss +specific techniques for managing certificates in an organization, or the +important legal issues of patents and import and export restrictions. Rather, +it is intended to provide a common background to mod_ssl users by pulling +together various concepts, definitions, and examples as a starting point for +further exploration. +

+The presented content is mainly derived, with permission by the author, from +the article Introducing SSL +and Certificates using SSLeay from Frederick J. Hirsch, of The Open +Group Research Institute, which was published in Web Security: A Matter of +Trust, World Wide Web Journal, Volume 2, Issue 3, Summer 1997. +Please send any postive feedback to Frederick Hirsch (the original +article author) and all negative feedback to Ralf S. Engelschall (the mod_ssl +author). +

 +   + +
+ + + + + + + +
+ +Table Of Contents + +
+ +        Cryptographic Techniques
+                Cryptographic Algorithms
+                Message Digests
+                Digital Signatures
+        Certificates
+                Certificate Contents
+                Certificate Authorities
+                        Certificate Chains
+                        Creating a Root-Level CA
+                        Certificate Management
+        Secure Sockets Layer (SSL)
+                Session Establishment
+                Key Exchange Method
+                Cipher for Data Transfer
+                Digest Function
+                Handshake Sequence Protocol
+                Data Transfer
+                Securing HTTP Communication
+        References
+ +
+
+
+

Cryptographic Techniques

+Understanding SSL requires an understanding of cryptographic algorithms, +message digest functions (aka. one-way or hash functions), and digital +signatures. These techniques are the subject of entire books (see for instance +[AC96]) and provide the basis for privacy, integrity, and +authentication. +

Cryptographic Algorithms

+Suppose Alice wants to send a message to her bank to transfer some money. +Alice would like the message to be private, since it will include information +such as her account number and transfer amount. One solution is to use a +cryptographic algorithm, a technique that would transform her message into an +encrypted form, unreadable except by those it is intended for. Once in this +form, the message may only be interpreted through the use of a secret key. +Without the key the message is useless: good cryptographic algorithms make it +so difficult for intruders to decode the original text that it isn't worth +their effort. +

+There are two categories of cryptographic algorithms: +conventional and public key. +

    +
  • Conventional cryptography, also known as symmetric +cryptography, requires the sender and receiver to share a key: a secret +piece of information that may be used to encrypt or decrypt a message. +If this key is secret, then nobody other than the sender or receiver may +read the message. If Alice and the bank know a secret key, then they +may send each other private messages. The task of privately choosing a key +before communicating, however, can be problematic. +

    +

  • Public key cryptography, also known as asymmetric cryptography, +solves the key exchange problem by defining an algorithm which uses two keys, +each of which may be used to encrypt a message. If one key is used to encrypt +a message then the other must be used to decrypt it. This makes it possible +to receive secure messages by simply publishing one key (the public key) and +keeping the other secret (the private key). +

    +Anyone may encrypt a message using the public key, but only the owner of the +private key will be able to read it. In this way, Alice may send private +messages to the owner of a key-pair (the bank), by encrypting it using their +public key. Only the bank will be able to decrypt it. +

+

Message Digests

+Although Alice may encrypt her message to make it private, there is still a +concern that someone might modify her original message or substitute +it with a different one, in order to transfer the money to themselves, for +instance. One way of guaranteeing the integrity of Alice's message is to +create a concise summary of her message and send this to the bank as well. +Upon receipt of the message, the bank creates its own summary and compares it +with the one Alice sent. If they agree then the message was received intact. +

+A summary such as this is called a message digest, one-way +function or hash function. Message digests are used to create +short, fixed-length representations of longer, variable-length messages. +Digest algorithms are designed to produce unique digests for different +messages. Message digests are designed to make it too difficult to determine +the message from the digest, and also impossible to find two different +messages which create the same digest -- thus eliminating the possibility of +substituting one message for another while maintaining the same digest. +

+Another challenge that Alice faces is finding a way to send the digest to the +bank securely; when this is achieved, the integrity of the associated message +is assured. One way to to this is to include the digest in a digital +signature. +

Digital Signatures

+When Alice sends a message to the bank, the bank needs to ensure that the +message is really from her, so an intruder does not request a transaction +involving her account. A digital signature, created by Alice and +included with the message, serves this purpose. +

+Digital signatures are created by encrypting a digest of the message, +and other information (such as a sequence number) with the sender's +private key. Though anyone may decrypt the signature using the public +key, only the signer knows the private key. This means that only they may +have signed it. Including the digest in the signature means the signature is +only good for that message; it also ensures the integrity of the message since +no one can change the digest and still sign it. +

+To guard against interception and reuse of the signature by an intruder at a +later date, the signature contains a unique sequence number. This protects +the bank from a fraudulent claim from Alice that she did not send the message +-- only she could have signed it (non-repudiation). +

Certificates

+Although Alice could have sent a private message to the bank, signed it, and +ensured the integrity of the message, she still needs to be sure that she is +really communicating with the bank. This means that she needs to be sure that +the public key she is using corresponds to the bank's private key. Similarly, +the bank also needs to verify that the message signature really corresponds to +Alice's signature. +

+If each party has a certificate which validates the other's identity, confirms +the public key, and is signed by a trusted agency, then they both will be +assured that they are communicating with whom they think they are. Such a +trusted agency is called a Certificate Authority, and certificates are +used for authentication. +

Certificate Contents

+A certificate associates a public key with the real identity of an individual, +server, or other entity, known as the subject. As shown in Table 1, information about the subject includes identifying +information (the distinguished name), and the public key. It also includes +the identification and signature of the Certificate Authority that issued the +certificate, and the period of time during which the certificate is valid. It +may have additional information (or extensions) as well as administrative +information for the Certificate Authority's use, such as a serial number. +

+

+ + + +
Table 1: Certificate Information
+ + +
+ + + + + + + + + + + +
Subject:Distinguished Name, Public Key
Issuer:Distinguished Name, Signature
Period of Validity:Not Before Date, Not After Date
Administrative Information:Version, Serial Number
Extended Information:Basic Contraints, Netscape Flags, etc.
+
+
+
+

+A distinguished name is used to provide an identity in a specific context -- +for instance, an individual might have a personal certificate as well as one +for their identity as an employee. Distinguished names are defined by the +X.509 standard [X509], which defines the fields, field +names, and abbreviations used to refer to the fields +(see Table 2). +

+

+ + + +
Table 2: Distinguished Name Information
+ + +
+ + + + + + + + + + + + + + + + +
DN Field:Abbrev.:Description:Example:
Common NameCNName being certifiedCN=Joe Average
Organization or CompanyOName is associated with this
organization		O=Snake Oil, Ltd.
Organizational UnitOUName is associated with this
organization unit, such as a department		OU=Research Institute
City/LocalityLName is located in this CityL=Snake City
State/ProvinceSTName is located in this State/ProvinceST=Desert
CountryCName is located in this Country (ISO code)C=XZ
+
+
+
+

+A Certificate Authority may define a policy specifying which distinguished +field names are optional, and which are required. It may also place +requirements upon the field contents, as may users of certificates. As an +example, a Netscape browser requires that the Common Name for a certificate +representing a server has a name which matches a wildcard pattern for the +domain name of that server, such as *.snakeoil.com. +

+The binary format of a certificate is defined using the ASN.1 notation [ X208] [PKCS]. This notation defines how to +specify the contents, and encoding rules define how this information is +translated into binary form. The binary encoding of the certificate is +defined using Distinguished Encoding Rules (DER), which are based on the more +general Basic Encoding Rules (BER). For those transmissions which cannot +handle binary, the binary form may be translated into an ASCII form by using +Base64 encoding [MIME]. This encoded version is called PEM +encoded (the name comes from "Privacy Enhanced Mail"), when placed between +begin and end delimiter lines as illustrated in Table 3. +

+

+ + + +
Table 3: Example of a PEM-encoded certificate (snakeoil.crt)
+ + +
+
+
+-----BEGIN CERTIFICATE-----
+MIIC7jCCAlegAwIBAgIBATANBgkqhkiG9w0BAQQFADCBqTELMAkGA1UEBhMCWFkx
+FTATBgNVBAgTDFNuYWtlIERlc2VydDETMBEGA1UEBxMKU25ha2UgVG93bjEXMBUG
+A1UEChMOU25ha2UgT2lsLCBMdGQxHjAcBgNVBAsTFUNlcnRpZmljYXRlIEF1dGhv
+cml0eTEVMBMGA1UEAxMMU25ha2UgT2lsIENBMR4wHAYJKoZIhvcNAQkBFg9jYUBz
+bmFrZW9pbC5kb20wHhcNOTgxMDIxMDg1ODM2WhcNOTkxMDIxMDg1ODM2WjCBpzEL
+MAkGA1UEBhMCWFkxFTATBgNVBAgTDFNuYWtlIERlc2VydDETMBEGA1UEBxMKU25h
+a2UgVG93bjEXMBUGA1UEChMOU25ha2UgT2lsLCBMdGQxFzAVBgNVBAsTDldlYnNl
+cnZlciBUZWFtMRkwFwYDVQQDExB3d3cuc25ha2VvaWwuZG9tMR8wHQYJKoZIhvcN
+AQkBFhB3d3dAc25ha2VvaWwuZG9tMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKB
+gQDH9Ge/s2zcH+da+rPTx/DPRp3xGjHZ4GG6pCmvADIEtBtKBFAcZ64n+Dy7Np8b
+vKR+yy5DGQiijsH1D/j8HlGE+q4TZ8OFk7BNBFazHxFbYI4OKMiCxdKzdif1yfaa
+lWoANFlAzlSdbxeGVHoT0K+gT5w3UxwZKv2DLbCTzLZyPwIDAQABoyYwJDAPBgNV
+HRMECDAGAQH/AgEAMBEGCWCGSAGG+EIBAQQEAwIAQDANBgkqhkiG9w0BAQQFAAOB
+gQAZUIHAL4D09oE6Lv2k56Gp38OBDuILvwLg1v1KL8mQR+KFjghCrtpqaztZqcDt
+2q2QoyulCgSzHbEGmi0EsdkPfg6mp0penssIFePYNI+/8u9HT4LuKMJX15hxBam7
+dUHzICxBVC1lnHyYGjDuAMhe396lYAn8bCld1/L4NMGBCQ==
+-----END CERTIFICATE-----
+
+
+
+
+

Certificate Authorities

+By first verifying the information in a certificate request before granting +the certificate, the Certificate Authority assures the identity of the private +key owner of a key-pair. For instance, if Alice requests a personal +certificate, the Certificate Authority must first make sure that Alice really +is the person the certificate request claims. +

Certificate Chains

+A Certificate Authority may also issue a certificate for another Certificate +Authority. When examining a certificate, Alice may need to examine the +certificate of the issuer, for each parent Certificate Authority, until +reaching one which she has confidence in. She may decide to trust only +certificates with a limited chain of issuers, to reduce her risk of a "bad" +certificate in the chain. +

Creating a Root-Level CA

+As noted earlier, each certificate requires an issuer to assert the validity +of the identity of the certificate subject, up to the top-level Certificate +Authority (CA). This presents a problem: Since this is who vouches for the +certificate of the top-level authority, which has no issuer? +In this unique case, the certificate is "self-signed", so the issuer of the +certificate is the same as the subject. As a result, one must exercise extra +care in trusting a self-signed certificate. The wide publication of a public +key by the root authority reduces the risk in trusting this key -- it would be +obvious if someone else publicized a key claiming to be the authority. +Browsers are preconfigured to trust well-known certificate authorities. +

+A number of companies, such as Thawte and +VeriSign have established themselves as +Certificate Authorities. These companies provide the following services: +

    +
  • Verifying certificate requests +
  • Processing certificate requests +
  • Issuing and managing certificates +
+

+It is also possible to create your own Certificate Authority. Although risky +in the Internet environment, it may be useful within an Intranet where the +organization can easily verify the identities of individuals and servers. +

Certificate Management

+Establishing a Certificate Authority is a responsibility which requires a +solid administrative, technical, and management framework. +Certificate Authorities not only issue certificates, they also manage them -- +that is, they determine how long certificates are valid, they renew them, and +they keep lists of certificates that have already been issued but are no +longer valid (Certificate Revocation Lists, or CRLs). +Say Alice is entitled to a certificate as an employee of a company. Say too, +that the certificate needs to be revoked when Alice leaves the company. Since +certificates are objects that get passed around, it is impossible to tell from +the certificate alone that it has been revoked. +When examining certificates for validity, therefore, it is necessary to +contact the issuing Certificate Authority to check CRLs -- this is not usually +an automated part of the process. +

+

Note:
+If you use a Certificate Authority that is not configured into browsers by +default, it is necessary to load the Certificate Authority certificate into +the browser, enabling the browser to validate server certificates signed by +that Certificate Authority. Doing so may be dangerous, since once loaded, the +browser will accept all certificates signed by that Certificate Authority. +

Secure Sockets Layer (SSL)

+The Secure Sockets Layer protocol is a protocol layer which may be placed +between a reliable connection-oriented network layer protocol (e.g. TCP/IP) +and the application protocol layer (e.g. HTTP). SSL provides for secure +communication between client and server by allowing mutual authentication, the +use of digital signatures for integrity, and encryption for privacy. +

+The protocol is designed to support a range of choices for specific algorithms +used for cryptography, digests, and signatures. This allows algorithm +selection for specific servers to be made based on legal, export or other +concerns, and also enables the protocol to take advantage of new algorithms. +Choices are negotiated between client and server at the start of establishing +a protocol session. +

+

+ + + +
Table 4: Versions of the SSL protocol
+ + +
+ + + + + + + + + + + + + + + + + + + + + + + + +
Version:Source:Description:Browser Support:
SSL v2.0Vendor Standard (from Netscape Corp.) [SSL2]First SSL protocol for which implementations exists- NS Navigator 1.x/2.x
+ - MS IE 3.x
+ - Lynx/2.8+OpenSSL +
SSL v3.0Expired Internet Draft (from Netscape Corp.) [SSL3]Revisions to prevent specific security attacks, add non-RSA ciphers, and support for certificate chains- NS Navigator 2.x/3.x/4.x
+ - MS IE 3.x/4.x
+ - Lynx/2.8+OpenSSL +
TLS v1.0Proposed Internet Standard (from IETF) [TLS1]Revision of SSL 3.0 to update the MAC layer to HMAC, add block padding for + block ciphers, message order standardization and more alert messages. +- Lynx/2.8+OpenSSL
+
+
+
+

+There are a number of versions of the SSL protocol, as shown in Table 4. As noted there, one of the benefits in SSL 3.0 is +that it adds support of certificate chain loading. This feature allows a +server to pass a server certificate along with issuer certificates to the +browser. Chain loading also permits the browser to validate the server +certificate, even if Certificate Authority certificates are not installed for +the intermediate issuers, since they are included in the certificate chain. +SSL 3.0 is the basis for the Transport Layer Security [TLS] protocol standard, currently in development by the +Internet Engineering Task Force (IETF). +

Session Establishment

+The SSL session is established by following a handshake sequence +between client and server, as shown in Figure 1. This +sequence may vary, depending on whether the server is configured to provide a +server certificate or request a client certificate. Though cases exist where +additional handshake steps are required for management of cipher information, +this article summarizes one common scenario: see the SSL specification for the +full range of possibilities. +

+

Note
+Once an SSL session has been established it may be reused, thus avoiding the +performance penalty of repeating the many steps needed to start a session. +For this the server assigns each SSL session a unique session identifier which +is cached in the server and which the client can use on forthcoming +connections to reduce the handshake (until the session identifer expires in +the cache of the server). +

+

+ + + +
Figure 1: Simplified SSL Handshake Sequence
+ + +
+ +
+
+
+

+The elements of the handshake sequence, as used by the client and server, are +listed below: +

    +
  1. Negotiate the Cipher Suite to be used during data transfer +
  2. Establish and share a session key between client and server +
  3. Optionally authenticate the server to the client +
  4. Optionally authenticate the client to the server +
+

+The first step, Cipher Suite Negotiation, allows the client and server to +choose a Cipher Suite supportable by both of them. The SSL3.0 protocol +specification defines 31 Cipher Suites. A Cipher Suite is defined by the +following components: +

    +
  • Key Exchange Method +
  • Cipher for Data Transfer +
  • Message Digest for creating the Message Authentication Code (MAC) +
+These three elements are described in the sections that follow. +

Key Exchange Method

+The key exchange method defines how the shared secret symmetric cryptography +key used for application data transfer will be agreed upon by client and +server. SSL 2.0 uses RSA key exchange only, while SSL 3.0 supports a choice of +key exchange algorithms including the RSA key exchange when certificates are +used, and Diffie-Hellman key exchange for exchanging keys without certificates +and without prior communication between client and server. +

+One variable in the choice of key exchange methods is digital signatures -- +whether or not to use them, and if so, what kind of signatures to use. +Signing with a private key provides assurance against a +man-in-the-middle-attack during the information exchange used in generating +the shared key [AC96, p516]. +

Cipher for Data Transfer

+SSL uses the conventional cryptography algorithm (symmetric cryptography) +described earlier for encrypting messages in a session. There are nine +choices, including the choice to perform no encryption: +
    +
  • No encryption +
  • Stream Ciphers +
      +
    • RC4 with 40-bit keys +
    • RC4 with 128-bit keys +
    +
  • CBC Block Ciphers +
      +
    • RC2 with 40 bit key +
    • DES with 40 bit key +
    • DES with 56 bit key +
    • Triple-DES with 168 bit key +
    • Idea (128 bit key) +
    • Fortezza (96 bit key) +
    +
+Here "CBC" refers to Cipher Block Chaining, which means that a portion of the +previously encrypted cipher text is used in the encryption of the current +block. "DES" refers to the Data Encryption Standard [AC96, +ch12], which has a number of variants (including DES40 and 3DES_EDE). "Idea" +is one of the best and cryptographically strongest available algorithms, and +"RC2" is a proprietary algorithm from RSA DSI [AC96, +ch13]. +

Digest Function

+The choice of digest function determines how a digest is created from a record +unit. SSL supports the following: +
    +
  • No digest (Null choice) +
  • MD5, a 128-bit hash +
  • Secure Hash Algorithm (SHA-1), a 160-bit hash +
+The message digest is used to create a Message Authentication Code (MAC) which +is encrypted with the message to provide integrity and to prevent against +replay attacks. +

Handshake Sequence Protocol

+The handshake sequence uses three protocols: +
    +
  • The SSL Handshake Protocol + for performing the client and server SSL session establishment. +
  • The SSL Change Cipher Spec Protocol for actually establishing agreement + on the Cipher Suite for the session. +
  • The SSL Alert Protocol for + conveying SSL error messages between client and server. +
+These protocols, as well as application protocol data, are encapsulated in the +SSL Record Protocol, as shown in Figure 2. An +encapsulated protocol is transferred as data by the lower layer protocol, +which does not examine the data. The encapsulated protocol has no knowledge of +the underlying protocol. +

+

+ + + +
Figure 2: SSL Protocol Stack
+ + +
+ +
+
+
+

+The encapsulation of SSL control protocols by the record protocol means that +if an active session is renegotiated the control protocols will be transmitted +securely. If there were no session before, then the Null cipher suite is +used, which means there is no encryption and messages have no integrity +digests until the session has been established. +

Data Transfer

+The SSL Record Protocol, shown in Figure 3, is used to +transfer application and SSL Control data between the client and server, +possibly fragmenting this data into smaller units, or combining multiple +higher level protocol data messages into single units. It may compress, attach +digest signatures, and encrypt these units before transmitting them using the +underlying reliable transport protocol (Note: currently all major SSL +implementations lack support for compression). +

+

+ + + +
Figure 3: SSL Record Protocol
+ + +
+ +
+
+
+

Securing HTTP Communication

+One common use of SSL is to secure Web HTTP communication between a browser +and a webserver. This case does not preclude the use of non-secured HTTP. The +secure version is mainly plain HTTP over SSL (named HTTPS), but with one major +difference: it uses the URL scheme https rather than +http and a different server port (by default 443). This mainly +is what mod_ssl provides to you for the Apache webserver... +

References

+ +

+
+ + + + + + + + + + +
+ + + + + +
+previous page
Overview + 		+next page
Reference +
+
+ + + + +
+ mod_ssl 2.8, User Manual
+ The Apache Interface to OpenSSL + + 		+ Copyright © 1998-2001 + Ralf S. Engelschall
+ All Rights Reserved
+ +
+
+

+
+ + diff --git a/docs/manual/ssl/ssl_overview.html b/docs/manual/ssl/ssl_overview.html new file mode 100644 index 0000000000..be48d6c77f --- /dev/null +++ b/docs/manual/ssl/ssl_overview.html @@ -0,0 +1,476 @@ + + +mod_ssl: Preface + + + + + + + + + + +
+ + + + +
+
+ + + + + + + + + + + + + +
+ + + + + +
+ mod_ssl + + Chapter 1 +
+
+ + + + + +
+previous page
Cover + 		+next page
Introduction +
+
+
+ Preface +
+
+ + + + + + + +
+ +``Ralf Engelschall has released an +excellent module that integrates +Apache and SSLeay.'' + +
+ +Tim J. Hudson, SSLeay F.A.Q. + +
+
+

+ + + + + + +
+T +his module provides strong cryptography for the Apache (v1.3) webserver via the Secure Socket Layer +(SSL v2/v3) and Transport Layer +Security (TLS v1) protocols by the help of the excellent SSL/TLS +implementation library OpenSSL from Eric A. Young and Tim Hudson. + +   + + +
+

+The mod_ssl package was +created in April 1998 by Ralf S. +Engelschall and was originally derived from the Apache-SSL package developed by Ben Laurie. It stays under a BSD-style +license which is equivalent to the license used by The Apache Group for the Apache webserver +itself. This means, in short, that you are free to use it both for commercial +and non-commercial purposes as long as you retain the authors' copyright +notices and give the proper credit. +

Legalese

+Although the above conditions also apply to Apache and OpenSSL in general (both +are freely available and useable software packages), you should be aware that +especially the cryptographic algorithms used inside OpenSSL stay under +certain patents and perhaps import/export/use restrictions in some countries +of the world. So whether you can actually use the combination +Apache+mod_ssl+OpenSSL in your country depends mainly on your local state laws. +The authors of neither Apache nor mod_ssl nor OpenSSL are liable for any +violations you make here. +

+If you're not sure what law details apply to your country you're strongly +advised to first determine them by consulting an attorney before using this +module. A lot of hints you can find in the International Law +Crypto Survey which is a really comprehensive resource on this topic. At +least two countries with heavy cryptography restrictions are well known: +In the United States (USA) it's not allowed to (re-)export mod_ssl +or OpenSSL And inside France it's not allowed to use any cryptography at all +when keys with more than 40 bits are used. +

+ + + + +
+ + + + +
+ +This software package uses strong cryptography, so while it is created, +maintained and distributed from Germany and Switzerland (where it is legal to +do this), it falls under certain export/import and/or use restrictions in some +other parts of the world. +

+PLEASE REMEMBER THAT EXPORT/IMPORT AND/OR USE OF STRONG CRYPTOGRAPHY +SOFTWARE, PROVIDING CRYPTOGRAPHY HOOKS OR EVEN JUST COMMUNICATING TECHNICAL +DETAILS ABOUT CRYPTOGRAPHY SOFTWARE IS ILLEGAL IN SOME PARTS OF THE WORLD. +SO, WHEN YOU IMPORT THIS PACKAGE TO YOUR COUNTRY, RE-DISTRIBUTE IT FROM +THERE OR EVEN JUST EMAIL TECHNICAL SUGGESTIONS OR EVEN SOURCE PATCHES TO THE +AUTHOR OR OTHER PEOPLE YOU ARE STRONGLY ADVISED TO PAY CLOSE ATTENTION TO +ANY EXPORT/IMPORT AND/OR USE LAWS WHICH APPLY TO YOU. THE AUTHOR OF MOD_SSL +IS NOT LIABLE FOR ANY VIOLATIONS YOU MAKE HERE. SO BE CAREFULLY YOURSELF, IT +IS YOUR RESPONSIBILITY. + +

+ +CREDIT INFORMATION: +This product includes software developed by Ben Laurie for use in the +Apache-SSL HTTP server project, software developed by Larry Wall and David +MacKenzie for use in the GNU project of the FSF and software developed by Dr. +Stephen N. Henson as a companion to OpenSSL. + +

+
+

Module Architecture

+The mod_ssl package consists of the SSL module (part 1 in Figure 1) and a set of source patches for Apache adding the +Extended API (EAPI) (part 2 in Figure 1) which is an +essential prerequisite in order to use mod_ssl. In other words: you can only +use the mod_ssl module when Apache's core code contains the Extended API. But +because when applying mod_ssl to the Apache source tree the Extended API is +also automatically added you usually don't have to think about this. It's +mainly important for package vendors who want to build separate packages for +Apache and mod_ssl. For more details on how to apply mod_ssl to the Apache +source tree please follow the INSTALL file in the mod_ssl +distribution. +

+

+ + + +
Figure 1: Module Architecture
+ + +
+ +
+
+
+

Module Building

+The SSL module (mod_ssl) resides under the src/modules/ssl/ +subdirectory inside the Apache source tree and is a regular Apache module. This +means that you can configure, build and install it like any other Apache module. +Usually this is done by using the APACI command +
+
+$ cd apache_1.3.x/
+$ SSL_BASE=/path/to/openssl ./configure ... --enable-module=ssl
+
+
+or by manually editing the SSL_BASE variable, +uncommenting the corresponding AddModule directive inside the +src/Configuration file and using the command +
+
+$ cd apache_1.3.x/src
+$ ./Configure
+
+
+for configuring. Additionally you can enable the Dynamic Shared Object (DSO) +support for mod_ssl by either adding the --enable-shared=ssl +option to the APACI configure command line or by replacing the +
+
+AddModule ssl_module modules/ssl/libssl.a
+
+
+line in src/Configuration with +
+
+SharedModule ssl_module modules/ssl/libssl.so
+
+
+Building mod_ssl as a DSO is especially interesting to achieve more run-time +flexibility, i.e. you can decide whether to use SSL or not at run-time instead +of build-time. But notice that building mod_ssl as a DSO requires that your +OS/compiler supports building DSOs in the first place, and additionally that +they support linking of a DSO against a static library (libssl.a, libcrypo.a). +Not all platform support this. +

+
+ + + + + + + + + + +
+ + + + + +
+previous page
Cover + 		+next page
Introduction +
+
+ + + + +
+ mod_ssl 2.8, User Manual
+ The Apache Interface to OpenSSL + + 		+ Copyright © 1998-2001 + Ralf S. Engelschall
+ All Rights Reserved
+ +
+
+

+
+ + diff --git a/docs/manual/ssl/ssl_reference.html b/docs/manual/ssl/ssl_reference.html new file mode 100644 index 0000000000..f7ecb633ff --- /dev/null +++ b/docs/manual/ssl/ssl_reference.html @@ -0,0 +1,2539 @@ + + +mod_ssl: Reference + + + + + + + + + + +
+ + + + +
+
+ + + + + + + + + + + + + +
+ + + + + +
+ mod_ssl + + Chapter 3 +
+
+ + + + + +
+previous page
Introduction + 		+next page
Compatibility +
+
+
+ Reference +
+
+ + + + + + + +
+ +``Try to understand everything, +but believe nothing!'' + +
+ +Unknown + +
+
+

+ + + + + + +
+T +his chapter provides a reference to all configuration directives and +additional user visible features mod_ssl provides. It's intended as the +official resource when you want to know how a particilar mod_ssl functionality +is actually configured or activated. Each directive is documented similar to +the way standard Apache directives are documented in the official Apache +documentation set, i.e. for each directive especially the syntax, default and +context where applicable is given. +

+Notice that there are three major classes of directives which are used by +mod_ssl: First Global Directives (i.e. directives with context +``server config''), which can occur inside the server config files but only +outside of any sectioning commands like <VirtualHost>. Second +Per-Server Directives (i.e. those with context ``server config, +virtual host''), which can occur inside the server config files both outside +(for the main/default server) and inside <VirtualHost> sections. +

 +   + +
+ + + + + + + +
+ +Table Of Contents + +
+ +Configuration Directives
+        SSLPassPhraseDialog
+        SSLMutex
+        SSLRandomSeed
+        SSLSessionCache
+        SSLSessionCacheTimeout
+        SSLEngine
+        SSLProtocol
+        SSLCipherSuite
+        SSLCertificateFile
+        SSLCertificateKeyFile
+        SSLCertificateChainFile
+        SSLCACertificatePath
+        SSLCACertificateFile
+        SSLCARevocationPath
+        SSLCARevocationFile
+        SSLVerifyClient
+        SSLVerifyDepth
+        SSLLog
+        SSLLogLevel
+        SSLOptions
+        SSLRequireSSL
+        SSLRequire
+Additional Features
+        Environment Variables
+        Custom Log Formats
+ +
+
+
+

+And third Per-Directory Directives (i.e. those with context ``server +config, virtual host, directory, .htaccess''), which can pretty much occur +everywhere. Especially both inside the server config files and the +per-directory .htaccess files. The three classes are subsets of +each other, i.e. directives from the per-directory class can also be used in +the per-server and global context, and directives from the per-server class +can also be used the in the global context. +

+Additional directives and environment variables provided by mod_ssl (via +on-the-fly mapping) for backward compatiblity to other Apache SSL solutions +are documented in the Compatibility chapter. +

Configuration Directives

+The most visible and error-prone things of mod_ssl are its configuration +directives. So we document them in great detail here to assist you in setting +up the best possible configuration of your SSL-aware webserver. + +

+
+ +

SSLPassPhraseDialog

+

+ + + + +
+ + + + +
+ + + + + + + + + + +
+Name: SSLPassPhraseDialog
+Description: Type of pass phrase dialog for encrypted private keys
Syntax: SSLPassPhraseDialog type
Default: SSLPassPhraseDialog builtin
Context: server config
Override: Not applicable
Status: Extension
Module: mod_ssl
Compatibility: mod_ssl 2.1
+
+
+

+When Apache starts up it has to read the various Certificate (see SSLCertificateFile) and Private Key (see SSLCertificateKeyFile) files of the +SSL-enabled virtual servers. Because for security reasons the Private Key +files are usually encrypted, mod_ssl needs to query the administrator for a +Pass Phrase in order to decrypt those files. This query can be done in two ways +which can be configured by type: +

    +
  • builtin +

    + This is the default where an interactive terminal dialog occurs at startup + time just before Apache detaches from the terminal. Here the administrator + has to manually enter the Pass Phrase for each encrypted Private Key file. + Because a lot of SSL-enabled virtual hosts can be configured, the + following reuse-scheme is used to minimize the dialog: When a Private Key + file is encrypted, all known Pass Phrases (at the beginning there are + none, of course) are tried. If one of those known Pass Phrases succeeds no + dialog pops up for this particular Private Key file. If none succeeded, + another Pass Phrase is queried on the terminal and remembered for the next + round (where it perhaps can be reused). +

    + This scheme allows mod_ssl to be maximally flexible (because for N encrypted + Private Key files you can use N different Pass Phrases - but then + you have to enter all of them, of course) while minimizing the terminal + dialog (i.e. when you use a single Pass Phrase for all N Private Key files + this Pass Phrase is queried only once). +

    +

  • exec:/path/to/program +

    + Here an external program is configured which is called at startup for each + encrypted Private Key file. It is called with two arguments (the first is + of the form ``servername:portnumber'', the second is either + ``RSA'' or ``DSA''), which indicate for which + server and algorithm it has to print the corresponding Pass Phrase to + stdout. The intent is that this external program first runs + security checks to make sure that the system is not compromised by an + attacker, and only when these checks were passed successfully it provides + the Pass Phrase. +

    + Both these security checks, and the way the Pass Phrase is determined, can + be as complex as you like. Mod_ssl just defines the interface: an + executable program which provides the Pass Phrase on stdout. + Nothing more or less! So, if you're really paranoid about security, here + is your interface. Anything else has to be left as an exercise to the + administrator, because local security requirements are so different. +

    + The reuse-algorithm above is used here, too. In other words: The external + program is called only once per unique Pass Phrase. +

+

+Example: +

+
+SSLPassPhraseDialog exec:/usr/local/apache/sbin/pp-filter
+
+
+ +

+
+ +

SSLMutex

+

+ + + + +
+ + + + +
+ + + + + + + + + + +
+Name: SSLMutex
+Description: Semaphore for internal mutual exclusion of operations
Syntax: SSLMutex type
Default: SSLMutex none
Context: server config
Override: Not applicable
Status: Extension
Module: mod_ssl
Compatibility: mod_ssl 2.1
+
+
+

+This configures the SSL engine's semaphore (aka. lock) which is used for mutual +exclusion of operations which have to be done in a synchronized way between the +pre-forked Apache server processes. This directive can only be used in the +global server context because it's only useful to have one global mutex. +

+The following Mutex types are available: +

    +
  • none +

    + This is the default where no Mutex is used at all. Use it at your own + risk. But because currently the Mutex is mainly used for synchronizing + write access to the SSL Session Cache you can live without it as long + as you accept a sometimes garbled Session Cache. So it's not recommended + to leave this the default. Instead configure a real Mutex. +

    +

  • file:/path/to/mutex +

    + This is the portable and (under Unix) always provided Mutex variant where + a physical (lock-)file is used as the Mutex. Always use a local disk + filesystem for /path/to/mutex and never a file residing on a + NFS- or AFS-filesystem. Note: Internally, the Process ID (PID) of the + Apache parent process is automatically appended to + /path/to/mutex to make it unique, so you don't have to worry + about conflicts yourself. Notice that this type of mutex is not available + under the Win32 environment. There you have to use the semaphore + mutex. +

    +

  • sem +

    + This is the most elegant but also most non-portable Mutex variant where a + SysV IPC Semaphore (under Unix) and a Windows Mutex (under Win32) is used + when possible. It is only available when the underlying platform + supports it. +

+

+Example: +

+
+SSLMutex file:/usr/local/apache/logs/ssl_mutex
+
+
+ +

+
+ +

SSLRandomSeed

+

+ + + + +
+ + + + +
+ + + + + + + + + + +
+Name: SSLRandomSeed
+Description: Pseudo Random Number Generator (PRNG) seeding source
Syntax: SSLRandomSeed context source [bytes]
Default: none
Context: server config
Override: Not applicable
Status: Extension
Module: mod_ssl
Compatibility: mod_ssl 2.2
+
+
+

+This configures one or more sources for seeding the Pseudo Random Number +Generator (PRNG) in OpenSSL at startup time (context is +startup) and/or just before a new SSL connection is established +(context is connect). This directive can only be used +in the global server context because the PRNG is a global facility. +

+The following source variants are available: +

    +
  • builtin +

    This is the always available builtin seeding source. It's usage + consumes minimum CPU cycles under runtime and hence can be always used + without drawbacks. The source used for seeding the PRNG contains of the + current time, the current process id and (when applicable) a randomly + choosen 1KB extract of the inter-process scoreboard structure of Apache. + The drawback is that this is not really a strong source and at startup + time (where the scoreboard is still not available) this source just + produces a few bytes of entropy. So you should always, at least for the + startup, use an additional seeding source. +

    +

  • file:/path/to/source +

    + This variant uses an external file /path/to/source as the + source for seeding the PRNG. When bytes is specified, only the + first bytes number of bytes of the file form the entropy (and + bytes is given to /path/to/source as the first + argument). When bytes is not specified the whole file forms the + entropy (and 0 is given to /path/to/source as + the first argument). Use this especially at startup time, for instance + with an available /dev/random and/or + /dev/urandom devices (which usually exist on modern Unix + derivates like FreeBSD and Linux). +

    + But be careful: Usually /dev/random provides only as + much entropy data as it actually has, i.e. when you request 512 bytes of + entropy, but the device currently has only 100 bytes available two things + can happen: On some platforms you receive only the 100 bytes while on + other platforms the read blocks until enough bytes are available (which + can take a long time). Here using an existing /dev/urandom is + better, because it never blocks and actually gives the amount of requested + data. The drawback is just that the quality of the received data may not + be the best. +

    + On some platforms like FreeBSD one can even control how the entropy is + actually generated, i.e. by which system interrupts. More details one can + find under rndcontrol(8) on those platforms. Alternatively, when + your system lacks such a random device, you can use tool + like EGD + (Entropy Gathering Daemon) and run it's client program with the + exec:/path/to/program/ variant (see below) or use + egd:/path/to/egd-socket (see below). +

    +

  • exec:/path/to/program +

    + This variant uses an external executable /path/to/program as + the source for seeding the PRNG. When bytes is specified, only the + first bytes number of bytes of its stdout contents + form the entropy. When bytes is not specified, the entirety of + the data produced on stdout form the entropy. Use this only + at startup time when you need a very strong seeding with the help of an + external program (for instance as in the example above with the + truerand utility you can find in the mod_ssl distribution + which is based on the AT&T truerand library). Using this in + the connection context slows down the server too dramatically, of course. + So usually you should avoid using external programs in that context. +

    +

  • egd:/path/to/egd-socket (Unix only) +

    + This variant uses the Unix domain socket of the + external Entropy Gathering Daemon (EGD) (see http://www.lothar.com/tech + /crypto/) to seed the PRNG. Use this if no random device exists + on your platform. +

+

+Example: +

+
+SSLRandomSeed startup builtin
+SSLRandomSeed startup file:/dev/random
+SSLRandomSeed startup file:/dev/urandom 1024
+SSLRandomSeed startup exec:/usr/local/bin/truerand 16
+SSLRandomSeed connect builtin
+SSLRandomSeed connect file:/dev/random
+SSLRandomSeed connect file:/dev/urandom 1024
+
+
+ +

+
+ +

SSLSessionCache

+ + + + +
+ + + + +
+ + + + + + + + + + +
+Name: SSLSessionCache
+Description: Type of the global/inter-process SSL Session Cache
Syntax: SSLSessionCache type
Default: SSLSessionCache none
Context: server config
Override: Not applicable
Status: Extension
Module: mod_ssl
Compatibility: mod_ssl 2.1
+
+
+

+This configures the storage type of the global/inter-process SSL Session +Cache. This cache is an optional facility which speeds up parallel request +processing. For requests to the same server process (via HTTP keep-alive), +OpenSSL already caches the SSL session information locally. But because modern +clients request inlined images and other data via parallel requests (usually +up to four parallel requests are common) those requests are served by +different pre-forked server processes. Here an inter-process cache +helps to avoid unneccessary session handshakes. +

+The following two storage types are currently supported: +

    +
  • none +

    + This is the default and just disables the global/inter-process Session + Cache. There is no drawback in functionality, but a noticeable speed + penalty can be observed. +

    +

  • dbm:/path/to/datafile +

    + This makes use of a DBM hashfile on the local disk to synchronize the + local OpenSSL memory caches of the server processes. The slight increase + in I/O on the server results in a visible request speedup for your + clients, so this type of storage is generally recommended. +

    +

  • shm:/path/to/datafile[(size)] +

    + This makes use of a high-performance hash table (approx. size bytes + in size) inside a shared memory segment in RAM (established via + /path/to/datafile) to synchronize the local OpenSSL memory + caches of the server processes. This storage type is not available on all + platforms. See the mod_ssl INSTALL document for details on + how to build Apache+EAPI with shared memory support. +

+

+Examples: +

+
+SSLSessionCache dbm:/usr/local/apache/logs/ssl_gcache_data
+SSLSessionCache shm:/usr/local/apache/logs/ssl_gcache_data(512000)
+
+
+ +

+
+ +

SSLSessionCacheTimeout

+ + + + +
+ + + + +
+ + + + + + + + + + +
+Name: SSLSessionCacheTimeout
+Description: Number of seconds before an SSL session expires in the Session Cache
Syntax: SSLSessionCacheTimeout seconds
Default: SSLSessionCacheTimeout 300
Context: server config, virtual host
Override: Not applicable
Status: Extension
Module: mod_ssl
Compatibility: mod_ssl 2.0
+
+
+

+This directive sets the timeout in seconds for the information stored in the +global/inter-process SSL Session Cache and the OpenSSL internal memory cache. +It can be set as low as 15 for testing, but should be set to higher +values like 300 in real life. +

+Example: +

+
+SSLSessionCacheTimeout 600
+
+
+ +

+
+ +

SSLEngine

+ + + + +
+ + + + +
+ + + + + + + + + + +
+Name: SSLEngine
+Description: SSL Engine Operation Switch
Syntax: SSLEngine on|off
Default: SSLEngine off
Context: server config, virtual host
Override: Not applicable
Status: Extension
Module: mod_ssl
Compatibility: mod_ssl 2.1
+
+
+

+This directive toggles the usage of the SSL/TLS Protocol Engine. This is +usually used inside a <VirtualHost> section to enable SSL/TLS for a +particular virtual host. By default the SSL/TLS Protocol Engine is disabled +for both the main server and all configured virtual hosts. +

+Example: +

+
+<VirtualHost _default_:443>
+SSLEngine on
+...
+</VirtualHost>
+
+
+ +

+
+ +

SSLProtocol

+ + + + +
+ + + + +
+ + + + + + + + + + +
+Name: SSLProtocol
+Description: Configure usable SSL protocol flavors
Syntax: SSLProtocol [+-]protocol ...
Default: SSLProtocol all
Context: server config, virtual host
Override: Options
Status: Extension
Module: mod_ssl
Compatibility: mod_ssl 2.2
+
+
+

+This directive can be used to control the SSL protocol flavors mod_ssl should +use when establishing its server environment. Clients then can only connect +with one of the provided protocols. +

+The available (case-insensitive) protocols are: +

    +
  • SSLv2 +

    + This is the Secure Sockets Layer (SSL) protocol, version 2.0. It is the + original SSL protocol as designed by Netscape Corporation. +

    +

  • SSLv3 +

    + This is the Secure Sockets Layer (SSL) protocol, version 3.0. It is the + successor to SSLv2 and the currently (as of February 1999) de-facto + standardized SSL protocol from Netscape Corporation. It's supported by + almost all popular browsers. +

    +

  • TLSv1 +

    + This is the Transport Layer Security (TLS) protocol, version 1.0. It is the + successor to SSLv3 and currently (as of February 1999) still under + construction by the Internet Engineering Task Force (IETF). It's still + not supported by any popular browsers. +

    +

  • All +

    + This is a shortcut for ``+SSLv2 +SSLv3 +TLSv1'' and a + convinient way for enabling all protocols except one when used in + combination with the minus sign on a protocol as the example above shows. +

+

+Example: +

+
+#   enable SSLv3 and TLSv1, but not SSLv2
+SSLProtocol all -SSLv2
+
+
+ +

+
+ +

SSLCipherSuite

+ + + + +
+ + + + +
+ + + + + + + + + + +
+Name: SSLCipherSuite
+Description: Cipher Suite available for negotiation in SSL handshake
Syntax: SSLCipherSuite cipher-spec
Default: SSLCipherSuite ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP
Context: server config, virtual host, directory, .htaccess
Override: AuthConfig
Status: Extension
Module: mod_ssl
Compatibility: mod_ssl 2.1
+
+
+

+This complex directive uses a colon-separated cipher-spec string +consisting of OpenSSL cipher specifications to configure the Cipher Suite the +client is permitted to negotiate in the SSL handshake phase. Notice that this +directive can be used both in per-server and per-directory context. In +per-server context it applies to the standard SSL handshake when a connection +is established. In per-directory context it forces a SSL renegotation with the +reconfigured Cipher Suite after the HTTP request was read but before the HTTP +response is sent. +

+An SSL cipher specification in cipher-spec is composed of 4 major +attributes plus a few extra minor ones: +

    +
  • Key Exchange Algorithm:
    + RSA or Diffie-Hellman variants. +

    +

  • Authentication Algorithm:
    + RSA, Diffie-Hellman, DSS or none. +

    +

  • Cipher/Encryption Algorithm:
    + DES, Triple-DES, RC4, RC2, IDEA or none. +

    +

  • MAC Digest Algorithm:
    + MD5, SHA or SHA1. +
+An SSL cipher can also be an export cipher and is either a SSLv2 or SSLv3/TLSv1 +cipher (here TLSv1 is equivalent to SSLv3). To specify which ciphers to use, +one can either specify all the Ciphers, one at a time, or use aliases to +specify the preference and order for the ciphers (see Table +1). +

+

+ + + +
Table 1: OpenSSL Cipher Specification Tags
+ + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Tag Description
Key Exchange Algorithm:
kRSA RSA key exchange
kDHr Diffie-Hellman key exchange with RSA key
kDHd Diffie-Hellman key exchange with DSA key
kEDH Ephemeral (temp.key) Diffie-Hellman key exchange (no cert)
Authentication Algorithm:
aNULL No authentication
aRSA RSA authentication
aDSS DSS authentication
aDH Diffie-Hellman authentication
Cipher Encoding Algorithm:
eNULL No encoding
DES DES encoding
3DES Triple-DES encoding
RC4 RC4 encoding
RC2 RC2 encoding
IDEA IDEA encoding
MAC Digest Algorithm:
MD5 MD5 hash function
SHA1 SHA1 hash function
SHA SHA hash function
Aliases:
SSLv2 all SSL version 2.0 ciphers
SSLv3 all SSL version 3.0 ciphers
TLSv1 all TLS version 1.0 ciphers
EXP all export ciphers
EXPORT40 all 40-bit export ciphers only
EXPORT56 all 56-bit export ciphers only
LOW all low strength ciphers (no export, single DES)
MEDIUM all ciphers with 128 bit encryption
HIGH all ciphers using Triple-DES
RSA all ciphers using RSA key exchange
DH all ciphers using Diffie-Hellman key exchange
EDH all ciphers using Ephemeral Diffie-Hellman key exchange
ADH all ciphers using Anonymous Diffie-Hellman key exchange
DSS all ciphers using DSS authentication
NULL all ciphers using no encryption
+
+
+
+

+Now where this becomes interesting is that these can be put together +to specify the order and ciphers you wish to use. To speed this up +there are also aliases (SSLv2, SSLv3, TLSv1, EXP, LOW, MEDIUM, +HIGH) for certain groups of ciphers. These tags can be joined +together with prefixes to form the cipher-spec. Available +prefixes are: +

    +
  • none: add cipher to list +
  • +: add ciphers to list and pull them to current location in list +
  • -: remove cipher from list (can be added later again) +
  • !: kill cipher from list completely (can not be added later again) +
+A simpler way to look at all of this is to use the ``openssl ciphers +-v'' command which provides a nice way to successively create the +correct cipher-spec string. The default cipher-spec string +is ``ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP'' which +means the following: first, remove from consideration any ciphers that do not +authenticate, i.e. for SSL only the Anonymous Diffie-Hellman ciphers. Next, +use ciphers using RC4 and RSA. Next include the high, medium and then the low +security ciphers. Finally pull all SSLv2 and export ciphers to the +end of the list. +
+
+$ openssl ciphers -v 'ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP'
+NULL-SHA                SSLv3 Kx=RSA      Au=RSA  Enc=None      Mac=SHA1
+NULL-MD5                SSLv3 Kx=RSA      Au=RSA  Enc=None      Mac=MD5
+EDH-RSA-DES-CBC3-SHA    SSLv3 Kx=DH       Au=RSA  Enc=3DES(168) Mac=SHA1
+...                     ...               ...     ...           ...
+EXP-RC4-MD5             SSLv3 Kx=RSA(512) Au=RSA  Enc=RC4(40)   Mac=MD5  export
+EXP-RC2-CBC-MD5         SSLv2 Kx=RSA(512) Au=RSA  Enc=RC2(40)   Mac=MD5  export
+EXP-RC4-MD5             SSLv2 Kx=RSA(512) Au=RSA  Enc=RC4(40)   Mac=MD5  export
+
+
+The complete list of particular RSA & DH ciphers for SSL is given in Table 2. +

+Example: +

+
+SSLCipherSuite RSA:!EXP:!NULL:+HIGH:+MEDIUM:-LOW
+
+
+

+

+ + + +
Table 2: Particular SSL Ciphers
+ + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Cipher-Tag Protocol Key Ex. Auth. Enc. MAC Type
RSA Ciphers:
DES-CBC3-SHA SSLv3 RSA RSA 3DES(168) SHA1  
DES-CBC3-MD5 SSLv2 RSA RSA 3DES(168) MD5  
IDEA-CBC-SHA SSLv3 RSA RSA IDEA(128) SHA1  
RC4-SHA SSLv3 RSA RSA RC4(128) SHA1  
RC4-MD5 SSLv3 RSA RSA RC4(128) MD5  
IDEA-CBC-MD5 SSLv2 RSA RSA IDEA(128) MD5  
RC2-CBC-MD5 SSLv2 RSA RSA RC2(128) MD5  
RC4-MD5 SSLv2 RSA RSA RC4(128) MD5  
DES-CBC-SHA SSLv3 RSA RSA DES(56) SHA1  
RC4-64-MD5 SSLv2 RSA RSA RC4(64) MD5  
DES-CBC-MD5 SSLv2 RSA RSA DES(56) MD5  
EXP-DES-CBC-SHA SSLv3 RSA(512) RSA DES(40) SHA1 export
EXP-RC2-CBC-MD5 SSLv3 RSA(512) RSA RC2(40) MD5 export
EXP-RC4-MD5 SSLv3 RSA(512) RSA RC4(40) MD5 export
EXP-RC2-CBC-MD5 SSLv2 RSA(512) RSA RC2(40) MD5 export
EXP-RC4-MD5 SSLv2 RSA(512) RSA RC4(40) MD5 export
NULL-SHA SSLv3 RSA RSA None SHA1  
NULL-MD5 SSLv3 RSA RSA None MD5  
Diffie-Hellman Ciphers:
ADH-DES-CBC3-SHA SSLv3 DH None 3DES(168) SHA1  
ADH-DES-CBC-SHA SSLv3 DH None DES(56) SHA1  
ADH-RC4-MD5 SSLv3 DH None RC4(128) MD5  
EDH-RSA-DES-CBC3-SHA SSLv3 DH RSA 3DES(168) SHA1  
EDH-DSS-DES-CBC3-SHA SSLv3 DH DSS 3DES(168) SHA1  
EDH-RSA-DES-CBC-SHA SSLv3 DH RSA DES(56) SHA1  
EDH-DSS-DES-CBC-SHA SSLv3 DH DSS DES(56) SHA1  
EXP-EDH-RSA-DES-CBC-SHA SSLv3 DH(512) RSA DES(40) SHA1 export
EXP-EDH-DSS-DES-CBC-SHA SSLv3 DH(512) DSS DES(40) SHA1 export
EXP-ADH-DES-CBC-SHA SSLv3 DH(512) None DES(40) SHA1 export
EXP-ADH-RC4-MD5 SSLv3 DH(512) None RC4(40) MD5 export
+
+
+
+ +

+
+ +

SSLCertificateFile

+ + + + +
+ + + + +
+ + + + + + + + + + +
+Name: SSLCertificateFile
+Description: Server PEM-encoded X.509 Certificate file
Syntax: SSLCertificateFile filename
Default: None
Context: server config, virtual host
Override: Not applicable
Status: Extension
Module: mod_ssl
Compatibility: mod_ssl 2.0
+
+
+

+This directive points to the PEM-encoded Certificate file for the server and +optionally also to the corresponding RSA or DSA Private Key file for it +(contained in the same file). If the contained Private Key is encrypted the +Pass Phrase dialog is forced at startup time. This directive can be used up to +two times (referencing different filenames) when both a RSA and a DSA based +server certificate is used in parallel. +

+Example: +

+
+SSLCertificateFile /usr/local/apache/conf/ssl.crt/server.crt
+
+
+ +

+
+ +

SSLCertificateKeyFile

+ + + + +
+ + + + +
+ + + + + + + + + + +
+Name: SSLCertificateKeyFile
+Description: Server PEM-encoded Private Key file
Syntax: SSLCertificateKeyFile filename
Default: None
Context: server config, virtual host
Override: Not applicable
Status: Extension
Module: mod_ssl
Compatibility: mod_ssl 2.0
+
+
+

+This directive points to the PEM-encoded Private Key file for the server. If +the Private Key is not combined with the Certificate in the +SSLCertificateFile, use this additional directive to point to the +file with the stand-alone Private Key. When SSLCertificateFile +is used and the file contains both the Certificate and the Private Key this +directive need not be used. But we strongly discourage this practice. +Instead we recommend you to separate the Certificate and the Private Key. If +the contained Private Key is encrypted, the Pass Phrase dialog is forced at +startup time. This directive can be used up to two times (referencing +different filenames) when both a RSA and a DSA based private key is used in +parallel. +

+Example: +

+
+SSLCertificateKeyFile /usr/local/apache/conf/ssl.key/server.key
+
+
+ +

+
+ +

SSLCertificateChainFile

+ + + + +
+ + + + +
+ + + + + + + + + + +
+Name: SSLCertificateChainFile
+Description: File of PEM-encoded Server CA Certificates
Syntax: SSLCertificateChainFile filename
Default: None
Context: server config, virtual host
Override: Not applicable
Status: Extension
Module: mod_ssl
Compatibility: mod_ssl 2.3.6
+
+
+

+This directive sets the optional all-in-one file where you can +assemble the certificates of Certification Authorities (CA) which form the +certificate chain of the server certificate. This starts with the issuing CA +certificate of of the server certificate and can range up to the root CA +certificate. Such a file is simply the concatenation of the various +PEM-encoded CA Certificate files, usually in certificate chain order. +

+This should be used alternatively and/or additionally to SSLCACertificatePath for explicitly +constructing the server certificate chain which is sent to the browser in +addition to the server certificate. It is especially useful to avoid conflicts +with CA certificates when using client authentication. Because although +placing a CA certificate of the server certificate chain into SSLCACertificatePath has the same effect for +the certificate chain construction, it has the side-effect that client +certificates issued by this same CA certificate are also accepted on client +authentication. That's usually not one expect. +

+But be careful: Providing the certificate chain works only if you are using a +single (either RSA or DSA) based server certificate. If you are +using a coupled RSA+DSA certificate pair, this will work only if actually both +certificates use the same certificate chain. Else the browsers will be +confused in this situation. +

+Example: +

+
+SSLCertificateChainFile /usr/local/apache/conf/ssl.crt/ca.crt
+
+
+ +

+
+ +

SSLCACertificatePath

+ + + + +
+ + + + +
+ + + + + + + + + + +
+Name: SSLCACertificatePath
+Description: Directory of PEM-encoded CA Certificates for Client Auth.
Syntax: SSLCACertificatePath directory
Default: None
Context: server config, virtual host
Override: Not applicable
Status: Extension
Module: mod_ssl
Compatibility: mod_ssl 2.0
+
+
+

+This directive sets the directory where you keep the Certificates of +Certification Authorities (CAs) whose clients you deal with. These are used to +verify the client certificate on Client Authentication. +

+The files in this directory have to be PEM-encoded and are accessed through +hash filenames. So usually you can't just place the Certificate files +there: you also have to create symbolic links named +hash-value.N. And you should always make sure this directory +contains the appropriate symbolic links. Use the Makefile which +comes with mod_ssl to accomplish this task. +

+Example: +

+
+SSLCACertificatePath /usr/local/apache/conf/ssl.crt/
+
+
+ +

+
+ +

SSLCACertificateFile

+ + + + +
+ + + + +
+ + + + + + + + + + +
+Name: SSLCACertificateFile
+Description: File of concatenated PEM-encoded CA Certificates for Client Auth.
Syntax: SSLCACertificateFile filename
Default: None
Context: server config, virtual host
Override: Not applicable
Status: Extension
Module: mod_ssl
Compatibility: mod_ssl 2.0
+
+
+

+This directive sets the all-in-one file where you can assemble the +Certificates of Certification Authorities (CA) whose clients you deal +with. These are used for Client Authentication. Such a file is simply the +concatenation of the various PEM-encoded Certificate files, in order of +preference. This can be used alternatively and/or additionally to SSLCACertificatePath. +

+Example: +

+
+SSLCACertificateFile /usr/local/apache/conf/ssl.crt/ca-bundle-client.crt
+
+
+ +

+
+ +

SSLCARevocationPath

+ + + + +
+ + + + +
+ + + + + + + + + + +
+Name: SSLCARevocationPath
+Description: Directory of PEM-encoded CA CRLs for Client Auth.
Syntax: SSLCARevocationPath directory
Default: None
Context: server config, virtual host
Override: Not applicable
Status: Extension
Module: mod_ssl
Compatibility: mod_ssl 2.3
+
+
+

+This directive sets the directory where you keep the Certificate Revocation +Lists (CRL) of Certification Authorities (CAs) whose clients you deal with. +These are used to revoke the client certificate on Client Authentication. +

+The files in this directory have to be PEM-encoded and are accessed through +hash filenames. So usually you have not only to place the CRL files there. +Additionally you have to create symbolic links named +hash-value.rN. And you should always make sure this directory +contains the appropriate symbolic links. Use the Makefile which +comes with mod_ssl to accomplish this task. +

+Example: +

+
+SSLCARevocationPath /usr/local/apache/conf/ssl.crl/
+
+
+ +

+
+ +

SSLCARevocationFile

+ + + + +
+ + + + +
+ + + + + + + + + + +
+Name: SSLCARevocationFile
+Description: File of concatenated PEM-encoded CA CRLs for Client Auth.
Syntax: SSLCARevocationFile filename
Default: None
Context: server config, virtual host
Override: Not applicable
Status: Extension
Module: mod_ssl
Compatibility: mod_ssl 2.3
+
+
+

+This directive sets the all-in-one file where you can assemble the +Certificate Revocation Lists (CRL) of Certification Authorities (CA) whose +clients you deal with. These are used for Client Authentication. +Such a file is simply the concatenation of the various PEM-encoded CRL +files, in order of preference. This can be used alternatively and/or +additionally to SSLCARevocationPath. +

+Example: +

+
+SSLCARevocationFile /usr/local/apache/conf/ssl.crl/ca-bundle-client.crl
+
+
+ +

+
+ +

SSLVerifyClient

+ + + + +
+ + + + +
+ + + + + + + + + + +
+Name: SSLVerifyClient
+Description: Type of Client Certificate verification
Syntax: SSLVerifyClient level
Default: SSLVerifyClient none
Context: server config, virtual host, directory, .htaccess
Override: AuthConfig
Status: Extension
Module: mod_ssl
Compatibility: mod_ssl 2.0
+
+
+

+This directive sets the Certificate verification level for the Client +Authentication. Notice that this directive can be used both in per-server and +per-directory context. In per-server context it applies to the client +authentication process used in the standard SSL handshake when a connection is +established. In per-directory context it forces a SSL renegotation with the +reconfigured client verification level after the HTTP request was read but +before the HTTP response is sent. +

+The following levels are available for level: +

    +
  • none: + no client Certificate is required at all +
  • optional: + the client may present a valid Certificate +
  • require: + the client has to present a valid Certificate +
  • optional_no_ca: + the client may present a valid Certificate
    + but it need not to be (successfully) verifiable. +
+In practice only levels none and require are +really interesting, because level optional doesn't work with +all browsers and level optional_no_ca is actually against the +idea of authentication (but can be used to establish SSL test pages, etc.) +

+Example: +

+
+SSLVerifyClient require
+
+
+ +

+
+ +

SSLVerifyDepth

+ + + + +
+ + + + +
+ + + + + + + + + + +
+Name: SSLVerifyDepth
+Description: Maximum depth of CA Certificates in Client Certificate verification
Syntax: SSLVerifyDepth number
Default: SSLVerifyDepth 1
Context: server config, virtual host, directory, .htaccess
Override: AuthConfig
Status: Extension
Module: mod_ssl
Compatibility: mod_ssl 2.0
+
+
+

+This directive sets how deeply mod_ssl should verify before deciding that the +clients don't have a valid certificate. Notice that this directive can be +used both in per-server and per-directory context. In per-server context it +applies to the client authentication process used in the standard SSL +handshake when a connection is established. In per-directory context it forces +a SSL renegotation with the reconfigured client verification depth after the +HTTP request was read but before the HTTP response is sent. +

+The depth actually is the maximum number of intermediate certificate issuers, +i.e. the number of CA certificates which are max allowed to be followed while +verifying the client certificate. A depth of 0 means that self-signed client +certificates are accepted only, the default depth of 1 means the client +certificate can be self-signed or has to be signed by a CA which is directly +known to the server (i.e. the CA's certificate is under +SSLCACertificatePath), etc. +

+Example: +

+
+SSLVerifyDepth 10
+
+
+ +

+
+ +

SSLLog

+ + + + +
+ + + + +
+ + + + + + + + + + +
+Name: SSLLog
+Description: Where to write the dedicated SSL engine logfile
Syntax: SSLLog filename
Default: None
Context: server config, virtual host
Override: Not applicable
Status: Extension
Module: mod_ssl
Compatibility: mod_ssl 2.1
+
+
+

+This directive sets the name of the dedicated SSL protocol engine logfile. +Error type messages are additionally duplicated to the general Apache error +log file (directive ErrorLog). Put this somewhere where it cannot +be used for symlink attacks on a real server (i.e. somewhere where only root +can write). If the filename does not begin with a slash +('/') then it is assumed to be relative to the Server +Root. If filename begins with a bar ('|') then the +following string is assumed to be a path to an executable program to which a +reliable pipe can be established. The directive should occur only once per +virtual server config. +

+Example: +

+
+SSLLog /usr/local/apache/logs/ssl_engine_log
+
+
+ +

+
+ +

SSLLogLevel

+ + + + +
+ + + + +
+ + + + + + + + + + +
+Name: SSLLogLevel
+Description: Logging level for the dedicated SSL engine logfile
Syntax: SSLLogLevel level
Default: SSLLogLevel none
Context: server config, virtual host
Override: Not applicable
Status: Extension
Module: mod_ssl
Compatibility: mod_ssl 2.1
+
+
+

+This directive sets the verbosity degree of the dedicated SSL protocol engine +logfile. The level is one of the following (in ascending order where +higher levels include lower levels): +

    +
  • none
    + no dedicated SSL logging is done, but messages of level + ``error'' are still written to the general Apache error + logfile. +

    +

  • error
    + log messages of error type only, i.e. messages which show fatal situations + (processing is stopped). Those messages are also duplicated to the + general Apache error logfile. +

    +

  • warn
    + log also warning messages, i.e. messages which show non-fatal problems + (processing is continued). +

    +

  • info
    + log also informational messages, i.e. messages which show major + processing steps. +

    +

  • trace
    + log also trace messages, i.e. messages which show minor processing steps. +

    +

  • debug
    + log also debugging messages, i.e. messages which show development and + low-level I/O information. +
+

+Example: +

+
+SSLLogLevel warn
+
+
+ +

+
+ +

SSLOptions

+ + + + +
+ + + + +
+ + + + + + + + + + +
+Name: SSLOptions
+Description: Configure various SSL engine run-time options
Syntax: SSLOptions [+-]option ...
Default: None
Context: server config, virtual host, directory, .htaccess
Override: Options
Status: Extension
Module: mod_ssl
Compatibility: mod_ssl 2.1
+
+
+

+This directive can be used to control various run-time options on a +per-directory basis. Normally, if multiple SSLOptions could +apply to a directory, then the most specific one is taken completely; the +options are not merged. However if all the options on the +SSLOptions directive are preceded by a plus (+) or +minus (-) symbol, the options are merged. Any options preceded by +a + are added to the options currently in force, and any options +preceded by a - are removed from the options currently in force. +

+The available options are: +

    +
  • StdEnvVars +

    + When this option is enabled, the standard set of SSL related CGI/SSI + environment variables are created. This per default is disabled for + performance reasons, because the information extraction step is a + rather expensive operation. So one usually enables this option for + CGI and SSI requests only. +

    +

  • CompatEnvVars +

    + When this option is enabled, additional CGI/SSI environment variables are + created for backward compatibility to other Apache SSL solutions. Look in + the Compatibility chapter for details + on the particular variables generated. +

    +

  • ExportCertData +

    + When this option is enabled, additional CGI/SSI environment variables are + created: SSL_SERVER_CERT, SSL_CLIENT_CERT and + SSL_CLIENT_CERT_CHAINn (with n = 0,1,2,..). + These contain the PEM-encoded X.509 Certificates of server and client for + the current HTTPS connection and can be used by CGI scripts for deeper + Certificate checking. Additionally all other certificates of the client + certificate chain are provided, too. This bloats up the environment a + little bit which is why you have to use this option to enable it on + demand. +

    +

  • FakeBasicAuth +

    + When this option is enabled, the Subject Distinguished Name (DN) of the + Client X509 Certificate is translated into a HTTP Basic Authorization + username. This means that the standard Apache authentication methods can + be used for access control. The user name is just the Subject of the + Client's X509 Certificate (can be determined by running OpenSSL's + openssl x509 command: openssl x509 -noout -subject -in + certificate.crt). Note that no password is + obtained from the user. Every entry in the user file needs this password: + ``xxj31ZMTZzkVA'', which is the DES-encrypted version of the + word `password''. Those who live under MD5-based encryption + (for instance under FreeBSD or BSD/OS, etc.) should use the following MD5 + hash of the same word: ``$1$OXLyS...$Owx8s2/m9/gfkcRVXzgoE/''. +

    +

  • StrictRequire +

    + This forces forbidden access when SSLRequireSSL or + SSLRequire successfully decided that access should be + forbidden. Usually the default is that in the case where a ``Satisfy + any'' directive is used, and other access restrictions are passed, + denial of access due to SSLRequireSSL or + SSLRequire is overridden (because that's how the Apache + Satisfy mechanism should work.) But for strict access restriction + you can use SSLRequireSSL and/or SSLRequire in + combination with an ``SSLOptions +StrictRequire''. Then an + additional ``Satisfy Any'' has no chance once mod_ssl has + decided to deny access. +

    +

  • OptRenegotiate +

    + This enables optimized SSL connection renegotiation handling when SSL + directives are used in per-directory context. By default a strict + scheme is enabled where every per-directory reconfiguration of + SSL parameters causes a full SSL renegotiation handshake. When this + option is used mod_ssl tries to avoid unnecessary handshakes by doing more + granular (but still safe) parameter checks. Nevertheless these granular + checks sometimes maybe not what the user expects, so enable this on a + per-directory basis only, please. +

+

+Example: +

+
+SSLOptions +FakeBasicAuth -StrictRequire
+<Files ~ "\.(cgi|shtml)$">
+    SSLOptions +StdEnvVars +CompatEnvVars -ExportCertData
+<Files>
+
+
+ +

+
+ +

SSLRequireSSL

+ + + + +
+ + + + +
+ + + + + + + + + + +
+Name: SSLRequireSSL
+Description: Deny access when SSL is not used for the HTTP request
Syntax: SSLRequireSSL
Default: None
Context: directory, .htaccess
Override: AuthConfig
Status: Extension
Module: mod_ssl
Compatibility: mod_ssl 2.0
+
+
+

+This directive forbids access unless HTTP over SSL (i.e. HTTPS) is enabled for +the current connection. This is very handy inside the SSL-enabled virtual +host or directories for defending against configuration errors that expose +stuff that should be protected. When this directive is present all requests +are denied which are not using SSL. +

+Example: +

+
+SSLRequireSSL
+
+
+ +

+
+ +

SSLRequire

+ + + + +
+ + + + +
+ + + + + + + + + + +
+Name: SSLRequire
+Description: Allow access only when an arbitrarily complex boolean expression is true
Syntax: SSLRequire expression
Default: None
Context: directory, .htaccess
Override: AuthConfig
Status: Extension
Module: mod_ssl
Compatibility: mod_ssl 2.1
+
+
+

+This directive specifies a general access requirement which has to be +fulfilled in order to allow access. It's a very powerful directive because the +requirement specification is an arbitrarily complex boolean expression +containing any number of access checks. +

+The expression must match the following syntax (given as a BNF +grammar notation): +

+
+expr     ::= "true" | "false"
+           | "!" expr
+           | expr "&&" expr
+           | expr "||" expr
+           | "(" expr ")"
+           | comp
+
+comp     ::= word "==" word | word "eq" word
+           | word "!=" word | word "ne" word
+           | word "<"  word | word "lt" word
+           | word "<=" word | word "le" word
+           | word ">"  word | word "gt" word
+           | word ">=" word | word "ge" word
+           | word "in" "{" wordlist "}"
+           | word "=~" regex
+           | word "!~" regex
+
+wordlist ::= word
+           | wordlist "," word
+
+word     ::= digit
+           | cstring
+           | variable
+           | function
+
+digit    ::= [0-9]+
+cstring  ::= "..."
+variable ::= "%{" varname "}"
+function ::= funcname "(" funcargs ")"
+
+
+while for varname any variable from Table 3 +can be used. Finally for funcname the following functions +are available: +
    +
  • file(filename) +

    + This function takes one string argument and expands to the contents of the + file. This is especially useful for matching this contents against a + regular expression, etc. +

+Notice that expression is first parsed into an internal machine +representation and then evaluated in a second step. Actually, in Global and +Per-Server Class context expression is parsed at startup time and +at runtime only the machine representation is executed. For Per-Directory +context this is different: here expression has to be parsed and +immediately executed for every request. +

+Example: +

+
+SSLRequire (    %{SSL_CIPHER} !~ m/^(EXP|NULL)-/ \
+            and %{SSL_CLIENT_S_DN_O} eq "Snake Oil, Ltd." \
+            and %{SSL_CLIENT_S_DN_OU} in {"Staff", "CA", "Dev"} \
+            and %{TIME_WDAY} >= 1 and %{TIME_WDAY} <= 5 \
+            and %{TIME_HOUR} >= 8 and %{TIME_HOUR} <= 20       ) \
+           or %{REMOTE_ADDR} =~ m/^192\.76\.162\.[0-9]+$/
+
+
+
+ + + +
Table 3: Available Variables for SSLRequire
+ + +
+
+Standard CGI/1.0 and Apache variables: +
+HTTP_USER_AGENT        PATH_INFO             AUTH_TYPE
+HTTP_REFERER           QUERY_STRING          SERVER_SOFTWARE
+HTTP_COOKIE            REMOTE_HOST           API_VERSION
+HTTP_FORWARDED         REMOTE_IDENT          TIME_YEAR
+HTTP_HOST              IS_SUBREQ             TIME_MON
+HTTP_PROXY_CONNECTION  DOCUMENT_ROOT         TIME_DAY
+HTTP_ACCEPT            SERVER_ADMIN          TIME_HOUR
+HTTP:headername        SERVER_NAME           TIME_MIN
+THE_REQUEST            SERVER_PORT           TIME_SEC
+REQUEST_METHOD         SERVER_PROTOCOL       TIME_WDAY
+REQUEST_SCHEME         REMOTE_ADDR           TIME
+REQUEST_URI            REMOTE_USER           ENV:variablename
+REQUEST_FILENAME
+
+SSL-related variables: +
+HTTPS                  SSL_CLIENT_M_VERSION   SSL_SERVER_M_VERSION
+                       SSL_CLIENT_M_SERIAL    SSL_SERVER_M_SERIAL
+SSL_PROTOCOL           SSL_CLIENT_V_START     SSL_SERVER_V_START
+SSL_SESSION_ID         SSL_CLIENT_V_END       SSL_SERVER_V_END
+SSL_CIPHER             SSL_CLIENT_S_DN        SSL_SERVER_S_DN
+SSL_CIPHER_EXPORT      SSL_CLIENT_S_DN_C      SSL_SERVER_S_DN_C
+SSL_CIPHER_ALGKEYSIZE  SSL_CLIENT_S_DN_ST     SSL_SERVER_S_DN_ST
+SSL_CIPHER_USEKEYSIZE  SSL_CLIENT_S_DN_L      SSL_SERVER_S_DN_L
+SSL_VERSION_LIBRARY    SSL_CLIENT_S_DN_O      SSL_SERVER_S_DN_O
+SSL_VERSION_INTERFACE  SSL_CLIENT_S_DN_OU     SSL_SERVER_S_DN_OU
+                       SSL_CLIENT_S_DN_CN     SSL_SERVER_S_DN_CN
+                       SSL_CLIENT_S_DN_T      SSL_SERVER_S_DN_T
+                       SSL_CLIENT_S_DN_I      SSL_SERVER_S_DN_I
+                       SSL_CLIENT_S_DN_G      SSL_SERVER_S_DN_G
+                       SSL_CLIENT_S_DN_S      SSL_SERVER_S_DN_S
+                       SSL_CLIENT_S_DN_D      SSL_SERVER_S_DN_D
+                       SSL_CLIENT_S_DN_UID    SSL_SERVER_S_DN_UID
+                       SSL_CLIENT_S_DN_Email  SSL_SERVER_S_DN_Email
+                       SSL_CLIENT_I_DN        SSL_SERVER_I_DN
+                       SSL_CLIENT_I_DN_C      SSL_SERVER_I_DN_C
+                       SSL_CLIENT_I_DN_ST     SSL_SERVER_I_DN_ST
+                       SSL_CLIENT_I_DN_L      SSL_SERVER_I_DN_L
+                       SSL_CLIENT_I_DN_O      SSL_SERVER_I_DN_O
+                       SSL_CLIENT_I_DN_OU     SSL_SERVER_I_DN_OU
+                       SSL_CLIENT_I_DN_CN     SSL_SERVER_I_DN_CN
+                       SSL_CLIENT_I_DN_T      SSL_SERVER_I_DN_T
+                       SSL_CLIENT_I_DN_I      SSL_SERVER_I_DN_I
+                       SSL_CLIENT_I_DN_G      SSL_SERVER_I_DN_G
+                       SSL_CLIENT_I_DN_S      SSL_SERVER_I_DN_S
+                       SSL_CLIENT_I_DN_D      SSL_SERVER_I_DN_D
+                       SSL_CLIENT_I_DN_UID    SSL_SERVER_I_DN_UID
+                       SSL_CLIENT_I_DN_Email  SSL_SERVER_I_DN_Email
+                       SSL_CLIENT_A_SIG       SSL_SERVER_A_SIG
+                       SSL_CLIENT_A_KEY       SSL_SERVER_A_KEY
+                       SSL_CLIENT_CERT        SSL_SERVER_CERT
+                       SSL_CLIENT_CERT_CHAINn
+                       SSL_CLIENT_VERIFY
+
+
+
+
+
+
+
+

+

Additional Features

+

Environment Variables

+This module provides a lot of SSL information as additional environment +variables to the SSI and CGI namespace. The generated variables are listed in +Table 4. For backward compatibility the information can +be made available under different names, too. Look in the Compatibility chapter for details on the +compatibility variables. +

+

+ + + +
Table 4: SSI/CGI Environment Variables
+ + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Variable Name:Value Type:Description:
HTTPS flag HTTPS is being used.
SSL_PROTOCOL string The SSL protocol version (SSLv2, SSLv3, TLSv1)
SSL_SESSION_ID string The hex-encoded SSL session id
SSL_CIPHER string The cipher specification name
SSL_CIPHER_EXPORT string true if cipher is an export cipher
SSL_CIPHER_USEKEYSIZE number Number of cipher bits (actually used)
SSL_CIPHER_ALGKEYSIZE number Number of cipher bits (possible)
SSL_VERSION_INTERFACE string The mod_ssl program version
SSL_VERSION_LIBRARY string The OpenSSL program version
SSL_CLIENT_M_VERSION string The version of the client certificate
SSL_CLIENT_M_SERIAL string The serial of the client certificate
SSL_CLIENT_S_DN string Subject DN in client's certificate
SSL_CLIENT_S_DN_x509 string Component of client's Subject DN
SSL_CLIENT_I_DN string Issuer DN of client's certificate
SSL_CLIENT_I_DN_x509 string Component of client's Issuer DN
SSL_CLIENT_V_START string Validity of client's certificate (start time)
SSL_CLIENT_V_END string Validity of client's certificate (end time)
SSL_CLIENT_A_SIG string Algorithm used for the signature of client's certificate
SSL_CLIENT_A_KEY string Algorithm used for the public key of client's certificate
SSL_CLIENT_CERT string PEM-encoded client certificate
SSL_CLIENT_CERT_CHAINn string PEM-encoded certificates in client certificate chain
SSL_CLIENT_VERIFY string NONE, SUCCESS, GENEROUS or FAILED:reason
SSL_SERVER_M_VERSION string The version of the server certificate
SSL_SERVER_M_SERIAL string The serial of the server certificate
SSL_SERVER_S_DN string Subject DN in server's certificate
SSL_SERVER_S_DN_x509 string Component of server's Subject DN
SSL_SERVER_I_DN string Issuer DN of server's certificate
SSL_SERVER_I_DN_x509 string Component of server's Issuer DN
SSL_SERVER_V_START string Validity of server's certificate (start time)
SSL_SERVER_V_END string Validity of server's certificate (end time)
SSL_SERVER_A_SIG string Algorithm used for the signature of server's certificate
SSL_SERVER_A_KEY string Algorithm used for the public key of server's certificate
SSL_SERVER_CERT string PEM-encoded server certificate
+[ where x509 is a component of a X.509 DN: + C,ST,L,O,OU,CN,T,I,G,S,D,UID,Email ] +
+
+
+

+
+

Custom Log Formats

+When mod_ssl is built into Apache or at least loaded (under DSO situation) +additional functions exist for the Custom Log Format of mod_log_config. First there is an additional +``%{varname}x'' eXtension format function +which can be used to expand any variables provided by any module, especially +those provided by mod_ssl which can you find in Table 4. +

+For backward compatibility there is additionally a special +``%{name}c'' cryptography format function +provided. Information about this function is provided in the Compatibility chapter. +

+Example: +

+
+CustomLog logs/ssl_request_log \
+          "%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b"
+
+
+

+
+ + + + + + + + + + +
+ + + + + +
+previous page
Introduction + 		+next page
Compatibility +
+
+ + + + +
+ mod_ssl 2.8, User Manual
+ The Apache Interface to OpenSSL + + 		+ Copyright © 1998-2001 + Ralf S. Engelschall
+ All Rights Reserved
+ +
+
+

+
+ +