1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
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`_.
|
