prosody-modules
4d73a1a6ba68
mod_client_certs/README.markdown

Find changesets by keywords by author, files, the commit message, revision number or hash, or revset expression.

Software / code / prosody-modules

Comparison

mod_client_certs/README.markdown @ 1803:4d73a1a6ba68

Convert all wiki pages to Markdown
author Kim Alvefur <zash@zash.se>
date Fri, 28 Aug 2015 18:03:58 +0200
parent 1782:mod_client_certs/README.wiki@29f3d6b7ad16
comparison
equal deleted inserted replaced
1802:0ab737feada6 1803:4d73a1a6ba68
1 ---
2 labels:
3 - 'Stage-Alpha'
4 summary: 'Client-side certificate management for Prosody'
5 ...
6
7 Introduction
8 ============
9
10 [XEP-0257](http://xmpp.org/extensions/xep-0257.html) specifies a
11 protocol for clients to store and manage client side certificates. When
12 a client presents a stored client side certificate during the TLS
13 handshake, it can log in without supplying a password (using SASL
14 EXTERNAL). This makes it possible to have multiple devices accessing an
15 account, without any of them needing to know the password, and makes it
16 easier to revoke access for a single device.
17
18 Details
19 =======
20
21 Each user can add their own certificates. These do not need to be signed
22 by a trusted CA, yet they do need to be valid at the time of logging in
23 and they should include an subjectAltName with otherName
24 "id-on-xmppAddr" with the JID of the user.
25
26 Generating your certificate
27 ---------------------------
28
29 1. To generate your own certificate with a "id-on-xmppAddr" attribute
30 using the command line `openssl` tool, first create a file called
31 `client.cnf` with contents:
32
33 [req] prompt = no
34 x509_extensions = v3_extensions
35 req_extensions = v3_extensions
36 distinguished_name = distinguished_name
37
38 [v3_extensions]
39 extendedKeyUsage = clientAuth
40 keyUsage = digitalSignature,keyEncipherment
41 basicConstraints = CA:FALSE
42 subjectAltName = @subject_alternative_name
43
44 [subject_alternative_name]
45 otherName.0 =
46 1.3.6.1.5.5.7.8.5;FORMAT:UTF8,UTF8:hamlet@shakespeare.lit
47
48 [distinguished_name]
49 commonName = Your Name
50 emailAddress = hamlet@shakespeare.lit
51
52 2. Replace the values for `otherName.0` and `commonName` and
53 `emailAddress` with your own values. The JID in `otherName.0` can
54 either be a full JID or a bare JID, in the former case, the client
55 can only use the resource specified in the resource. There are many
56 other fields you can add, however, for SASL EXTERNAL, they will have
57 no meaning. You can add more JIDs as `otherName.1`, `otherName.2`,
58 etc.
59 3. Create a private key (as an example, a 4096 bits RSA key):
60
61 openssl genrsa -out client.key 4096
62
63 4. Create the certificate request:
64
65 openssl req -key client.key -new -out client.req -config client.cnf -extensions v3_extensions
66
67 5. Sign it yourself:
68
69 openssl x509 -req -days 365 -in client.req -signkey client.key -out client.crt -extfile client.cnf -extensions v3_extensions
70
71 The 365 means the certificate will be valid for a year starting now.
72
73 The `client.key` **must** be kept secret, and is only needed by clients
74 connecting using this certificate. The `client.crt` file contains the
75 certificate that should be sent to the server using XEP-0257, and is
76 also needed by clients connecting to the server. The `client.req` file
77 is not needed anymore.
78
79 Configuration
80 =============
81
82 (None yet)
83
84 Compatibility
85 =============
86
87 ----- -----------------------------
88 0.9 Works
89 0.8 Untested. Probably doesn't.
90 ----- -----------------------------
91
92 Clients
93 =======
94
95 (None?)
96
97 TODO
98 ====
99
100 Possible options to add to the configuration:
101
102 - Require certificates to be signed by a trusted CA.
103 - Do not require a id-on-xmppAddr
104 - Remove expired certs after a certain time
105 - Limit the number of certificates per user