diff options
| -rw-r--r-- | doc/ssl-client-certificates.rst | 174 |
1 files changed, 174 insertions, 0 deletions
diff --git a/doc/ssl-client-certificates.rst b/doc/ssl-client-certificates.rst new file mode 100644 index 0000000..92bcdec --- /dev/null +++ b/doc/ssl-client-certificates.rst @@ -0,0 +1,174 @@ +======================= +SSL client certificates +======================= + +By using SSL client certificates, you get automatically logged into +SemanticScuttle without using a password or submitting a login form. + +Any number of certificates can be registered with a user account, +making it easy to login to the same installation from home and from +work - without risking to use the same certificate on both machines. + + +Usage scenarios +=============== +The scenarios assume that the web server is configured_ properly +to request client certificates. + +.. _configured: `Configuring your web server`_ + + +Registering a certificate with an existing account +-------------------------------------------------- +You already have an account and want to associate a SSL client certificate +with it. + +1. Visit your profile page +2. Click "Register current certificate to automatically login." + +That's it. Now logout and click "Home". You will be logged in again +automatically. + + +Registering a certificate with a new account +-------------------------------------------- +When you do not have an user account yet, just visit the registration +page. Your email address will already be filled in, using the information +from the SSL certificate. + +Provide the rest of the data and submit the form. +The certificate will automatically be associated to your account, +and the user name will also be set for you. + + + +Configuring your web server +=========================== + +Getting SSL certificates +------------------------ +You need both a server certificate for normal HTTPS mode, as well as a client +certificate in your browser. + +CAcert.org is a good place to obtain both. +You are of course free to generate your own certificate with i.e. openssl +or buy a certificate from another certificate authority, but this is out +of this document's scope. + +Server certificate +'''''''''''''''''' +First, generate a Certificate signing request with the `CSR generator`__. +Store the key file under :: + + /etc/ssl/private/bookmarks.cweiske.de.key + +Use the the .csr file and the CAcert web interface to generate a signed +certificate. Store it as :: + + /etc/ssl/private/bookmarks.cweiske.de-cacert.pem + +Now fetch both official CAcert certificates (root and class 3) and put both +together into :: + + /etc/ssl/private/cacert-1and3.crt + +.. _CSR: http://wiki.cacert.org/CSRGenerator +__ CSR_ + + +Client certificate +'''''''''''''''''' +CAcert also offers to create client certificates. You do not need a +certificate sign request but just can create it on their web page. + +After creation, you can simply install it in your browser by clicking +on the appropriate link on the CAcert page. + +Once you got the certificate installed in your browser, you can transfer +it to other browsers by exporting it in the `PKCS #12` format +(with private key included) and importing it in any other browsers +you use. + + + +Apache configuration +-------------------- +To make use of SSL client certificates, you need to deliver SemanticScuttle +via HTTPS. + +A basic virtual host configuration with SSL looks like this: + +:: + + <VirtualHost *:443> + ServerName bookmarks.cweiske.de + + LogFormat "%V %h %l %u %t \"%r\" %s %b" vcommon + CustomLog /var/log/apache2/access_log vcommon + + VirtualDocumentRoot /home/cweiske/Dev/html/hosts/bookmarks.cweiske.de + <Directory "/home/cweiske/Dev/html/hosts/bookmarks.cweiske.de"> + AllowOverride all + </Directory> + + SSLEngine On + SSLCertificateFile /etc/ssl/private/bookmarks.cweiske.de-cacert.pem + SSLCertificateKeyFile /etc/ssl/private/bookmarks.cweiske.de.key + + SSLCACertificateFile /etc/ssl/private/cacert-1and3.crt + </VirtualHost> + +Apart from that, you might need to enable the SSL module in your webserver, +i.e. by executing :: + + $ a2enmod ssl + + +Now that SSL works, you can configure your web server to request client +certificates. + +:: + + ... + </Directory> + + SSLVerifyClient optional + SSLVerifyDepth 1 + SSLOptions +StdEnvVars + </VirtualHost> + +There are several options you need to set: + + +``SSLVerifyClient optional`` + You may choose ``optional`` or ``required`` here. + ``optional`` asks the browser for a client certificate but accepts + if the browser (the user) does choose not to send any certificate. + This is the best option if you want to be able to login with and + without a certificate. + + Setting ``required`` makes the web server terminate the connection + when no client certificate is sent by the browser. + This option may be used when all users have their client certificate set. + +``SSLVerifyDepth 1`` + Your client certificate is signed by a certificate authority (CA), + and your web server trusts the CA specified in ``SSLCACertificateFile``. + CA certificates itself may be signed by another authority, i.e. like :: + + CAcert >> your own CA >> your client certificate + + In this case, you have a higher depth. For most cases, 1 is enough. + +``SSLOptions +StdEnvVars`` + This makes your web server pass the SSL environment variables to PHP, + so that SemanticScuttle can detect that a client certificate is available + and read its data. + + In case you need the complete certificate + \- which SemanticScuttle does *not* need - you have to add ``+ExportCertData`` + to the line. + + +That's it. Restart your web server and visit your SemanticScuttle installation. +Continue reading the `Usage scenarios`_. |