=======================
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.

Note that you can equip several virtual hosts with SSL certificates
and keep them on the same, standard SSL port by using SNI -
`Server Name Indication`__.

.. _SNI: http://wiki.apache.org/httpd/NameBasedSSLVHostsWithSNI
__ SNI_

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`_.