From: Rainer Jung Date: Mon, 1 Jun 2015 15:00:13 +0000 (+0000) Subject: Try to clarify extended uses of SSLCertificateFile. X-Git-Tag: 2.5.0-alpha~3115 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=f9125046b60e979afe28fb1975b50a6666717bc9;p=apache Try to clarify extended uses of SSLCertificateFile. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1682923 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/mod/mod_ssl.xml b/docs/manual/mod/mod_ssl.xml index 851aa1b1f5..e492bcfd2e 100644 --- a/docs/manual/mod/mod_ssl.xml +++ b/docs/manual/mod/mod_ssl.xml @@ -817,35 +817,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 @@ -881,9 +890,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.

@@ -893,6 +900,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 4e9ccc195f..c9dc24b8eb 100644 --- a/docs/manual/ssl/ssl_faq.xml +++ b/docs/manual/ssl/ssl_faq.xml @@ -757,20 +757,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.