ssl client certificate docs

diff --git a/doc/ssl-client-certificates.rst b/doc/ssl-client-certificates.rst
new file mode 100644 (file)
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`_.