Mercurial > prosody-wiki

annotate mod_client_certs.wiki @ 322:c52f914590e7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
wiki commit.
author Marco Cirillo <maranda@lightwitch.org>
date Tue, 05 Mar 2013 17:03:11 +0000
parents 118f44d63e25
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
283
bc0b13c53b57 Created wiki page through web user interface.
thijsalkemade@gmail.com
parents:
diff changeset
1 #summary Client-side certificate management for Prosody
bc0b13c53b57 Created wiki page through web user interface.
thijsalkemade@gmail.com
parents:
diff changeset
2 #labels Stage-Alpha
bc0b13c53b57 Created wiki page through web user interface.
thijsalkemade@gmail.com
parents:
diff changeset
3
bc0b13c53b57 Created wiki page through web user interface.
thijsalkemade@gmail.com
parents:
diff changeset
4 = Introduction =
bc0b13c53b57 Created wiki page through web user interface.
thijsalkemade@gmail.com
parents:
diff changeset
5 [http://xmpp.org/extensions/xep-0257.html XEP-0257] specifies a protocol for clients to store and manage client side certificates. When a client presents a stored client side certificate during the TLS handshake, it can log in without supplying a password (using SASL EXTERNAL). This makes it possible to have multiple devices accessing an account, without any of them needing to know the password, and makes it easier to revoke access for a single device.
bc0b13c53b57 Created wiki page through web user interface.
thijsalkemade@gmail.com
parents:
diff changeset
6
bc0b13c53b57 Created wiki page through web user interface.
thijsalkemade@gmail.com
parents:
diff changeset
7
bc0b13c53b57 Created wiki page through web user interface.
thijsalkemade@gmail.com
parents:
diff changeset
8 = Details =
bc0b13c53b57 Created wiki page through web user interface.
thijsalkemade@gmail.com
parents:
diff changeset
9
bc0b13c53b57 Created wiki page through web user interface.
thijsalkemade@gmail.com
parents:
diff changeset
10 Each user can add their own certificates. These do not need to be signed by a trusted CA, yet they do need to be valid at the time of logging in and they should include an subjectAltName with otherName "id-on-xmppAddr" with the JID of the user.
bc0b13c53b57 Created wiki page through web user interface.
thijsalkemade@gmail.com
parents:
diff changeset
11
287
1a00ae04a358 Added an example of how to generate your client side certificate with a id-on-xmppAddr field, thanks to Zash for the cnf file.
thijsalkemade@gmail.com
parents: 283
diff changeset
12 == Generating your certificate ==
1a00ae04a358 Added an example of how to generate your client side certificate with a id-on-xmppAddr field, thanks to Zash for the cnf file.
thijsalkemade@gmail.com
parents: 283
diff changeset
13
1a00ae04a358 Added an example of how to generate your client side certificate with a id-on-xmppAddr field, thanks to Zash for the cnf file.
thijsalkemade@gmail.com
parents: 283
diff changeset
14 # To generate your own certificate with a "id-on-xmppAddr" attribute using the command line {{{openssl}}} tool, first create a file called {{{client.cnf}}} with contents:
1a00ae04a358 Added an example of how to generate your client side certificate with a id-on-xmppAddr field, thanks to Zash for the cnf file.
thijsalkemade@gmail.com
parents: 283
diff changeset
15 {{{
1a00ae04a358 Added an example of how to generate your client side certificate with a id-on-xmppAddr field, thanks to Zash for the cnf file.
thijsalkemade@gmail.com
parents: 283
diff changeset
16 [req]
1a00ae04a358 Added an example of how to generate your client side certificate with a id-on-xmppAddr field, thanks to Zash for the cnf file.
thijsalkemade@gmail.com
parents: 283
diff changeset
17 prompt = no
1a00ae04a358 Added an example of how to generate your client side certificate with a id-on-xmppAddr field, thanks to Zash for the cnf file.
thijsalkemade@gmail.com
parents: 283
diff changeset
18 x509_extensions = v3_extensions
1a00ae04a358 Added an example of how to generate your client side certificate with a id-on-xmppAddr field, thanks to Zash for the cnf file.
thijsalkemade@gmail.com
parents: 283
diff changeset
19 req_extensions = v3_extensions
1a00ae04a358 Added an example of how to generate your client side certificate with a id-on-xmppAddr field, thanks to Zash for the cnf file.
thijsalkemade@gmail.com
parents: 283
diff changeset
20 distinguished_name = distinguished_name
1a00ae04a358 Added an example of how to generate your client side certificate with a id-on-xmppAddr field, thanks to Zash for the cnf file.
thijsalkemade@gmail.com
parents: 283
diff changeset
21
1a00ae04a358 Added an example of how to generate your client side certificate with a id-on-xmppAddr field, thanks to Zash for the cnf file.
thijsalkemade@gmail.com
parents: 283
diff changeset
22 [v3_extensions]
1a00ae04a358 Added an example of how to generate your client side certificate with a id-on-xmppAddr field, thanks to Zash for the cnf file.
thijsalkemade@gmail.com
parents: 283
diff changeset
23 extendedKeyUsage = clientAuth
1a00ae04a358 Added an example of how to generate your client side certificate with a id-on-xmppAddr field, thanks to Zash for the cnf file.
thijsalkemade@gmail.com
parents: 283
diff changeset
24 keyUsage = digitalSignature,keyEncipherment
1a00ae04a358 Added an example of how to generate your client side certificate with a id-on-xmppAddr field, thanks to Zash for the cnf file.
thijsalkemade@gmail.com
parents: 283
diff changeset
25 basicConstraints = CA:FALSE
1a00ae04a358 Added an example of how to generate your client side certificate with a id-on-xmppAddr field, thanks to Zash for the cnf file.
thijsalkemade@gmail.com
parents: 283
diff changeset
26 subjectAltName = @subject_alternative_name
1a00ae04a358 Added an example of how to generate your client side certificate with a id-on-xmppAddr field, thanks to Zash for the cnf file.
thijsalkemade@gmail.com
parents: 283
diff changeset
27
1a00ae04a358 Added an example of how to generate your client side certificate with a id-on-xmppAddr field, thanks to Zash for the cnf file.
thijsalkemade@gmail.com
parents: 283
diff changeset
28 [subject_alternative_name]
1a00ae04a358 Added an example of how to generate your client side certificate with a id-on-xmppAddr field, thanks to Zash for the cnf file.
thijsalkemade@gmail.com
parents: 283
diff changeset
29 otherName.0 = 1.3.6.1.5.5.7.8.5;FORMAT:UTF8,UTF8:hamlet@shakespeare.lit
1a00ae04a358 Added an example of how to generate your client side certificate with a id-on-xmppAddr field, thanks to Zash for the cnf file.
thijsalkemade@gmail.com
parents: 283
diff changeset
30
1a00ae04a358 Added an example of how to generate your client side certificate with a id-on-xmppAddr field, thanks to Zash for the cnf file.
thijsalkemade@gmail.com
parents: 283
diff changeset
31 [distinguished_name]
1a00ae04a358 Added an example of how to generate your client side certificate with a id-on-xmppAddr field, thanks to Zash for the cnf file.
thijsalkemade@gmail.com
parents: 283
diff changeset
32 commonName = Your Name
1a00ae04a358 Added an example of how to generate your client side certificate with a id-on-xmppAddr field, thanks to Zash for the cnf file.
thijsalkemade@gmail.com
parents: 283
diff changeset
33 emailAddress = hamlet@shakespeare.lit
1a00ae04a358 Added an example of how to generate your client side certificate with a id-on-xmppAddr field, thanks to Zash for the cnf file.
thijsalkemade@gmail.com
parents: 283
diff changeset
34 }}}
1a00ae04a358 Added an example of how to generate your client side certificate with a id-on-xmppAddr field, thanks to Zash for the cnf file.
thijsalkemade@gmail.com
parents: 283
diff changeset
35 # Replace the values for {{{otherName.0}}} and {{{commonName}}} and {{{emailAddress}}} with your own values. The JID in {{{otherName.0}}} can either be a full JID or a bare JID, in the former case, the client can only use the resource specified in the resource. There are many other fields you can add, however, for SASL EXTERNAL, they will have no meaning. You can add more JIDs as {{{otherName.1}}}, {{{otherName.2}}}, etc.
1a00ae04a358 Added an example of how to generate your client side certificate with a id-on-xmppAddr field, thanks to Zash for the cnf file.
thijsalkemade@gmail.com
parents: 283
diff changeset
36 # Create a private key (as an example, a 4096 bits RSA key):
1a00ae04a358 Added an example of how to generate your client side certificate with a id-on-xmppAddr field, thanks to Zash for the cnf file.
thijsalkemade@gmail.com
parents: 283
diff changeset
37 {{{
1a00ae04a358 Added an example of how to generate your client side certificate with a id-on-xmppAddr field, thanks to Zash for the cnf file.
thijsalkemade@gmail.com
parents: 283
diff changeset
38 openssl genrsa -out client.key 4096
1a00ae04a358 Added an example of how to generate your client side certificate with a id-on-xmppAddr field, thanks to Zash for the cnf file.
thijsalkemade@gmail.com
parents: 283
diff changeset
39 }}}
1a00ae04a358 Added an example of how to generate your client side certificate with a id-on-xmppAddr field, thanks to Zash for the cnf file.
thijsalkemade@gmail.com
parents: 283
diff changeset
40 # Create the certificate request:
1a00ae04a358 Added an example of how to generate your client side certificate with a id-on-xmppAddr field, thanks to Zash for the cnf file.
thijsalkemade@gmail.com
parents: 283
diff changeset
41 {{{
1a00ae04a358 Added an example of how to generate your client side certificate with a id-on-xmppAddr field, thanks to Zash for the cnf file.
thijsalkemade@gmail.com
parents: 283
diff changeset
42 openssl req -key client.key -new -out client.req -config client.cnf -extensions v3_extensions
1a00ae04a358 Added an example of how to generate your client side certificate with a id-on-xmppAddr field, thanks to Zash for the cnf file.
thijsalkemade@gmail.com
parents: 283
diff changeset
43 }}}
1a00ae04a358 Added an example of how to generate your client side certificate with a id-on-xmppAddr field, thanks to Zash for the cnf file.
thijsalkemade@gmail.com
parents: 283
diff changeset
44 # Sign it yourself:
1a00ae04a358 Added an example of how to generate your client side certificate with a id-on-xmppAddr field, thanks to Zash for the cnf file.
thijsalkemade@gmail.com
parents: 283
diff changeset
45 {{{
1a00ae04a358 Added an example of how to generate your client side certificate with a id-on-xmppAddr field, thanks to Zash for the cnf file.
thijsalkemade@gmail.com
parents: 283
diff changeset
46 openssl x509 -req -days 365 -in client.req -signkey client.key -out client.crt -extfile client.cnf -extensions v3_extensions
1a00ae04a358 Added an example of how to generate your client side certificate with a id-on-xmppAddr field, thanks to Zash for the cnf file.
thijsalkemade@gmail.com
parents: 283
diff changeset
47 }}}
1a00ae04a358 Added an example of how to generate your client side certificate with a id-on-xmppAddr field, thanks to Zash for the cnf file.
thijsalkemade@gmail.com
parents: 283
diff changeset
48 The 365 means the certificate will be valid for a year starting now.
1a00ae04a358 Added an example of how to generate your client side certificate with a id-on-xmppAddr field, thanks to Zash for the cnf file.
thijsalkemade@gmail.com
parents: 283
diff changeset
49
288
118f44d63e25 Explained what these steps actually generated.
thijsalkemade@gmail.com
parents: 287
diff changeset
50 The {{{client.key}}} *must* be kept secret, and is only needed by clients connecting using this certificate. The {{{client.crt}}} file contains the certificate that should be sent to the server using XEP-0257, and is also needed by clients connecting to the server. The {{{client.req}}} file is not needed anymore.
118f44d63e25 Explained what these steps actually generated.
thijsalkemade@gmail.com
parents: 287
diff changeset
51
283
bc0b13c53b57 Created wiki page through web user interface.
thijsalkemade@gmail.com
parents:
diff changeset
52 = Configuration =
bc0b13c53b57 Created wiki page through web user interface.
thijsalkemade@gmail.com
parents:
diff changeset
53
bc0b13c53b57 Created wiki page through web user interface.
thijsalkemade@gmail.com
parents:
diff changeset
54 (None yet)
bc0b13c53b57 Created wiki page through web user interface.
thijsalkemade@gmail.com
parents:
diff changeset
55
bc0b13c53b57 Created wiki page through web user interface.
thijsalkemade@gmail.com
parents:
diff changeset
56 = Compatibility =
bc0b13c53b57 Created wiki page through web user interface.
thijsalkemade@gmail.com
parents:
diff changeset
57
bc0b13c53b57 Created wiki page through web user interface.
thijsalkemade@gmail.com
parents:
diff changeset
58 ||0.9||Works||
bc0b13c53b57 Created wiki page through web user interface.
thijsalkemade@gmail.com
parents:
diff changeset
59 ||0.8||Untested. Probably doesn't.||
bc0b13c53b57 Created wiki page through web user interface.
thijsalkemade@gmail.com
parents:
diff changeset
60
bc0b13c53b57 Created wiki page through web user interface.
thijsalkemade@gmail.com
parents:
diff changeset
61 = Clients =
bc0b13c53b57 Created wiki page through web user interface.
thijsalkemade@gmail.com
parents:
diff changeset
62
bc0b13c53b57 Created wiki page through web user interface.
thijsalkemade@gmail.com
parents:
diff changeset
63 (None?)
bc0b13c53b57 Created wiki page through web user interface.
thijsalkemade@gmail.com
parents:
diff changeset
64
bc0b13c53b57 Created wiki page through web user interface.
thijsalkemade@gmail.com
parents:
diff changeset
65 = TODO =
bc0b13c53b57 Created wiki page through web user interface.
thijsalkemade@gmail.com
parents:
diff changeset
66 Possible options to add to the configuration:
bc0b13c53b57 Created wiki page through web user interface.
thijsalkemade@gmail.com
parents:
diff changeset
67 * Require certificates to be signed by a trusted CA.
bc0b13c53b57 Created wiki page through web user interface.
thijsalkemade@gmail.com
parents:
diff changeset
68 * Do not require a id-on-xmppAddr
bc0b13c53b57 Created wiki page through web user interface.
thijsalkemade@gmail.com
parents:
diff changeset
69 * Remove expired certs after a certain time
bc0b13c53b57 Created wiki page through web user interface.
thijsalkemade@gmail.com
parents:
diff changeset
70 * Limit the number of certificates per user