<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> <head> <meta http-equiv="Content-type" content="text/html; charset=utf-8" /> <meta http-equiv="Content-Language" content="en-us" /> <meta name="ROBOTS" content="ALL" /> <meta http-equiv="imagetoolbar" content="no" /> <meta name="MSSmartTagsPreventParsing" content="true" /> <meta name="Keywords" content="cherokee web server httpd http" /> <meta name="Description" content="Cherokee is a flexible, very fast, lightweight Web server. It is implemented entirely in C, and has no dependencies beyond a standard C library. It is embeddable and extensible with plug-ins. It supports on-the-fly configuration by reading files or strings, TLS/SSL (via GNUTLS or OpenSSL), virtual hosts, authentication, cache friendly features, PHP, custom error management, and much more." /> <link href="media/css/cherokee_doc.css" rel="stylesheet" type="text/css" media="all" /> </head> <body> <h2 id="_a_href_index_html_index_a_8594_a_href_cookbook_html_cookbook_a"><a href="index.html">Index</a> → <a href="cookbook.html">Cookbook</a></h2> <div class="sectionbody"> </div> <h2 id="_cookbook_ssl_tls_and_certificates">Cookbook: SSL, TLS and certificates</h2> <div class="sectionbody"> <div class="paragraph"><p>This section answers some general questions and details the procedure to generate SSL keys.</p></div> <h3 id="general">General questions</h3><div style="clear:left"></div> <div class="paragraph"><div class="title">Can the same server provide HTTP and HTTPS?</div><p>Yes. HTTP and HTTPS use different server ports. The former binds to port 80 and the latter to port 443, so there is no conflict between them. To provide HTTPS you will need matching certificates.</p></div> <div class="paragraph"><p>Keep in mind that to have one of your virtual servers with HTTPS enabled you will need to configure HTTPS settings for all of them.</p></div> <div class="paragraph"><div class="title">Which port does HTTPS use?</div><p>HTTPS can run on any port, but the standards specify port 443. That’s where any HTTPS compliant browser will look by default. You can change that by specifying another port in the URL. For example, <a href="https://example.com:8080/">https://example.com:8080/</a> would look for an HTTPS server on port 8080.</p></div> <div class="paragraph"><div class="title">How to enable the SSL support?</div><p>SSL support is not enabled by default. You will have to perform three straightforward actions is order to enable it:</p></div> <div class="olist arabic"><ol class="arabic"> <li> <p> The first step is to enable a TLS/SSL engine. The option is located in the <a href="config_general.html">General</a> configuration setting. Cherokee is shipped with a libssl plug-in. </p> </li> <li> <p> Once the engine is configured, a new <a href="config_general.html#ports_to_listen">binding port</a> must be configured. By default, HTTPS uses the port 443. Remember to add this port, and to check the TLS toggle button. </p> </li> <li> <p> The last step would be to assign SSL certificates to the virtual servers, starting with the default virtual server. Cherokee uses SNI to distinguish between virtual servers. The certificate specified in the default server will be used in the first negotiation. If not present, the startup sequence will fail. The configuration is found inside each <a href="config_virtual_servers.html#security">virtual server</a> configuration, under the Security tab. This part is <em>very important</em>: you have to concatenate your certificates into a single file in order to use them in Cherokee. </p> </li> </ol></div> <div class="paragraph"><div class="title">How to manually test HTTP/HTTPS?</div><p>HTTP can easily be tested like this:</p></div> <div class="listingblock"> <div class="content"> <pre><tt>$ telnet localhost 80 GET / HTTP/1.0</tt></pre> </div></div> <div class="paragraph"><p>For HTTPS it is not so easy because of the SSL protocol between TCP and HTTP. However you can do a similar check with the help of OpenSSL’s s_client command.</p></div> <div class="listingblock"> <div class="content"> <pre><tt>$ openssl s_client -connect localhost:443 -state -debug GET / HTTP/1.0</tt></pre> </div></div> <div class="paragraph"><p>You will receive detailed information about the SSL handshake before the actual HTTP response.</p></div> <div class="paragraph"><p>A more general command line client is probably a better choice. <a href="http://curl.haxx.se/">cURL</a> deals with both HTTP and HTTPS, and performs a bunch of other interesting stuff.</p></div> <div class="listingblock"> <div class="content"> <pre><tt>$ curl http://localhost/ $ curl https://localhost/</tt></pre> </div></div> <h3 id="overview">Private keys and Certificates overview</h3><div style="clear:left"></div> <div class="paragraph"><p>First some terminology:</p></div> <div class="olist arabic"><ol class="arabic"> <li> <p> RSA private key file: a digital file that can be used to decrypt messages sent to you. It has a public component that must be distributed (via your Certificate file) to allow people to encrypt those messages. </p> </li> <li> <p> CSR, or Certificate Signing Request: a digital file containing your public key and your name. It is sent to a Certifying Authority (CA) that will convert sign it to convert it into a real Certificate. </p> </li> <li> <p> Certificate: contains your RSA public key and name, the name of the CA, and is digitally signed by the CA. A browser that knows the CA can verify the signature and obtain your RSA public key, which can be used to send messages which only you can decrypt. </p> </li> </ol></div> <div class="paragraph"><div class="title">Does the startup between a non-SSL and an SSL-aware web server differ?</div><p>Yes. Although in essence it is exactly the same, if you have a passphrase on your SSL private key file, a startup dialog will asks you to enter it. This can be problematic if the web server needs to be started automatically. In this case, the <a href="#passphrase">passphrase</a> can be removed from your private key at the cost of erasing a security layer, which brings additional security risks.</p></div> <div class="paragraph"><div class="title">Does Cherokee offer any help for Certificate Generation?</div><p>Yes. A script is provided to assist you with Certificate Generation.</p></div> <div class="paragraph"><p>Just locate the <tt>contrib</tt> subdirectory and type:</p></div> <div class="listingblock"> <div class="content"> <pre><tt>make-cert.sh</tt></pre> </div></div> <div class="paragraph"><p>And follow the instructions. It will generate the required files, but you will have to install them manually.</p></div> <div class="paragraph"><p>It has been tested and has worked fine every time, but if you don’t find the script or it doesn’t work for you can always follow the rest of the procedure described in this recipe to manually generate the certificates.</p></div> <h3 id="locate">Locate CA.pl or CA.sh</h3><div style="clear:left"></div> <div class="ulist"><ul> <li> <p> On Debian or Ubuntu those are usually located under /usr/lib/ssl/misc/ </p> </li> <li> <p> On MacOS X, you will find them in /System/Library/OpenSSL/misc/ </p> </li> </ul></div> <div class="paragraph"><p>In any other case <tt>`find / -iname CA.pl -print</tt>` will help you to locate it.</p></div> <h3 id="create">Create a new CA</h3><div style="clear:left"></div> <div class="listingblock"> <div class="content"> <pre><tt> $ /usr/lib/ssl/misc/CA.pl -newca CA certificate filename (or enter to create) <press enter> Making CA certificate ... Generating a 1024 bit RSA private key .............++++++ .......................................++++++ writing new private key to './demoCA/private/cakey.pem' Enter PEM pass phrase: <type the secret phrase again> Verifying - Enter PEM pass phrase: <type the secret phrase again> ----- You are about to be asked to enter information that will be incorporated into your certificate request. What you are about to enter is what is called a Distinguished Name or a DN. There are quite a few fields but you can leave some blank For some fields there will be a default value, If you enter '.', the field will be left blank. ----- Country Name (2 letter code) [AU]:ES State or Province Name (full name) [Some-State]:. Locality Name (eg, city) []:. Organization Name (eg, company) [Internet Widgits Pty Ltd]:Cherokee Team Organizational Unit Name (eg, section) []:<Enter> Common Name (eg, YOUR name) []:Cherokee Certificate Master Email Address []:alvaro@alobbs.com</tt></pre> </div></div> <h3 id="generate">Generate a certificate request</h3><div style="clear:left"></div> <div class="listingblock"> <div class="content"> <pre><tt> $ /usr/lib/ssl/misc/CA.pl -newreq Generating a 1024 bit RSA private key .....................................++++++ ...++++++ writing new private key to 'newreq.pem' Enter PEM pass phrase: <another phrase> Verifying - Enter PEM pass phrase: <repeat it> ----- You are about to be asked to enter information that will be incorporated into your certificate request. What you are about to enter is what is called a Distinguished Name or a DN. There are quite a few fields but you can leave some blank For some fields there will be a default value, If you enter '.', the field will be left blank. ----- Country Name (2 letter code) [AU]:ES State or Province Name (full name) [Some-State]:. Locality Name (eg, city) []:. Organization Name (eg, company) [Internet Widgits Pty Ltd]:Cherokee web server Organizational Unit Name (eg, section) []:. Common Name (eg, YOUR name) []:www.cherokee-project.com Email Address []:sysop@cherokee-project.com Please enter the following 'extra' attributes to be sent with your certificate request A challenge password []: <Enter> An optional company name []: <Enter> Request (and private key) is in newreq.pem</tt></pre> </div></div> <h3 id="sign">Sign the certificate request</h3><div style="clear:left"></div> <div class="listingblock"> <div class="content"> <pre><tt> $ /usr/lib/ssl/misc/CA.pl -sign: Using configuration from /usr/lib/ssl/openssl.cnf Enter pass phrase for ./demoCA/private/cakey.pem: Check that the request matches the signature Signature ok Certificate Details: Serial Number: 1 (0x1) Validity: Not Before: Aug 17 13:12:44 2003 GMT Not After : Aug 16 13:12:44 2004 GMT Subject: countryName = ES organizationName = Cherokee web server commonName = www.cherokee-project.com emailAddress = sysop@cherokee-project.com X509v3 extensions: X509v3 Basic Constraints: CA:FALSE Netscape Comment: OpenSSL Generated Certificate X509v3 Subject Key Identifier: 14:6A:45:66:A2:EB:73:74:5A:C5:68:80:50:D5:48:94:DD:ED:25:F7 X509v3 Authority Key Identifier: keyid:9E:E0:E2:6E:1B:02:17:F2:72:C9:0D:E3:DA:C9:E1:8F:CE:BC:6E:A2 DirName:/C=ES/ST=Madrid/L=Madrid/O=Cherokee Team/CN=Cherokee Certificate Master/emailAddress=alvaro@alobbs.com serial:00 Certificate is to be certified until Aug 16 13:12:44 2004 GMT (365 days) Sign the certificate? [y/n]:y 1 out of 1 certificate requests certified, commit? [y/n]y Write out database with 1 new entries Data Base Updated Signed certificate is in newcert.pem</tt></pre> </div></div> <h3 id="self_sign">Self signed certificates</h3><div style="clear:left"></div> <div class="paragraph"><p>It is another way to generate certificate files. Ramon Pons sent this little script to create self signed certificates::</p></div> <div class="listingblock"> <div class="content"> <pre><tt>#!/bin/sh CERTNAME=cherokee.pem openssl req -days 1000 -new -x509 -nodes -out $CERTNAME -keyout $CERTNAME chmod 600 $CERTNAME openssl verify $CERTNAME if [ $? != 0 ]; then \mv $CERTNAME $CERTNAME.not_valid fi</tt></pre> </div></div> <div class="paragraph"><p>You can see that, in essence, it issues the following command:</p></div> <div class="listingblock"> <div class="content"> <pre><tt>$ openssl req -new -x509 -nodes -out server.crt -keyout server.key</tt></pre> </div></div> <div class="paragraph"><p>Which would produce a couple of files: the SSL Certificate File (server.crt) and the SSL Certificate key file (server.key).</p></div> <div class="paragraph"><p>This server.key does not have any passphrase. To add a passphrase to the key, you should run the following command, and enter & verify the passphrase as requested.</p></div> <div class="listingblock"> <div class="content"> <pre><tt>$ openssl rsa -des3 -in server.key -out server.key.new $ mv server.key.new server.key</tt></pre> </div></div> <div class="paragraph"><p>You should probably backup the key file and the entered passphrase in a secure location.</p></div> <h3 id="passphrase">Pass-phrase issues</h3><div style="clear:left"></div> <div class="paragraph"><p>As noted above, if you have a pass-phrase on your SSL private key file, the web-server start up will remain on hold until you enter it. Here is the information needed to change it or even remove it, but bare in mind the security implications.</p></div> <div class="paragraph"><div class="title">How to change the pass-phrase on a private key file?</div><p>Simply read it with the old pass-phrase and write it again, specifying a new pass-phrase. This can be done withe these commands:</p></div> <div class="listingblock"> <div class="content"> <pre><tt>$ openssl rsa -des3 -in server.key -out server.key.new $ mv server.key.new server.key</tt></pre> </div></div> <div class="paragraph"><div class="title">How to get rid of the pass-phrase?</div><p>The RSA private key inside the server.key file is stored in encrypted format for security reasons. The pass-phrase is needed to decrypt this file, so it can be read and parsed. Thus, removing it removes a layer of security from the web server. It is advised to keep a backup copy of the original file before proceeding.</p></div> <div class="listingblock"> <div class="content"> <pre><tt> $ cp server.key server.key.org $ openssl rsa -in server.key.org -out server.key $ chmod 400 server.key</tt></pre> </div></div> <div class="paragraph"><p>Since the server.key now contains an unencrypted copy of the key, if anyone gets it they will be able to impersonate you on the net.</p></div> <h3 id="verification">Verifying that a private key matches its Certificate</h3><div style="clear:left"></div> <div class="paragraph"><p>To view the Certificate and the key run the commands:</p></div> <div class="listingblock"> <div class="content"> <pre><tt>$ openssl x509 -noout -text -in server.crt $ openssl rsa -noout -text -in server.key</tt></pre> </div></div> <div class="paragraph"><p>The <tt>modulus</tt> and the <tt>public exponent</tt> portions in the key and the Certificate must match. It is difficult to visually check that the long modulus numbers are the same, so this approach can be used instead to obtain the numbers to compare (though it is mathematically less rigorous).</p></div> <div class="listingblock"> <div class="content"> <pre><tt>$ openssl x509 -noout -modulus -in server.crt | openssl md5 $ openssl rsa -noout -modulus -in server.key | openssl md5</tt></pre> </div></div> <div class="paragraph"><p>To check to which key or certificate a particular CSR belongs you can perform the same calculation on the CSR as follows:</p></div> <div class="listingblock"> <div class="content"> <pre><tt>$ openssl req -noout -modulus -in server.csr | openssl md5</tt></pre> </div></div> </div> <div id="footer"> <div id="footer-text"> </div> </div> </body> </html>