From 192e4100ed4cc4a6a61a9ad50ffe9f085622bad1 Mon Sep 17 00:00:00 2001 From: Joshua Slive Date: Wed, 17 Apr 2002 21:20:25 +0000 Subject: [PATCH] Removing old WML stuff from the ssl directory. These files are now just plain old html. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@94684 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/ssl/ssl_compat.wml | 257 ----- docs/manual/ssl/ssl_cover.wml | 66 -- docs/manual/ssl/ssl_faq.wml | 1272 ----------------------- docs/manual/ssl/ssl_glossary.wml | 152 --- docs/manual/ssl/ssl_howto.wml | 325 ------ docs/manual/ssl/ssl_intro.wml | 644 ------------ docs/manual/ssl/ssl_overview.wml | 197 ---- docs/manual/ssl/ssl_reference.wml | 1580 ----------------------------- 8 files changed, 4493 deletions(-) delete mode 100644 docs/manual/ssl/ssl_compat.wml delete mode 100644 docs/manual/ssl/ssl_cover.wml delete mode 100644 docs/manual/ssl/ssl_faq.wml delete mode 100644 docs/manual/ssl/ssl_glossary.wml delete mode 100644 docs/manual/ssl/ssl_howto.wml delete mode 100644 docs/manual/ssl/ssl_intro.wml delete mode 100644 docs/manual/ssl/ssl_overview.wml delete mode 100644 docs/manual/ssl/ssl_reference.wml diff --git a/docs/manual/ssl/ssl_compat.wml b/docs/manual/ssl/ssl_compat.wml deleted file mode 100644 index e73c61ee78..0000000000 --- a/docs/manual/ssl/ssl_compat.wml +++ /dev/null @@ -1,257 +0,0 @@ - -#use "ssl_template.inc" title="Compatibility" tag=compat num=4 - - - - -#use wml::std::toc style=nbsp - - -All PCs are compatible. But some of -them are more compatible than others. - - -

- - - - - - -
- -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 - -
- - - -
-
- -
- -

-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. - -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
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. - -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
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. - -

- - - - - - - - - - - - -
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)
- - diff --git a/docs/manual/ssl/ssl_cover.wml b/docs/manual/ssl/ssl_cover.wml deleted file mode 100644 index 812d582319..0000000000 --- a/docs/manual/ssl/ssl_cover.wml +++ /dev/null @@ -1,66 +0,0 @@ -#!wml -o index.html - -#use "ssl_template.inc" title="Title Page" tag=title num=0 - -
- - - - - - - - - - -
- - - - - - - -
- User Manual -
- mod_ssl version 2.8    -
-
-
- mod_ssl - The Apache Interface to OpenSSL -
- - - - - - - -
- Ralf S. Engelschall
- rse@engelschall.com
- www.engelschall.com
- 		-      - -
Overview - 		- -
-
- diff --git a/docs/manual/ssl/ssl_faq.wml b/docs/manual/ssl/ssl_faq.wml deleted file mode 100644 index 0b0b2e3b84..0000000000 --- a/docs/manual/ssl/ssl_faq.wml +++ /dev/null @@ -1,1272 +0,0 @@ - -#use "ssl_template.inc" title="F.A.Q." tag=faq num=6 - - - - -#use wml::std::toc style=nbsp - - -``The wise man doesn't give the right answers, -he poses the right questions.'' - - -

- - - - - - -
- -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 - -
- - - -
-
- -
- -# container tag for layouting a question - - - - -

-

  • - - %body\ -    - [L] -

    - - - - - -

    About the module

    - -
      - - -What is the history of mod_ssl? - - - 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? - - - 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? - - - 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? - - - 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? - - - 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? - - - First, let us explain what Wassenaar and its 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? - - - 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? - - - 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? - - - 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? - - - 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? - - - 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? - - - 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". - - - 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? - - - 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? - - - 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? - - - While you usually just use -

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

      - for simple testing the HTTP protocol of Apache, it's not so 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? - - - 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? - - - 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? - - - 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? - - - 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? - - - 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? - - - 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? - - - 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? - - - 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)? - - - 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? - - - 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? - - - 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? - - - 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? - - - 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? - - - 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? - - - 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? - - - 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? - - - 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? - - - 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? - - - 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? - - - 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? - - - 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? - - - 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? - - - 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? - - - 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? - - - 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? - - - 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? - - - 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? - - - 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? - - - 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? - - -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? - - -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? - - -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? - - - 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? - - -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. -
      - -
    - diff --git a/docs/manual/ssl/ssl_glossary.wml b/docs/manual/ssl/ssl_glossary.wml deleted file mode 100644 index d29b8d0b49..0000000000 --- a/docs/manual/ssl/ssl_glossary.wml +++ /dev/null @@ -1,152 +0,0 @@ - -#use "ssl_template.inc" title="Glossary" tag=gloss num=7 - - - - -``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.'' - - -
    - -
    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. -
    - diff --git a/docs/manual/ssl/ssl_howto.wml b/docs/manual/ssl/ssl_howto.wml deleted file mode 100644 index 0ce6dfcc76..0000000000 --- a/docs/manual/ssl/ssl_howto.wml +++ /dev/null @@ -1,325 +0,0 @@ - -#use "ssl_template.inc" title="HowTo" tag=howto num=5 - - - - -#use wml::std::toc style=nbsp - - -``The solution of this problem is trivial - and is left as an exercise for the reader.'' - - -

    - - - - - - -
    - -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 its restrictions and -coherences. - - -   - - -
    - - - - - - - -
    - -Table Of Contents - -
    - - - -
    -
    - -
    - -# container tag for layouting a question - - - - -

    -

  • - - %body\ -    - [L] -

    - - - - - - - -" "" > -" - bdwidth=1 bdcolor="#cccccc" bgcolor="#ffffff" fgcolor="#000000"> -

    -%body
-
    -\ - - - -

    Cipher Suites and Enforced Strong Security

    - -
      - - -How can I create a real SSLv2-only server? - - -The following creates an SSL server which speaks only the SSLv2 protocol and -its ciphers. - -

      - -SSLProtocol -all +SSLv2 -SSLCipherSuite SSLv2:+HIGH:+MEDIUM:+LOW:+EXP - - - -How can I create an SSL server which accepts strong encryption only? - - -The following enables only the seven strongest ciphers: - -

      - -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? - - -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 its 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: - -

      - -\# 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? - - -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: - -

      - -\# 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? - - -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. - -

      - -\# 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? - - -For this we again use the per-directory reconfiguration feature of mod_ssl: - -

      - -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? - - -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: - -

      - -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> - - -

      - -/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: - -

      - -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? - - -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): - -

      - -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> - - -

    - diff --git a/docs/manual/ssl/ssl_intro.wml b/docs/manual/ssl/ssl_intro.wml deleted file mode 100644 index 2d943826a6..0000000000 --- a/docs/manual/ssl/ssl_intro.wml +++ /dev/null @@ -1,644 +0,0 @@ - -#use "ssl_template.inc" title="Introduction" tag=intro num=2 - - - - -#use wml::std::toc style=nbsp - - -``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.'' - - -

    - - - - - - -
    - -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

    - -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. - -

    - - - - - - - - - - - - -
    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). - -

    - - - - - - - - - - - - - - - - - -
    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. - -

    - -
    -
    ------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. - -

    - - - - - - - - - - - - - - - - - - - - - - - - - -
    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). - -

    - - - - -

    -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. - -

    - - - - -

    -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). - -

    - - - - -

    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

    - - - diff --git a/docs/manual/ssl/ssl_overview.wml b/docs/manual/ssl/ssl_overview.wml deleted file mode 100644 index 4180ddb055..0000000000 --- a/docs/manual/ssl/ssl_overview.wml +++ /dev/null @@ -1,197 +0,0 @@ - -#use "ssl_template.inc" title="Preface" tag=over num=1 - - - - - -``Ralf Engelschall has released an -excellent module that integrates -Apache and SSLeay.'' - - -

    - - - - - - -
    - -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. - -

    - - - - -

    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. - diff --git a/docs/manual/ssl/ssl_reference.wml b/docs/manual/ssl/ssl_reference.wml deleted file mode 100644 index 1c49d178b9..0000000000 --- a/docs/manual/ssl/ssl_reference.wml +++ /dev/null @@ -1,1580 +0,0 @@ - -#use "ssl_template.inc" title="Reference" tag=ref num=3 - - - - -#use wml::std::toc style=nbsp -#use wml::std::grid - - -``Try to understand everything, -but believe nothing!'' - - -

    - - - - - - -
    - -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 - -
    - - - -
    -
    - -
    - -

    -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

    - -

    - - -

    -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

    - -

    - - -

    -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

    - -

    - - -

    -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. Its 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 its 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

    - - - -

    -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

    - - - -

    -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

    - - - -

    -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

    - - - -

    -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 all 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

    - - - -

    -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). - -

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    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: -

    -
    -#   allow only strongest RSA ciphers
-SSLCipherSuite RSA:!EXP:!NULL:+HIGH:+MEDIUM:-LOW
-
    -
    - -

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    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

    - - - -

    -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

    - - - -

    -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

    - - - -

    -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

    - - - -

    -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

    - - - -

    -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

    - - - -

    -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

    - - - -

    -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

    - - - -

    -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

    - - - -

    -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

    - - - -

    -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

    - - - -

    -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

    - - - -

    -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

    - - - -

    -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

    - - - -

    -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]+$/
-
    -
    - - -
    -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. - -

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    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"
-
    -
    - -- 2.40.0