SSL/TLS Strong Encryption: How-To

Available Languages: en | + fr

+ + +

This document is intended to get you started, and get a few things +working. You are strongly encouraged to read the rest of the SSL +documentation, and arrive at a deeper understanding of the material, +before progressing to the advanced techniques.

Basic Configuration Example
Cipher Suites and Enforcing Strong Security
OCSP Stapling
Client Authentication and Access Control
Logging

Basic Configuration Example

+ + +

Your SSL configuration will need to contain, at minimum, the +following directives.

+ +

LoadModule ssl_module modules/mod_ssl.so
+
+Listen 443
+<VirtualHost *:443>
+    ServerName www.example.com
+    SSLEngine on
+    SSLCertificateFile "/path/to/www.example.com.cert"
+    SSLCertificateKeyFile "/path/to/www.example.com.key"
+</VirtualHost>

+ + +

Cipher Suites and Enforcing Strong Security

+ +

How can I create an SSL server which accepts strong encryption only?
How can I create an SSL server which accepts all types of ciphers in general, but +requires a strong cipher for access to a particular URL?

+ +

How can I create an SSL server which accepts strong encryption +only?

+ +

The following enables only the strongest ciphers:

SSLCipherSuite HIGH:!aNULL:!MD5

+ + +

While with the following configuration you specify a preference + for specific speed-optimized ciphers (which will be selected by + mod_ssl, provided that they are supported by the client):

+ +

SSLCipherSuite RC4-SHA:AES128-SHA:HIGH:!aNULL:!MD5
+SSLHonorCipherOrder on

+ + + +

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, a server-wide SSLCipherSuite which restricts + ciphers to the strong variants, isn't the answer here. However, + mod_ssl can be reconfigured within Location + blocks, to give a per-directory solution, and can automatically force + a renegotiation of the SSL parameters to meet the new configuration. + This can be done as follows:

# be liberal in general
+SSLCipherSuite ALL:!aNULL:RC4+RSA:+HIGH:+MEDIUM:+LOW:+EXP:+eNULL
+
+<Location "/strong/area">
+# but https://hostname/strong/area/ and below
+# requires strong ciphers
+SSLCipherSuite HIGH:!aNULL:!MD5
+</Location>

+ + +

OCSP Stapling

+ + +

The Online Certificate Status Protocol (OCSP) is a mechanism for +determining whether or not a server certificate has been revoked, and OCSP +Stapling is a special form of this in which the server, such as httpd and +mod_ssl, maintains current OCSP responses for its certificates and sends +them to clients which communicate with the server. Most certificates +contain the address of an OCSP responder maintained by the issuing +Certificate Authority, and mod_ssl can communicate with that responder to +obtain a signed response that can be sent to clients communicating with +the server.

+ +

Because the client can obtain the certificate revocation status from +the server, without requiring an extra connection from the client to the +Certificate Authority, OCSP Stapling is the preferred way for the +revocation status to be obtained. Other benefits of eliminating the +communication between clients and the Certificate Authority are that the +client browsing history is not exposed to the Certificate Authority and +obtaining status is more reliable by not depending on potentially heavily +loaded Certificate Authority servers.

+ +

Because the response obtained by the server can be reused for all clients +using the same certificate during the time that the response is valid, the +overhead for the server is minimal.

+ +

Once general SSL support has been configured properly, enabling OCSP +Stapling generally requires only very minor modifications to the httpd +configuration — the addition of these two directives:

+ +

SSLUseStapling On
+SSLStaplingCache "shmcb:logs/ssl_stapling(32768)"

+ + +

These directives are placed at global scope (i.e., not within a virtual +host definition) wherever other global SSL configuration directives are +placed, such as in conf/extra/httpd-ssl.conf for normal +open source builds of httpd, /etc/apache2/mods-enabled/ssl.conf +for the Ubuntu or Debian-bundled httpd, etc.

+ +

The path on the SSLStaplingCache directive +(e.g., logs/) should match the one on the +SSLSessionCache directive. This path is relative +to ServerRoot.

+ +

This particular SSLStaplingCache directive requires +mod_socache_shmcb (from the shmcb prefix on the +directive's argument). This module is usually enabled already for +SSLSessionCache or on behalf of some module other than +mod_ssl. If you enabled an SSL session cache using a +mechanism other than mod_socache_shmcb, use that alternative +mechanism for SSLStaplingCache as well. For example:

+ +

SSLSessionCache "dbm:logs/ssl_scache"
+SSLStaplingCache "dbm:logs/ssl_stapling"

+ + +

You can use the openssl command-line program to verify that an OCSP response +is sent by your server:

+ +

$ openssl s_client -connect www.example.com:443 -status -servername www.example.com
+...
+OCSP response: 
+======================================
+OCSP Response Data:
+    OCSP Response Status: successful (0x0)
+    Response Type: Basic OCSP Response
+...
+    Cert Status: Good
+...

+ +

The following sections highlight the most common situations which require +further modification to the configuration. Refer also to the +mod_ssl reference manual.

+ +

If more than a few SSL certificates are used for the server

+ +

OCSP responses are stored in the SSL stapling cache. While the responses +are typically a few hundred to a few thousand bytes in size, mod_ssl +supports OCSP responses up to around 10K bytes in size. With more than a +few certificates, the stapling cache size (32768 bytes in the example above) +may need to be increased. Error message AH01929 will be logged in case of +an error storing a response.

+ + +

If the certificate does not point to an OCSP responder, or if a +different address must be used

+ +

Refer to the +SSLStaplingForceURL directive.

+ +

You can confirm that a server certificate points to an OCSP responder +using the openssl command-line program, as follows:

+ +

$ openssl x509 -in ./www.example.com.crt -text | grep 'OCSP.*http'
+OCSP - URI:http://ocsp.example.com

+ +

If the OCSP URI is provided and the web server can communicate to it +directly without using a proxy, no configuration is required. Note that +firewall rules that control outbound connections from the web server may +need to be adjusted.

+ +

If no OCSP URI is provided, contact your Certificate Authority to +determine if one is available; if so, configure it with +SSLStaplingForceURL in the virtual +host that uses the certificate.

+ + +

If multiple SSL-enabled virtual hosts are configured and OCSP +Stapling should be disabled for some

+ + +

Add SSLUseStapling Off to the virtual hosts for which OCSP +Stapling should be disabled.

+ + +

If the OCSP responder is slow or unreliable

+ +

Several directives are available to handle timeouts and errors. Refer +to the documentation for the +SSLStaplingFakeTryLater, +SSLStaplingResponderTimeout, and +SSLStaplingReturnResponderErrors +directives.

+ + +

If mod_ssl logs error AH02217

+ +

AH02217: ssl_stapling_init_cert: Can't retrieve issuer certificate!

In order to support OCSP Stapling when a particular server certificate is +used, the certificate chain for that certificate must be configured. If it +was not configured as part of enabling SSL, the AH02217 error will be issued +when stapling is enabled, and an OCSP response will not be provided for clients +using the certificate.

+ +

Refer to the SSLCertificateChainFile +and SSLCertificateFile for instructions +for configuring the certificate chain.

+ + +

Client Authentication and Access Control

+ +

How can I force clients to authenticate using certificates?
How can I force clients to authenticate using certificates for a + particular URL, but still allow arbitrary clients to access the rest of the server?
How can I allow only clients who have certificates to access a + particular URL, but allow all clients to access the rest of the server?
How can I require HTTPS with strong ciphers, and either +basic authentication or client certificates, for access to part of the +Intranet website, for clients coming from the Internet?

+ +

How can I force clients to authenticate using certificates?

+ + +

When you know all of your users (eg, as is often the case on a corporate + Intranet), you can require plain certificate authentication. All you + need to do is to create client certificates signed by your own CA + certificate (ca.crt) and then verify 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 force clients to authenticate using certificates for a + particular URL, but still allow arbitrary clients to access the rest of the server?

+ + +

To force clients to authenticate using certificates for a particular URL, + you can use the per-directory reconfiguration features of + mod_ssl:

+ +

SSLVerifyClient none
+SSLCACertificateFile "conf/ssl.crt/ca.crt"
+
+<Location "/secure/area">
+SSLVerifyClient require
+SSLVerifyDepth 1
+</Location>

+ + + +

How can I allow only clients who have certificates to access a + particular URL, but allow all clients to access the rest of the server?

+ + +

The key to doing this is checking that part of the client certificate + matches what you expect. Usually this means checking all or part of the + Distinguished Name (DN), to see if it contains some known string. + There are two ways to do this, using either mod_auth_basic or + SSLRequire.

+ +

The mod_auth_basic method is generally required when + the certificates are completely arbitrary, or when their DNs have + no common fields (usually the organisation, etc.). In this case, + you should establish a password database containing all + clients allowed, as follows:

+ +

SSLVerifyClient      none
+SSLCACertificateFile "conf/ssl.crt/ca.crt"
+SSLCACertificatePath "conf/ssl.crt"
+
+<Directory "/usr/local/apache2/htdocs/secure/area">
+    SSLVerifyClient      require
+    SSLVerifyDepth       5
+    SSLOptions           +FakeBasicAuth
+    SSLRequireSSL
+    AuthName             "Snake Oil Authentication"
+    AuthType             Basic
+    AuthBasicProvider    file
+    AuthUserFile         "/usr/local/apache2/conf/httpd.passwd"
+    Require              valid-user
+</Directory>

+ + +

The password used in this example is the DES encrypted string "password". + See the SSLOptions docs for more + information.

+ +

httpd.passwd

/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

+ +

When your clients are all part of a common hierarchy, which is encoded + into the DN, you can match them more easily using SSLRequire, as follows:

+ + +

SSLVerifyClient      none
+SSLCACertificateFile "conf/ssl.crt/ca.crt"
+SSLCACertificatePath "conf/ssl.crt"
+
+<Directory "/usr/local/apache2/htdocs/secure/area">
+  SSLVerifyClient      require
+  SSLVerifyDepth       5
+  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 part of the +Intranet website, for clients coming from the Internet? I still want to allow +plain HTTP access for clients on the Intranet.

+ + +

These examples presume that clients on the Intranet have IPs in the range + 192.168.1.0/24, and that the part of the Intranet website you want to allow + internet access to is /usr/local/apache2/htdocs/subarea. + This configuration should remain outside of your HTTPS virtual host, so + that it applies to both HTTPS and HTTP.

+ +

SSLCACertificateFile "conf/ssl.crt/company-ca.crt"
+
+<Directory "/usr/local/apache2/htdocs">
+    #   Outside the subarea only Intranet access is granted
+    Require              ip 192.168.1.0/24
+</Directory>
+
+<Directory "/usr/local/apache2/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
+    Require              ip 192.168.1.0/24
+    
+    #   HTTP Basic Authentication
+    AuthType             basic
+    AuthName             "Protected Intranet Area"
+    AuthBasicProvider    file
+    AuthUserFile         "conf/protected.passwd"
+    Require              valid-user
+</Directory>

+ + +

Logging

+ + +

mod_ssl can log extremely verbose debugging information + to the error log, when its LogLevel is + set to the higher trace levels. On the other hand, on a very busy server, + level info may already be too much. Remember that you can + configure the LogLevel per module to + suite your needs.

SSL/TLS Strong Encryption: How-To

See also

Basic Configuration Example

Cipher Suites and Enforcing Strong Security

How can I create an SSL server which accepts strong encryption +only?

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?

OCSP Stapling

If more than a few SSL certificates are used for the server

If the certificate does not point to an OCSP responder, or if a +different address must be used

If multiple SSL-enabled virtual hosts are configured and OCSP +Stapling should be disabled for some

If the OCSP responder is slow or unreliable

If mod_ssl logs error AH02217

Client Authentication and Access Control

How can I force clients to authenticate using certificates?

How can I force clients to authenticate using certificates for a + particular URL, but still allow arbitrary clients to access the rest of the server?

How can I allow only clients who have certificates to access a + particular URL, but allow all clients to access the rest of the server?

httpd.passwd

How can I require HTTPS with strong ciphers, and either basic +authentication or client certificates, for access to part of the +Intranet website, for clients coming from the Internet? I still want to allow +plain HTTP access for clients on the Intranet.

Logging

Comments