Mercurial > prosody-modules

comparison mod_client_certs/README.wiki @ 1782:29f3d6b7ad16

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Import wiki pages
author Kim Alvefur <zash@zash.se>
date Mon, 24 Aug 2015 16:43:56 +0200
parents
children
comparison
equal deleted inserted replaced
1781:12ac88940fe3 1782:29f3d6b7ad16
1 #summary Client-side certificate management for Prosody
2 #labels Stage-Alpha
3
4 = Introduction =
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.
6
7
8 = Details =
9
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.
11
12 == Generating your certificate ==
13
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:
15 {{{
16 [req]
17 prompt = no
18 x509_extensions = v3_extensions
19 req_extensions = v3_extensions
20 distinguished_name = distinguished_name
21
22 [v3_extensions]
23 extendedKeyUsage = clientAuth
24 keyUsage = digitalSignature,keyEncipherment
25 basicConstraints = CA:FALSE
26 subjectAltName = @subject_alternative_name
27
28 [subject_alternative_name]
29 otherName.0 = 1.3.6.1.5.5.7.8.5;FORMAT:UTF8,UTF8:hamlet@shakespeare.lit
30
31 [distinguished_name]
32 commonName = Your Name
33 emailAddress = hamlet@shakespeare.lit
34 }}}
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.
36 # Create a private key (as an example, a 4096 bits RSA key):
37 {{{
38 openssl genrsa -out client.key 4096
39 }}}
40 # Create the certificate request:
41 {{{
42 openssl req -key client.key -new -out client.req -config client.cnf -extensions v3_extensions
43 }}}
44 # Sign it yourself:
45 {{{
46 openssl x509 -req -days 365 -in client.req -signkey client.key -out client.crt -extfile client.cnf -extensions v3_extensions
47 }}}
48 The 365 means the certificate will be valid for a year starting now.
49
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.
51
52 = Configuration =
53
54 (None yet)
55
56 = Compatibility =
57
58 ||0.9||Works||
59 ||0.8||Untested. Probably doesn't.||
60
61 = Clients =
62
63 (None?)
64
65 = TODO =
66 Possible options to add to the configuration:
67 * Require certificates to be signed by a trusted CA.
68 * Do not require a id-on-xmppAddr
69 * Remove expired certs after a certain time
70 * Limit the number of certificates per user