Commit 9dc6f9b3 authored by Rainer Jung's avatar Rainer Jung
Browse files

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

docs/manual/mod/mod_ssl.xml

+40 −22
Original line number Diff line number Diff line
@@ -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>

docs/manual/ssl/ssl_faq.xml

+8 −6
Original line number Diff line number Diff line
@@ -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>