From: Rainer Jung Date: Mon, 1 Jun 2015 15:15:06 +0000 (+0000) Subject: Try to clarify extended uses of SSLCertificateFile. X-Git-Tag: 2.4.13~14 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=9da49151a777935796f9ee112c05f1614748df8b;p=apache Try to clarify extended uses of SSLCertificateFile. Backport of r1682923 from trunk. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/branches/2.4.x@1682929 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/mod/mod_ssl.xml b/docs/manual/mod/mod_ssl.xml index d7efa06923..07a3459581 100644 --- a/docs/manual/mod/mod_ssl.xml +++ b/docs/manual/mod/mod_ssl.xml @@ -822,35 +822,44 @@ SSLCipherSuite RSA:!EXP:!NULL:+HIGH:+MEDIUM:-LOW

This directive points to a file with certificate data in PEM format. At a minimum, the file must include an end-entity (leaf) certificate. -Beginning with version 2.4.8, it may also include intermediate CA -certificates, sorted from leaf to root, and obsoletes -SSLCertificateChainFile. +The directive can be used multiple times (referencing different filenames) +to support multiple algorithms for server authentication - typically +RSA, DSA, and ECC. The number of supported algorithms depends on the +OpenSSL version being used for mod_ssl: with version 1.0.0 or later, +openssl list-public-key-algorithms will output a list +of supported algorithms.

-Additional optional elements are DH parameters and/or an EC curve name -for ephemeral keys, as generated by openssl dhparam and -openssl ecparam, respectively (supported in version 2.4.7 -or later) and finally, the end-entity certificate's private key. -If the private key is encrypted, the pass phrase dialog is forced -at startup time.

+The files may also include intermediate CA certificates, sorted from +leaf to root. This is supported with version 2.4.8 and later, +and obsoletes SSLCertificateChainFile. +When running with OpenSSL 1.0.2 or later, this allows +to configure the intermediate CA chain on a per-certificate basis. +

-This directive can be used multiple times (referencing different filenames) -to support multiple algorithms for server authentication - typically -RSA, DSA, and ECC. The number of supported algorithms depends on the -OpenSSL version being used for mod_ssl: with version 1.0.0 or later, -openssl list-public-key-algorithms will output a list -of supported algorithms.

+Custom DH parameters and an EC curve name for ephemeral keys, +can also be added to end of the first file configured using +SSLCertificateChainFile. +This is supported in version 2.4.7 or later. +Such parameters can be generated using the commands +openssl dhparam and openssl ecparam. +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. +

-When running with OpenSSL 1.0.2 or later, this directive allows -to configure the intermediate CA chain on a per-certificate basis, -which removes a limitation of the (now obsolete) -SSLCertificateChainFile directive. -DH and ECDH parameters, however, are only read from the first -SSLCertificateFile directive, as they -are applied independently of the authentication algorithm type.

+Finally the the end-entity certificate's private key can also be +added to the certificate file instead of using a separate +SSLCertificateKeyFile +directive. This practice is highly discouraged. If it is used, +the certificate files using such an embedded key must be configured +after the certificates using a separate key file. If the private +key is encrypted, the pass phrase dialog is forced at startup time. +

DH parameter interoperability with primes > 1024 bit @@ -886,9 +895,7 @@ SSLCertificateFile "/usr/local/apache2/conf/ssl.crt/server.crt"

This directive points to the PEM-encoded private key file for the -server (the private key may also be combined with the certificate in the -SSLCertificateFile, but this practice -is discouraged). If the contained private key is encrypted, the pass phrase +server. If the contained private key is encrypted, the pass phrase dialog is forced at startup time.

@@ -898,6 +905,13 @@ to support multiple algorithms for server authentication. For each directive, there must be a matching SSLCertificateFile directive.

+

+The private key may also be combined with the certificate in the file given by +SSLCertificateFile, but this practice +is highly discouraged. If it is used, the certificate files using such +an embedded key must be configured after the certificates using a separate +key file.

+ Example SSLCertificateKeyFile "/usr/local/apache2/conf/ssl.key/server.key" diff --git a/docs/manual/ssl/ssl_faq.xml b/docs/manual/ssl/ssl_faq.xml index 58e0b88bf5..0b6d8d82aa 100644 --- a/docs/manual/ssl/ssl_faq.xml +++ b/docs/manual/ssl/ssl_faq.xml @@ -758,20 +758,22 @@ SetEnvIf User-Agent "MSIE [2-5]" \ or higher), you can either rearrange mod_ssl's cipher list with SSLCipherSuite (possibly in conjunction with SSLHonorCipherOrder), - or you can use the SSLCertificateFile - 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.

-

To generate custom DH parameters, use the openssl dhparam - command. Alternatively, you can append the following standard 1024-bit DH +

To generate custom DH parameters, use the openssl dhparam 1024 + command. Alternatively, you can use the following standard 1024-bit DH parameters from RFC 2409, - section 6.2 to the respective - SSLCertificateFile file:

+ section 6.2:

-----BEGIN DH PARAMETERS-----
 MIGHAoGBAP//////////yQ/aoiFowjTExmKLgNwc0SkCTgiKZ8x0Agu+pjsTmyJR
 Sgh5jjQE3e+VGbPNOkMbMCsKbfJfFDdP4TVtbVHCReSFtXZiXn7G9ExC6aY37WsL
 /1y29Aa37e44a/taiZ+lrp8kEXxLH+ZJKGZR7OZTgf//////////AgEC
 -----END DH PARAMETERS-----
 +

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 + SSLCertificateFile directive.