Software / code / prosody-modules
Annotate
mod_http_upload_external/README.md @ 6191:94399ad6b5ab
mod_invites_register_api: Use set_password() for password resets
Previously the code relied on the (weird) behaviour of create_user(), which
would update the password for a user account if it already existed. This has
several issues, and we plan to deprecate this behaviour of create_user().
The larger issue is that this route does not trigger the user-password-changed
event, which can be a security problem. For example, it did not disconnect
existing user sessions (this occurs in mod_c2s in response to the event).
Switching to set_password() is the right thing to do.
| author | Matthew Wild <mwild1@gmail.com> |
|---|---|
| date | Thu, 06 Feb 2025 10:13:39 +0000 |
| parent | 6093:c359259a494d |
| child | 6211:750d64c47ec6 |
| rev | line source |
|---|---|
|
2334
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
1 --- |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
2 description: HTTP File Upload (external service) |
|
5923
694b62d8a82f
various/README: Fix 'labels' metadata, should be a list
Kim Alvefur <zash@zash.se>
parents:
5863
diff
changeset
|
3 labels: |
|
6093
c359259a494d
mod_http_upload_external: add external service and update Compatibility.
Menel <menel@snikket.de>
parents:
6003
diff
changeset
|
4 - Stage-Beta |
|
2334
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
5 --- |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
6 |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
7 Introduction |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
8 ============ |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
9 |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
10 This module implements [XEP-0363], which lets clients upload files |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
11 over HTTP to an external web server. |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
12 |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
13 This module generates URLs that are signed using a HMAC. Any web service that can authenticate |
|
4509
16995e7624f0
mod_http_upload_external: add access control option
Nicolas Cedilnik <nicoco@nicoco.fr>
parents:
3959
diff
changeset
|
14 these URLs can be used. |
|
2823
f14bea5da323
mod_http_upload_external: add Python service implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
2334
diff
changeset
|
15 |
|
f14bea5da323
mod_http_upload_external: add Python service implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
2334
diff
changeset
|
16 Implementations |
|
f14bea5da323
mod_http_upload_external: add Python service implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
2334
diff
changeset
|
17 --------------- |
|
f14bea5da323
mod_http_upload_external: add Python service implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
2334
diff
changeset
|
18 |
|
f14bea5da323
mod_http_upload_external: add Python service implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
2334
diff
changeset
|
19 * [PHP implementation](https://hg.prosody.im/prosody-modules/raw-file/tip/mod_http_upload_external/share.php) |
|
f14bea5da323
mod_http_upload_external: add Python service implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
2334
diff
changeset
|
20 * [Python3+Flask implementation](https://github.com/horazont/xmpp-http-upload) |
|
3168
73a610c3c7a9
mod_http_external: Link to prosody-filer (Go implementation)
Matthew Wild <mwild1@gmail.com>
parents:
2823
diff
changeset
|
21 * [Go implementation, Prosody Filer](https://github.com/ThomasLeister/prosody-filer) |
|
6093
c359259a494d
mod_http_upload_external: add external service and update Compatibility.
Menel <menel@snikket.de>
parents:
6003
diff
changeset
|
22 * [Go implementation, HMAC File Server](https://github.com/PlusOne/hmac-file-server) |
|
3189
57332ea0c1c7
mod_http_upload_external/README: Add Perl implementation by Holger to list
Kim Alvefur <zash@zash.se>
parents:
3168
diff
changeset
|
23 * [Perl implementation for nginx](https://github.com/weiss/ngx_http_upload) |
|
5933
070b0db6c4a0
mod_http_upload_external: Add link to Rust implementation (Thanks Luna)
Kim Alvefur <zash@zash.se>
parents:
5923
diff
changeset
|
24 * [Rust implementation](https://gitlab.com/nyovaya/xmpp-http-upload) |
|
2823
f14bea5da323
mod_http_upload_external: add Python service implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
2334
diff
changeset
|
25 |
|
4509
16995e7624f0
mod_http_upload_external: add access control option
Nicolas Cedilnik <nicoco@nicoco.fr>
parents:
3959
diff
changeset
|
26 To implement your own service compatible with this module, check out the implementation notes below |
|
2823
f14bea5da323
mod_http_upload_external: add Python service implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
2334
diff
changeset
|
27 (and if you publish your implementation - let us know!). |
|
2334
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
28 |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
29 Configuration |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
30 ============= |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
31 |
|
3959
5741e6511f3d
mod_http_upload_external: Discourage loading via modules_enabled
Kim Alvefur <zash@zash.se>
parents:
3360
diff
changeset
|
32 The module can be added as a new Component definition: |
|
5741e6511f3d
mod_http_upload_external: Discourage loading via modules_enabled
Kim Alvefur <zash@zash.se>
parents:
3360
diff
changeset
|
33 |
|
5741e6511f3d
mod_http_upload_external: Discourage loading via modules_enabled
Kim Alvefur <zash@zash.se>
parents:
3360
diff
changeset
|
34 ``` {.lua} |
|
5741e6511f3d
mod_http_upload_external: Discourage loading via modules_enabled
Kim Alvefur <zash@zash.se>
parents:
3360
diff
changeset
|
35 Component "upload.example.org" "http_upload_external" |
|
5741e6511f3d
mod_http_upload_external: Discourage loading via modules_enabled
Kim Alvefur <zash@zash.se>
parents:
3360
diff
changeset
|
36 http_upload_external_base_url = "https://your.example.com/upload/service" |
|
5741e6511f3d
mod_http_upload_external: Discourage loading via modules_enabled
Kim Alvefur <zash@zash.se>
parents:
3360
diff
changeset
|
37 http_upload_external_secret = "your shared secret" |
|
5741e6511f3d
mod_http_upload_external: Discourage loading via modules_enabled
Kim Alvefur <zash@zash.se>
parents:
3360
diff
changeset
|
38 ``` |
|
5741e6511f3d
mod_http_upload_external: Discourage loading via modules_enabled
Kim Alvefur <zash@zash.se>
parents:
3360
diff
changeset
|
39 |
|
5741e6511f3d
mod_http_upload_external: Discourage loading via modules_enabled
Kim Alvefur <zash@zash.se>
parents:
3360
diff
changeset
|
40 It should **not** be added to modules_enabled. |
|
5741e6511f3d
mod_http_upload_external: Discourage loading via modules_enabled
Kim Alvefur <zash@zash.se>
parents:
3360
diff
changeset
|
41 |
|
2334
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
42 |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
43 External URL |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
44 ------------ |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
45 |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
46 You need to provide the path to the external service. Ensure it ends with '/'. |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
47 |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
48 For example, to use the PHP implementation linked above, you might set it to: |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
49 |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
50 ``` {.lua} |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
51 http_upload_external_base_url = "https://your.example.com/path/to/share.php/" |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
52 ``` |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
53 |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
54 Secret |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
55 ------ |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
56 |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
57 Set a long and unpredictable string as your secret. This is so the upload service can verify that |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
58 the upload comes from mod_http_upload_external, and random strangers can't upload to your server. |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
59 |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
60 ``` {.lua} |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
61 http_upload_external_secret = "this is a secret string!" |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
62 ``` |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
63 |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
64 You need to set exactly the same secret string in your external service. |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
65 |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
66 Limits |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
67 ------ |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
68 |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
69 A maximum file size can be set by: |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
70 |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
71 ``` {.lua} |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
72 http_upload_external_file_size_limit = 123 -- bytes |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
73 ``` |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
74 |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
75 Default is 100MB (100\*1024\*1024). |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
76 |
|
4509
16995e7624f0
mod_http_upload_external: add access control option
Nicolas Cedilnik <nicoco@nicoco.fr>
parents:
3959
diff
changeset
|
77 Access |
|
16995e7624f0
mod_http_upload_external: add access control option
Nicolas Cedilnik <nicoco@nicoco.fr>
parents:
3959
diff
changeset
|
78 ------ |
|
16995e7624f0
mod_http_upload_external: add access control option
Nicolas Cedilnik <nicoco@nicoco.fr>
parents:
3959
diff
changeset
|
79 |
|
16995e7624f0
mod_http_upload_external: add access control option
Nicolas Cedilnik <nicoco@nicoco.fr>
parents:
3959
diff
changeset
|
80 You may want to give upload access to additional entities such as components |
|
5863
fba64b043c52
mod_http_upload_external: Fix typo in access documentation.
aidan@jmad.org
parents:
4556
diff
changeset
|
81 by using the `http_upload_external_access` config option. |
|
4509
16995e7624f0
mod_http_upload_external: add access control option
Nicolas Cedilnik <nicoco@nicoco.fr>
parents:
3959
diff
changeset
|
82 |
|
16995e7624f0
mod_http_upload_external: add access control option
Nicolas Cedilnik <nicoco@nicoco.fr>
parents:
3959
diff
changeset
|
83 ``` {.lua} |
|
5863
fba64b043c52
mod_http_upload_external: Fix typo in access documentation.
aidan@jmad.org
parents:
4556
diff
changeset
|
84 http_upload_external_access = {"gateway.example.com"}; |
|
4509
16995e7624f0
mod_http_upload_external: add access control option
Nicolas Cedilnik <nicoco@nicoco.fr>
parents:
3959
diff
changeset
|
85 ``` |
|
16995e7624f0
mod_http_upload_external: add access control option
Nicolas Cedilnik <nicoco@nicoco.fr>
parents:
3959
diff
changeset
|
86 |
|
2334
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
87 Compatibility |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
88 ============= |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
89 |
|
6093
c359259a494d
mod_http_upload_external: add external service and update Compatibility.
Menel <menel@snikket.de>
parents:
6003
diff
changeset
|
90 Prosody-Version Status |
|
c359259a494d
mod_http_upload_external: add external service and update Compatibility.
Menel <menel@snikket.de>
parents:
6003
diff
changeset
|
91 ---------------- -------------------- |
|
c359259a494d
mod_http_upload_external: add external service and update Compatibility.
Menel <menel@snikket.de>
parents:
6003
diff
changeset
|
92 trunk Works as of 24-12-12 |
|
c359259a494d
mod_http_upload_external: add external service and update Compatibility.
Menel <menel@snikket.de>
parents:
6003
diff
changeset
|
93 0.12 Works |
|
2334
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
94 |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
95 Implementation |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
96 ============== |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
97 |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
98 To implement your own external service that is compatible with this module, you need to expose a |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
99 simple API that allows the HTTP GET, HEAD and PUT methods on arbitrary URLs located on your service. |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
100 |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
101 For example, if http_upload_external_base_url is set to `https://example.com/upload/` then your service |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
102 might receive the following requests: |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
103 |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
104 Upload a new file: |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
105 |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
106 ``` |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
107 PUT https://example.com/upload/foo/bar.jpg?v=49e9309ff543ace93d25be90635ba8e9965c4f23fc885b2d86c947a5d59e55b2 |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
108 ``` |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
109 |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
110 Recipient checks the file size and other headers: |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
111 |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
112 ``` |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
113 HEAD https://example.com/upload/foo/bar.jpg |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
114 ``` |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
115 |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
116 Recipient downloads the file: |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
117 |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
118 ``` |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
119 GET https://example.com/upload/foo/bar.jpg |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
120 ``` |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
121 |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
122 The only tricky logic is in validation of the PUT request. Firstly, don't overwrite existing files (return 409 Conflict). |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
123 |
|
3358
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
124 Then you need to validate the auth token. |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
125 |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
126 ### Validating the auth token |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
127 |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
128 |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
129 | Version | Supports | |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
130 |:--------|:--------------------------------------------------------------------------------------------------------| |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
131 | v | Validates only filename and size. Does not support file type restrictions by the XMPP server. | |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
132 | v2 | Validates the filename, size and MIME type. This allows the server to implement MIME type restrictions. | |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
133 |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
134 It is probable that a future v3 will be specified that allows carrying information about the uploader identity, allowing |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
135 the implementation of per-user quotas and limits. |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
136 |
|
3360
0149954cee37
mod_http_upload_external: Add note about correct behaviour in the presence of multiple versions
Matthew Wild <mwild1@gmail.com>
parents:
3359
diff
changeset
|
137 Implementations may implement one or more versions of the protocol simultaneously. The XMPP server generates the URLs and |
|
0149954cee37
mod_http_upload_external: Add note about correct behaviour in the presence of multiple versions
Matthew Wild <mwild1@gmail.com>
parents:
3359
diff
changeset
|
138 ultimately selects which version will be used. |
|
0149954cee37
mod_http_upload_external: Add note about correct behaviour in the presence of multiple versions
Matthew Wild <mwild1@gmail.com>
parents:
3359
diff
changeset
|
139 |
|
0149954cee37
mod_http_upload_external: Add note about correct behaviour in the presence of multiple versions
Matthew Wild <mwild1@gmail.com>
parents:
3359
diff
changeset
|
140 XMPP servers MUST only generate URLs with **one** of the versions listed here. However in case multiple parameters are |
|
0149954cee37
mod_http_upload_external: Add note about correct behaviour in the presence of multiple versions
Matthew Wild <mwild1@gmail.com>
parents:
3359
diff
changeset
|
141 present, upload services MUST **only** use the token from the highest parameter version that they support. |
|
3358
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
142 |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
143 #### Version 1 (v) |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
144 |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
145 The token will be in the URL query parameter 'v'. If it is absent, fail with 403 Forbidden. |
|
2334
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
146 |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
147 Calculate the expected auth token by reading the value of the Content-Length header of the PUT request. E.g. for a 1MB file |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
148 will have a Content-Length of '1048576'. Append this to the uploaded file name, separated by a space (0x20) character. |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
149 |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
150 For the above example, you would end up with the following string: "foo/bar.jpg 1048576" |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
151 |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
152 The auth token is a SHA256 HMAC of this string, using the configured secret as the key. E.g. |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
153 |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
154 ``` |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
155 calculated_auth_token = hmac_sha256("foo/bar.jpg 1048576", "secret string") |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
156 ``` |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
157 |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
158 If this is not equal to the 'v' parameter provided in the upload URL, reject the upload with 403 Forbidden. |
|
c728b2f77c7c
mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
159 |
|
3358
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
160 **Security note:** When comparing `calculated_auth_token` with the token provided in the URL, you must use a constant-time string |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
161 comparison, otherwise an attacker may be able to discover your secret key. Most languages/environments provide such a function, such |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
162 as `hash_equals()` in PHP, `hmac.compare_digest()` in Python, or `ConstantTimeCompare()` from `crypto/subtle` in Go. |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
163 |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
164 #### Version 2 (v2) |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
165 |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
166 The token will be in the URL query parameter 'v2'. If it is absent, fail with 403 Forbidden. |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
167 |
|
4556
c149edb37349
Fix mentions of 'Content-Size' (should be Content-Length) (thanks Roobre)
Matthew Wild <mwild1@gmail.com>
parents:
4509
diff
changeset
|
168 | Input | Example |Read from | |
|
c149edb37349
Fix mentions of 'Content-Size' (should be Content-Length) (thanks Roobre)
Matthew Wild <mwild1@gmail.com>
parents:
4509
diff
changeset
|
169 |:----------------|:------------|:--------------------------------------------------------------------| |
|
c149edb37349
Fix mentions of 'Content-Size' (should be Content-Length) (thanks Roobre)
Matthew Wild <mwild1@gmail.com>
parents:
4509
diff
changeset
|
170 |`file_path` | foo/bar.jpg | The URL of the PUT request, with the service's base prefix removed. | |
|
c149edb37349
Fix mentions of 'Content-Size' (should be Content-Length) (thanks Roobre)
Matthew Wild <mwild1@gmail.com>
parents:
4509
diff
changeset
|
171 |`content_length` | 1048576 | Content-Length header | |
|
c149edb37349
Fix mentions of 'Content-Size' (should be Content-Length) (thanks Roobre)
Matthew Wild <mwild1@gmail.com>
parents:
4509
diff
changeset
|
172 |`content_type` | image/jpeg | Content-Type header | |
|
3358
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
173 |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
174 The parameters should be joined into a single string, separated by NUL bytes (`\0`): |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
175 |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
176 ``` |
|
4556
c149edb37349
Fix mentions of 'Content-Size' (should be Content-Length) (thanks Roobre)
Matthew Wild <mwild1@gmail.com>
parents:
4509
diff
changeset
|
177 signed_string = ( file_path + '\0' + content_length + '\0' + content_type ) |
|
3358
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
178 ``` |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
179 |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
180 ``` |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
181 signed_string = "foo/bar.jpg\01048576\0image/jpeg" |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
182 ``` |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
183 |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
184 The expected auth token is the SHA256 HMAC of this string, using the configured secret key as the key. E.g.: |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
185 |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
186 ``` |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
187 calculated_auth_token = hmac_sha256(signed_string, "secret string") |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
188 ``` |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
189 |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
190 If this is not equal to the 'v2' parameter provided in the upload URL, reject the upload with 403 Forbidden. |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
191 |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
192 **Security note:** When comparing `calculated_auth_token` with the token provided in the URL, you must use a constant-time string |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
193 comparison, otherwise an attacker may be able to discover your secret key. Most languages/environments provide such a function, such |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
194 as `hash_equals()` in PHP, `hmac.compare_digest()` in Python, or `ConstantTimeCompare()` from `crypto/subtle` in Go. |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
195 |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
196 ### Security considerations |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
197 |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
198 #### HTTPS |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
199 |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
200 All uploads and downloads should only be over HTTPS. The security of the served content is protected only |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
201 by the uniqueness present in the URLs themselves, and not using HTTPS may leak the URLs and contents to third-parties. |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
202 |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
203 Implementations should consider including HSTS and HPKP headers, with consent of the administrator. |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
204 |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
205 #### MIME types |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
206 |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
207 If the upload Content-Type header matches any of the following MIME types, it MUST be preserved and included in the Content-Type |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
208 of any GET requests made to download the file: |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
209 |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
210 - `image/*` |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
211 - `video/*` |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
212 - `audio/*` |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
213 - `text/plain` |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
214 |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
215 It is recommended that other MIME types are preserved, but served with the addition of the following header: |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
216 |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
217 ``` |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
218 Content-Disposition: attachment |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
219 ``` |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
220 |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
221 This prevents the browser interpreting scripts and other resources that may potentially be malicious. |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
222 |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
223 Some browsers may also benefit from explicitly telling them not to try guessing the type of a file: |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
224 |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
225 ``` |
|
3359
3d01ab6b1186
mod_http_upload_external: Fix typo/copy-paste issues in headers (thanks jonas<U+2019>)
Matthew Wild <mwild1@gmail.com>
parents:
3358
diff
changeset
|
226 X-Content-Type-Options: nosniff |
|
3358
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
227 ``` |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
228 |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
229 #### Security headers |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
230 |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
231 The following headers should be included to provide additional sandboxing of resources, considering the uploaded |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
232 content is not understood or trusted by the upload service: |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
233 |
|
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
234 ``` |
|
3359
3d01ab6b1186
mod_http_upload_external: Fix typo/copy-paste issues in headers (thanks jonas<U+2019>)
Matthew Wild <mwild1@gmail.com>
parents:
3358
diff
changeset
|
235 Content-Security-Policy: default-src 'none' |
|
3d01ab6b1186
mod_http_upload_external: Fix typo/copy-paste issues in headers (thanks jonas<U+2019>)
Matthew Wild <mwild1@gmail.com>
parents:
3358
diff
changeset
|
236 X-Content-Security-Policy: default-src 'none' |
|
3d01ab6b1186
mod_http_upload_external: Fix typo/copy-paste issues in headers (thanks jonas<U+2019>)
Matthew Wild <mwild1@gmail.com>
parents:
3358
diff
changeset
|
237 X-WebKit-CSP: default-src 'none' |
|
3358
e49660ba3161
mod_http_upload_external: Improve implementation docs, including v2 details
Matthew Wild <mwild1@gmail.com>
parents:
3189
diff
changeset
|
238 ``` |
