You are viewing a plain text version of this content. The canonical link for it is here.

Posted to wiki-changes@httpd.apache.org by Apache Wiki <wi...@apache.org> on 2010/03/17 22:24:03 UTC

[Httpd Wiki] Update of "SettingUpModSSL" by thumbs

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Httpd Wiki" for change notification.

The "SettingUpModSSL" page has been changed by thumbs.
http://wiki.apache.org/httpd/SettingUpModSSL

--------------------------------------------------

New page:
Apache httpd with SSL (https, Secure Socket Layer)

This howto explains how to setup Apache httpd with ssl (https) for use with shopping carts, payment gateways or other secure systems.
Applicable to Centos Versions:

* Centos 5.x

Requirements
Explanation of requirements.

1. Root access or appropriate sudo privileges on the system.
2. Registered domain and access to dns/hosting settings.
3. Properly configured and working httpd setup.

Doing the Work

Basic description of what will be done and what is expected.

1. Install httpd and openssl and generate key file for your new ssl certificate. While you can generate a non-encrypted key, the point here is security, so we'll be generating an encrypted key. Both the private key and the certificate are required to enable SSL:

yum install httpd openssl
openssl genrsa -des3 -out www.example.com.key 2048
(Make sure to keep your passphrase in a secure location, not on your server. You'll need this each time you start/restart apache.)

2. Generate CSR (Certificate Signing Request) to give to your SSL certificate authority:

openssl req -new -key www.example.com.key -out www.example.com.csr

This command will prompt for the following X.509 attributes of the certificate:

Country Name: Use the two-letter code without punctuation for country, for example: US or CA.
State or Province: Spell out the state completely; do not abbreviate the state or province name, for example: California
Locality or City: The Locality field is the city or town name, for example: Berkeley. Do not abbreviate. For example: Saint Louis, not St. Louis
Company: If your company or department has an &, @, or any other symbol using the shift key in its name, you must spell out the symbol or omit it to enroll. Example: XY & Z Corporation would be XYZ Corporation or XY and Z Corportation.
Organizational Unit: This field is optional; but can be used to help identify certificates registered to an organization. The Organizational Unit (OU) field is the name of the department or organization unit making the request. To skip the OU field, press Enter on your keyboard.
Common Name: The Common Name is the Host + Domain Name. It looks like "www.company.com" or "company.com".
Certificates can only be used on Web servers using the Common Name specified during enrollment. For example, a certificate for the domain "domain.com" will receive a warning if accessing a site named "www.domain.com" or "secure.domain.com", because "www.domain.com" and "secure.domain.com" are different from "domain.com".
Do not enter your email address, challenge password or an optional company name when generating the CSR.
A public/private key pair has now been created. The private key (www.domain.com.key) is stored locally on the server machine and is used for decryption. The public portion, in the form of a Certificate Signing Request (certrequest.csr), will be for certificate enrollment at the authority of your choice.
To copy and paste the information into the enrollment form, open the file in a text editor such as Notepad or Vi and save it as a .txt file. Do not use Microsoft Word as it may insert extra hidden characters that will alter the contents of the CSR.

Once the CSR has been created, proceed to your certificate authority and purchase your new certificate.

3. Install and configure mod_ssl:

yum install mod_ssl

vi /etc/httpd/conf.d/ssl.conf

Move your key and crt files to:
/etc/httpd/conf/ssl.key
/etc/httpd/conf/ssl.crt

Configuration file:
#
# This is the Apache server configuration file providing SSL support.
# It contains the configuration directives to instruct the server how to
# serve pages over an https connection. For detailing information about these
# directives see <URL:http://httpd.apache.org/docs-2.0/mod/mod_ssl.html>
#
# Do NOT simply read the instructions in here without understanding
# what they do. They're here only as hints or reminders. If you are unsure
# consult the online docs. You have been warned.
#
LoadModule ssl_module modules/mod_ssl.so
# Until documentation is completed, please check http://www.modssl.org/
# for additional config examples and module docmentation. Directives
# and features of mod_ssl are largely unchanged from the mod_ssl project
# for Apache 1.3.
#
# When we also provide SSL we have to listen to the
# standard HTTP port (see above) and to the HTTPS port
#
Listen 443
##
## SSL Global Context
##
## All SSL configuration in this context applies both to
## the main server and all SSL-enabled virtual hosts.
##
#
# Some MIME-types for downloading Certificates and CRLs
#
AddType application/x-x509-ca-cert .crt
AddType application/x-pkcs7-crl .crl
# Pass Phrase Dialog:
# Configure the pass phrase gathering process.
# The filtering dialog program (`builtin' is a internal
# terminal dialog) has to provide the pass phrase on stdout.
SSLPassPhraseDialog builtin
# Inter-Process Session Cache:
# Configure the SSL Session Cache: First the mechanism
# to use and second the expiring timeout (in seconds).
#SSLSessionCache none
#SSLSessionCache dbm:/var/cache/mod_ssl/scache(512000)
#SSLSessionCache dc:UNIX:/var/cache/mod_ssl/distcache
SSLSessionCache shmcb:/var/cache/mod_ssl/scache(512000)
SSLSessionCacheTimeout 300
# Semaphore:
# Configure the path to the mutual exclusion semaphore the
# SSL engine uses internally for inter-process synchronization.
SSLMutex default
# Pseudo Random Number Generator (PRNG):
# Configure one or more sources to seed the PRNG of the
# SSL library. The seed data should be of good random quality.
# WARNING! On some platforms /dev/random blocks if not enough entropy
# is available. This means you then cannot use the /dev/random device
# because it would lead to very long connection times (as long as
# it requires to make more entropy available). But usually those
# platforms additionally provide a /dev/urandom device which doesn't
# block. So, if available, use this one instead. Read the mod_ssl User
# Manual for more details.
SSLRandomSeed startup file:/dev/urandom 256
SSLRandomSeed connect builtin
#SSLRandomSeed startup file:/dev/random 512
#SSLRandomSeed connect file:/dev/random 512
#SSLRandomSeed connect file:/dev/urandom 512
#
# Use "SSLCryptoDevice" to enable any supported hardware
# accelerators. Use "openssl engine -v" to list supported
# engine names. NOTE: If you enable an accelerator and the
# server does not start, consult the error logs and ensure
# your accelerator is functioning properly.
#
SSLCryptoDevice builtin
#SSLCryptoDevice ubsec
##
## SSL Virtual Host Context
<VirtualHost *:443>
# General setup for the virtual host, inherited from global configuration
DocumentRoot "/var/www/html/example.com/"
ServerName www.example.com
# Use separate log files for the SSL virtual host; note that LogLevel
# is not inherited from httpd.conf.
ErrorLog logs/ssl_error_log
TransferLog logs/ssl_access_log
LogLevel warn
# SSL Engine Switch:
# Enable/Disable SSL for this virtual host.
SSLEngine on
# SSL Cipher Suite:
# List the ciphers that the client is permitted to negotiate.
# See the mod_ssl documentation for a complete list.
SSLCipherSuite ALL:!ADH:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP
# Server Certificate:
# Point SSLCertificateFile at a PEM encoded certificate. If
# the certificate is encrypted, then you will be prompted for a
# pass phrase. Note that a kill -HUP will prompt again. A test
# certificate can be generated with `make certificate' under
# built time. Keep in mind that if you've both a RSA and a DSA
# certificate you can configure both in parallel (to also allow
# the use of DSA ciphers, etc.)
SSLCertificateFile /etc/httpd/conf/ssl.crt/www.example.com.crt
#SSLCertificateFile /etc/httpd/conf/ssl.crt/server.crt
#SSLCertificateFile /etc/httpd/conf/ssl.crt/server-dsa.crt
# Server Private Key:
# If the key is not combined with the certificate, use this
# directive to point at the key file. Keep in mind that if
# you've both a RSA and a DSA private key you can configure
# both in parallel (to also allow the use of DSA ciphers, etc.)
SSLCertificateKeyFile /etc/httpd/conf/ssl.key/www.example.com.key
#SSLCertificateKeyFile /etc/httpd/conf/ssl.key/server.key
#SSLCertificateKeyFile /etc/httpd/conf/ssl.key/server-dsa.key
# Server Certificate Chain:
# Point SSLCertificateChainFile at a file containing the
# concatenation of PEM encoded CA certificates which form the
# certificate chain for the server certificate. Alternatively
# the referenced file can be the same as SSLCertificateFile
# when the CA certificates are directly appended to the server
# certificate for convinience.
#SSLCertificateChainFile /etc/httpd/conf/ssl.crt/ca.crt
# Certificate Authority (CA):
# Set the CA certificate verification path where to find CA
# certificates for client authentication or alternatively one
# huge file containing all of them (file must be PEM encoded)
# Note: Inside SSLCACertificatePath you need hash symlinks
# to point to the certificate files. Use the provided
# Makefile to update the hash symlinks after changes.
#SSLCACertificatePath /etc/httpd/conf/ssl.crt
#SSLCACertificateFile /usr/share/ssl/certs/ca-bundle.crt
# Certificate Revocation Lists (CRL):
# Set the CA revocation path where to find CA CRLs for client
# authentication or alternatively one huge file containing all
# of them (file must be PEM encoded)
# Note: Inside SSLCARevocationPath you need hash symlinks
# to point to the certificate files. Use the provided
# Makefile to update the hash symlinks after changes.
#SSLCARevocationPath /etc/httpd/conf/ssl.crl
#SSLCARevocationFile /etc/httpd/conf/ssl.crl/ca-bundle.crl
# Client Authentication (Type):
# Client certificate verification type and depth. Types are
# none, optional, require and optional_no_ca. Depth is a
# number which specifies how deeply to verify the certificate
# issuer chain before deciding the certificate is not valid.
#SSLVerifyClient require
#SSLVerifyDepth 10
# Access Control:
# With SSLRequire you can do per-directory access control based
# on arbitrary complex boolean expressions containing server
# variable checks and other lookup directives. The syntax is a
# mixture between C and Perl. See the mod_ssl documentation
# for more details.
#<Location />
#SSLRequire ( %{SSL_CIPHER} !~ m/^(EXP|NULL)/ \
# and %{SSL_CLIENT_S_DN_O} eq "Snake Oil, Ltd." \
# and %{SSL_CLIENT_S_DN_OU} in {"Staff", "CA", "Dev"} \
# and %{TIME_WDAY} >= 1 and %{TIME_WDAY} <= 5 \
# and %{TIME_HOUR} >= 8 and %{TIME_HOUR} <= 20 ) \
# or %{REMOTE_ADDR} =~ m/^192\.76\.162\.[0-9]+$/
#</Location>
# SSL Engine Options:
# Set various options for the SSL engine.
# o FakeBasicAuth:
# Translate the client X.509 into a Basic Authorisation. This means that
# the standard Auth/DBMAuth methods can be used for access control. The
# user name is the `one line' version of the client's X.509 certificate.
# Note that no password is obtained from the user. Every entry in the user
# file needs this password: `xxj31ZMTZzkVA'.
# o ExportCertData:
# This exports two additional environment variables: SSL_CLIENT_CERT and
# SSL_SERVER_CERT. These contain the PEM-encoded certificates of the
# server (always existing) and the client (only existing when client
# authentication is used). This can be used to import the certificates
# into CGI scripts.
# o StdEnvVars:
# This exports the standard SSL/TLS related `SSL_*' environment variables.
# Per default this exportation is switched off for performance reasons,
# because the extraction step is an expensive operation and is usually
# useless for serving static content. So one usually enables the
# exportation for CGI and SSI requests only.
# o StrictRequire:
# This denies access when "SSLRequireSSL" or "SSLRequire" applied even
# under a "Satisfy any" situation, i.e. when it applies access is denied
# and no other module can change it.
# o OptRenegotiate:
# This enables optimized SSL connection renegotiation handling when SSL
# directives are used in per-directory context.
#SSLOptions +FakeBasicAuth +ExportCertData +CompatEnvVars +StrictRequire
<Files ~ "\.(cgi|shtml|phtml|php3?)$">
SSLOptions +StdEnvVars
</Files>
<Directory "/var/www/cgi-bin">
SSLOptions +StdEnvVars
</Directory>
# SSL Protocol Adjustments:
# The safe and default but still SSL/TLS standard compliant shutdown
# approach is that mod_ssl sends the close notify alert but doesn't wait for
# the close notify alert from client. When you need a different shutdown
# approach you can use one of the following variables:
# o ssl-unclean-shutdown:
# This forces an unclean shutdown when the connection is closed, i.e. no
# SSL close notify alert is send or allowed to received. This violates
# the SSL/TLS standard but is needed for some brain-dead browsers. Use
# this when you receive I/O errors because of the standard approach where
# mod_ssl sends the close notify alert.
# o ssl-accurate-shutdown:
# This forces an accurate shutdown when the connection is closed, i.e. a
# SSL close notify alert is send and mod_ssl waits for the close notify
# alert of the client. This is 100% SSL/TLS standard compliant, but in
# practice often causes hanging connections with brain-dead browsers. Use
# this only for browsers where you know that their SSL implementation
# works correctly.
# Notice: Most problems of broken clients are also related to the HTTP
# keep-alive facility, so you usually additionally want to disable
# keep-alive for those clients, too. Use variable "nokeepalive" for this.
# Similarly, one has to force some clients to use HTTP/1.0 to workaround
# their broken HTTP/1.1 implementation. Use variables "downgrade-1.0" and
# "force-response-1.0" for this.
SetEnvIf User-Agent ".*MSIE.*" \
nokeepalive ssl-unclean-shutdown \
downgrade-1.0 force-response-1.0
# Per-Server Logging:
# The home of a custom SSL log file. Use this when you want a
# compact non-error SSL logfile on a virtual host basis.
CustomLog logs/ssl_request_log \
"%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b"
</VirtualHost>

4. Restart httpd using the passphrase:

service httpd restart (or start if it hasn't been started)

service httpd restart
Stopping httpd: [ OK ]
Starting httpd:
Apache/2.2.8 mod_ssl/2.2.8 (Pass Phrase Dialog)
Some of your private key files are encrypted for security reasons.
In order to read them you have to provide the pass phrases.

Server www.example.com:443 (RSA)
Enter pass phrase:

OK: Pass Phrase Dialog successful.
[ OK ]

Troubleshooting
How to test
Explanation troubleshooting basics and expectations.

1. Test your new SSL connection:

Visit: https://www.example.com

2. Make sure httpd is started and that port 443 is open. Also, make sure you have configured httpd correctly apart from the SSL configuration:

service httpd status; service iptables status

Common problems and fixes

Describe common problems here, include links to known common problems if on another site

* http://wiki.centos.org

More Information
Any additional information or notes.
Disclaimer

We test this stuff on our own machines, really we do. But you may run into problems, if you do, come to #centos on irc.freenode.net