Mercurial > prosody-modules
annotate mod_client_certs/README.markdown @ 5193:2bb29ece216b
mod_http_oauth2: Implement stateless dynamic client registration
Replaces previous explicit registration that required either the
additional module mod_adhoc_oauth2_client or manually editing the
database. That method was enough to have something to test with, but
would not probably not scale easily.
Dynamic client registration allows creating clients on the fly, which
may be even easier in theory.
In order to not allow basically unauthenticated writes to the database,
we implement a stateless model here.
per_host_key := HMAC(config -> oauth2_registration_key, hostname)
client_id := JWT { client metadata } signed with per_host_key
client_secret := HMAC(per_host_key, client_id)
This should ensure everything we need to know is part of the client_id,
allowing redirects etc to be validated, and the client_secret can be
validated with only the client_id and the per_host_key.
A nonce injected into the client_id JWT should ensure nobody can submit
the same client metadata and retrieve the same client_secret
author | Kim Alvefur <zash@zash.se> |
---|---|
date | Fri, 03 Mar 2023 21:14:19 +0100 |
parents | 4d73a1a6ba68 |
children |
rev | line source |
---|---|
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
1 --- |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
2 labels: |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
3 - 'Stage-Alpha' |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
4 summary: 'Client-side certificate management for Prosody' |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
5 ... |
1782 | 6 |
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
7 Introduction |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
8 ============ |
1782 | 9 |
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
10 [XEP-0257](http://xmpp.org/extensions/xep-0257.html) specifies a |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
11 protocol for clients to store and manage client side certificates. When |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
12 a client presents a stored client side certificate during the TLS |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
13 handshake, it can log in without supplying a password (using SASL |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
14 EXTERNAL). This makes it possible to have multiple devices accessing an |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
15 account, without any of them needing to know the password, and makes it |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
16 easier to revoke access for a single device. |
1782 | 17 |
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
18 Details |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
19 ======= |
1782 | 20 |
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
21 Each user can add their own certificates. These do not need to be signed |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
22 by a trusted CA, yet they do need to be valid at the time of logging in |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
23 and they should include an subjectAltName with otherName |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
24 "id-on-xmppAddr" with the JID of the user. |
1782 | 25 |
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
26 Generating your certificate |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
27 --------------------------- |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
28 |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
29 1. To generate your own certificate with a "id-on-xmppAddr" attribute |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
30 using the command line `openssl` tool, first create a file called |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
31 `client.cnf` with contents: |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
32 |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
33 [req] prompt = no |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
34 x509_extensions = v3_extensions |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
35 req_extensions = v3_extensions |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
36 distinguished_name = distinguished_name |
1782 | 37 |
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
38 [v3_extensions] |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
39 extendedKeyUsage = clientAuth |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
40 keyUsage = digitalSignature,keyEncipherment |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
41 basicConstraints = CA:FALSE |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
42 subjectAltName = @subject_alternative_name |
1782 | 43 |
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
44 [subject_alternative_name] |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
45 otherName.0 = |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
46 1.3.6.1.5.5.7.8.5;FORMAT:UTF8,UTF8:hamlet@shakespeare.lit |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
47 |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
48 [distinguished_name] |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
49 commonName = Your Name |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
50 emailAddress = hamlet@shakespeare.lit |
1782 | 51 |
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
52 2. Replace the values for `otherName.0` and `commonName` and |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
53 `emailAddress` with your own values. The JID in `otherName.0` can |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
54 either be a full JID or a bare JID, in the former case, the client |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
55 can only use the resource specified in the resource. There are many |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
56 other fields you can add, however, for SASL EXTERNAL, they will have |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
57 no meaning. You can add more JIDs as `otherName.1`, `otherName.2`, |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
58 etc. |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
59 3. Create a private key (as an example, a 4096 bits RSA key): |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
60 |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
61 openssl genrsa -out client.key 4096 |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
62 |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
63 4. Create the certificate request: |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
64 |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
65 openssl req -key client.key -new -out client.req -config client.cnf -extensions v3_extensions |
1782 | 66 |
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
67 5. Sign it yourself: |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
68 |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
69 openssl x509 -req -days 365 -in client.req -signkey client.key -out client.crt -extfile client.cnf -extensions v3_extensions |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
70 |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
71 The 365 means the certificate will be valid for a year starting now. |
1782 | 72 |
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
73 The `client.key` **must** be kept secret, and is only needed by clients |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
74 connecting using this certificate. The `client.crt` file contains the |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
75 certificate that should be sent to the server using XEP-0257, and is |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
76 also needed by clients connecting to the server. The `client.req` file |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
77 is not needed anymore. |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
78 |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
79 Configuration |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
80 ============= |
1782 | 81 |
82 (None yet) | |
83 | |
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
84 Compatibility |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
85 ============= |
1782 | 86 |
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
87 ----- ----------------------------- |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
88 0.9 Works |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
89 0.8 Untested. Probably doesn't. |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
90 ----- ----------------------------- |
1782 | 91 |
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
92 Clients |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
93 ======= |
1782 | 94 |
95 (None?) | |
96 | |
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
97 TODO |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
98 ==== |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
99 |
1782 | 100 Possible options to add to the configuration: |
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
101 |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
102 - Require certificates to be signed by a trusted CA. |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
103 - Do not require a id-on-xmppAddr |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
104 - Remove expired certs after a certain time |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1782
diff
changeset
|
105 - Limit the number of certificates per user |