ssl client certificate docs
This commit is contained in:
Christian Weiske
parent
9cc4b5ffc2
commit
0ff131fbb1
1 changed files with 174 additions and 0 deletions
174
doc/ssl-client-certificates.rst
Normal file
174
doc/ssl-client-certificates.rst
Normal file
|
|
@ -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`_.
|
||||
Loading…
Reference in a new issue