Try to clarify extended uses of SSLCertificateFile.

Backport of r1682923 and r1682937 from trunk,
resp. r1682929 and r1682939 from 2.4.x.

git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/branches/2.2.x@1682942 13f79535-47bb-0310-9956-ffa450edef68

diff --git a/docs/manual/mod/mod_ssl.xml b/docs/manual/mod/mod_ssl.xml
index dfbc0941e093003db2504c406e8b8503307dd375..cb4af664d47a30ee1a6e70d4a570a1d0c8b86e1c 100644 (file)
--- a/docs/manual/mod/mod_ssl.xml
+++ b/docs/manual/mod/mod_ssl.xml
@@ -776,18 +776,32 @@ SSLCipherSuite RSA:!EXP:!NULL:+HIGH:+MEDIUM:-LOW
 
 <usage>
 <p>
-This directive points to the file with the PEM-encoded certificate,
-optionally also the corresponding private key, and - beginning with
-version 2.2.30 - DH parameters and/or an EC curve name
-for ephemeral keys (as generated by <code>openssl dhparam</code>
-and <code>openssl ecparam</code>, respectively). If the private key
-is encrypted, the pass phrase dialog is forced at startup time.
+This directive points to a file with certificate data in PEM format.
+At a minimum, the file must include an end-entity (leaf) certificate.
+The directive can be used up to three times (referencing different filenames)
+when an RSA, a DSA, and an ECC based server certificate is used in parallel.
 </p>
+
 <p>
-This directive can be used up to three times (referencing different filenames)
-when both an RSA, a DSA, and an ECC based server certificate is used in
-parallel. Note that DH and ECDH parameters are only read from the first
-<directive>SSLCertificateFile</directive> directive.</p>
+Custom DH parameters and an EC curve name for ephemeral keys,
+can be added to end of the first file configured using
+<directive module="mod_ssl">SSLCertificateFile</directive>.
+This is supported in version 2.2.30 or later.
+Such parameters can be generated using the commands
+<code>openssl dhparam</code> and <code>openssl ecparam</code>.
+The parameters can be added as-is to the end of the first
+certificate file. Only the first file can be used for custom
+parameters, as they are applied independently of the authentication
+algorithm type.
+</p>
+
+<p>
+Finally the the end-entity certificate's private key can also be
+added to the certificate file instead of using a separate
+<directive module="mod_ssl">SSLCertificateKeyFile</directive>
+directive. This practice is highly discouraged. If the private
+key is encrypted, the pass phrase dialog is forced at startup time.
+</p>
 
 <note>
 <title>DH parameter interoperability with primes > 1024 bit</title>
@@ -820,18 +834,22 @@ SSLCertificateFile /usr/local/apache2/conf/ssl.crt/server.crt
 
 <usage>
 <p>
-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
-<directive>SSLCertificateFile</directive>, use this additional directive to
-point to the file with the stand-alone Private Key. When
-<directive>SSLCertificateFile</directive> 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 three times
-(referencing different filenames) when both a RSA, a DSA, and an ECC based
-private key is used in parallel.</p>
+This directive points to the PEM-encoded private key file for the
+server. If the contained private key is encrypted, the pass phrase
+dialog is forced at startup time.</p>
+
+<p>
+The directive can be used up to three times (referencing different filenames)
+when an RSA, a DSA, and an ECC based private key is used in parallel. For each
+<directive module="mod_ssl">SSLCertificateKeyFile</directive>
+directive, there must be a matching <directive>SSLCertificateFile</directive>
+directive.</p>
+
+<p>
+The private key may also be combined with the certificate in the file given by
+<directive module="mod_ssl">SSLCertificateFile</directive>, but this practice
+is highly discouraged.</p>
+
 <example><title>Example</title>
 SSLCertificateKeyFile /usr/local/apache2/conf/ssl.key/server.key
 </example>

diff --git a/docs/manual/ssl/ssl_faq.xml b/docs/manual/ssl/ssl_faq.xml
index 3a98b4a538287d59ce6b352266b95cd627a37e95..dd10dcbd19d8ce675f31d6181b2f727733269719 100644 (file)
--- a/docs/manual/ssl/ssl_faq.xml
+++ b/docs/manual/ssl/ssl_faq.xml
@@ -946,20 +946,22 @@ HTTPS to an Apache+mod_ssl server with Netscape Navigator?</title>
     or higher), you can either rearrange mod_ssl's cipher list with
     <directive module="mod_ssl">SSLCipherSuite</directive>
     (possibly in conjunction with <directive module="mod_ssl">SSLHonorCipherOrder</directive>),
-    or you can use the <directive module="mod_ssl">SSLCertificateFile</directive>
-    directive to configure custom DH parameters with a 1024-bit prime, which
+    or you can use custom DH parameters with a 1024-bit prime, which
     will always have precedence over any of the built-in DH parameters.</p>
 
-    <p>To generate custom DH parameters, use the <code>openssl dhparam</code>
-    command. Alternatively, you can append the following standard 1024-bit DH
+    <p>To generate custom DH parameters, use the <code>openssl dhparam 1024</code>
+    command. Alternatively, you can use the following standard 1024-bit DH
     parameters from <a href="http://www.ietf.org/rfc/rfc2409.txt">RFC 2409</a>,
-    section 6.2 to the respective
-    <directive module="ssl">SSLCertificateFile</directive> file:</p>
+    section 6.2:</p>
     <example><pre>-----BEGIN DH PARAMETERS-----
 MIGHAoGBAP//////////yQ/aoiFowjTExmKLgNwc0SkCTgiKZ8x0Agu+pjsTmyJR
 Sgh5jjQE3e+VGbPNOkMbMCsKbfJfFDdP4TVtbVHCReSFtXZiXn7G9ExC6aY37WsL
 /1y29Aa37e44a/taiZ+lrp8kEXxLH+ZJKGZR7OZTgf//////////AgEC
 -----END DH PARAMETERS-----</pre></example>
+    <p>Add the custom parameters including the "BEGIN DH PARAMETERS" and
+    "END DH PARAMETERS" lines to the end of the first certificate file
+    you have configured using the
+    <directive module="mod_ssl">SSLCertificateFile</directive> directive.</p>
 </section>
 
 </section>