prosody-modules
502963b86fbc
mod_http_upload_external/README.md

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

Software / code / prosody-modules

Annotate

mod_http_upload_external/README.md @ 6297:502963b86fbc

:multble modules: fix tab-> space diff --git a/mod_admin_blocklist/README.md b/mod_admin_blocklist/README.md --- a/mod_admin_blocklist/README.md +++ b/mod_admin_blocklist/README.md @@ -24,9 +24,9 @@ admin_blocklist_roles = { "prosody:opera # Compatibility Prosody-Version Status - -------------- ------ - trunk* Works - 13 Works - 0.12 Works + ------------ ------ + trunk* Works + 13 Works + 0.12 Works *as of 2025-06-13 diff --git a/mod_csi_grace_period/README.md b/mod_csi_grace_period/README.md --- a/mod_csi_grace_period/README.md +++ b/mod_csi_grace_period/README.md @@ -16,9 +16,9 @@ pocket is not the best use of radio time Works with [mod_csi_simple][doc:modules:mod_csi_simple] which is included with Prosody. - ------- ------- - trunk* Works - 13 Works - 0.12 Works + ------- ------- + trunk* Works + 13 Works + 0.12 Works *as of 2025-06-13 diff --git a/mod_http_upload_external/README.md b/mod_http_upload_external/README.md --- a/mod_http_upload_external/README.md +++ b/mod_http_upload_external/README.md @@ -87,10 +87,10 @@ Compatibility ============= Prosody-Version Status - ---------------- -------------------- - trunk Works as of 25-06-13 - 13 Works - 0.12 Works + ---------------- -------------------- + trunk Works as of 25-06-13 + 13 Works + 0.12 Works Implementation ============== diff --git a/mod_muc_moderation/README.md b/mod_muc_moderation/README.md --- a/mod_muc_moderation/README.md +++ b/mod_muc_moderation/README.md @@ -27,11 +27,10 @@ modules_enabled = { # Compatibility - ------- --------------- - trunk Works^[as of 2025-06-13] - 13 Works - 0.12 Works - ------- --------------- + ------- --------------- + trunk Works^[as of 2025-06-13] + 13 Works + 0.12 Works ## XEP version diff --git a/mod_s2s_idle_timeout/README.md b/mod_s2s_idle_timeout/README.md --- a/mod_s2s_idle_timeout/README.md +++ b/mod_s2s_idle_timeout/README.md @@ -25,10 +25,9 @@ Compatibility ============= Prosody Version Status - ----------------- ----------- - trunk[^1] Works - 13 Works - 0.12 Works - ----------------- ----------- + ----------------- ----------- + trunk[^1] Works + 13 Works + 0.12 Works [^1]: as of 2025-06-13 diff --git a/mod_s2s_keepalive/README.md b/mod_s2s_keepalive/README.md --- a/mod_s2s_keepalive/README.md +++ b/mod_s2s_keepalive/README.md @@ -34,10 +34,9 @@ Compatibility ============= Prosody Version Status - ----------------- ----------- - trunk[^1] Works - 13 Works - 0.12 Works - ----------------- ----------- + ----------------- ----------- + trunk[^1] Works + 13 Works + 0.12 Works [^1]: as of 2025-06-13
author Menel <menel@snikket.de>
date Fri, 13 Jun 2025 09:58:51 +0200
parent 6296:1661f6a74141
child 6306:fe0a58b863db
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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)
3189
57332ea0c1c7 mod_http_upload_external/README: Add Perl implementation by Holger to list
Kim Alvefur <zash@zash.se>
parents: 3168
diff changeset
22 * [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
23 * [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
24
4509
16995e7624f0 mod_http_upload_external: add access control option
Nicolas Cedilnik <nicoco@nicoco.fr>
parents: 3959
diff changeset
25 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
26 (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
27
c728b2f77c7c mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
28 Configuration
c728b2f77c7c mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
29 =============
c728b2f77c7c mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
30
3959
5741e6511f3d mod_http_upload_external: Discourage loading via modules_enabled
Kim Alvefur <zash@zash.se>
parents: 3360
diff changeset
31 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
32
5741e6511f3d mod_http_upload_external: Discourage loading via modules_enabled
Kim Alvefur <zash@zash.se>
parents: 3360
diff changeset
33 ``` {.lua}
5741e6511f3d mod_http_upload_external: Discourage loading via modules_enabled
Kim Alvefur <zash@zash.se>
parents: 3360
diff changeset
34 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
35 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
36 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
37 ```
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 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
40
2334
c728b2f77c7c mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
41
c728b2f77c7c mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
42 External URL
c728b2f77c7c mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
43 ------------
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 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
46
c728b2f77c7c mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
47 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
48
c728b2f77c7c mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
49 ``` {.lua}
c728b2f77c7c mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
50 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
51 ```
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 Secret
c728b2f77c7c mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
54 ------
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 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
57 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
58
c728b2f77c7c mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
59 ``` {.lua}
c728b2f77c7c mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
60 http_upload_external_secret = "this is a secret string!"
c728b2f77c7c mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
61 ```
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 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
64
c728b2f77c7c mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
65 Limits
c728b2f77c7c mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
66 ------
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 A maximum file size can be set by:
c728b2f77c7c mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
69
c728b2f77c7c mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
70 ``` {.lua}
c728b2f77c7c mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
71 http_upload_external_file_size_limit = 123 -- bytes
c728b2f77c7c mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
72 ```
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 Default is 100MB (100\*1024\*1024).
c728b2f77c7c mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
75
4509
16995e7624f0 mod_http_upload_external: add access control option
Nicolas Cedilnik <nicoco@nicoco.fr>
parents: 3959
diff changeset
76 Access
16995e7624f0 mod_http_upload_external: add access control option
Nicolas Cedilnik <nicoco@nicoco.fr>
parents: 3959
diff changeset
77 ------
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 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
80 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
81
16995e7624f0 mod_http_upload_external: add access control option
Nicolas Cedilnik <nicoco@nicoco.fr>
parents: 3959
diff changeset
82 ``` {.lua}
5863
fba64b043c52 mod_http_upload_external: Fix typo in access documentation.
aidan@jmad.org
parents: 4556
diff changeset
83 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
84 ```
16995e7624f0 mod_http_upload_external: add access control option
Nicolas Cedilnik <nicoco@nicoco.fr>
parents: 3959
diff changeset
85
2334
c728b2f77c7c mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
86 Compatibility
c728b2f77c7c mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
87 =============
c728b2f77c7c mod_http_upload_external: Add README
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
88
6093
c359259a494d mod_http_upload_external: add external service and update Compatibility.
Menel <menel@snikket.de>
parents: 6003
diff changeset
89 Prosody-Version Status
6297
502963b86fbc :multble modules: fix tab-> space
Menel <menel@snikket.de>
parents: 6296
diff changeset
90 ---------------- --------------------
502963b86fbc :multble modules: fix tab-> space
Menel <menel@snikket.de>
parents: 6296
diff changeset
91 trunk Works as of 25-06-13
502963b86fbc :multble modules: fix tab-> space
Menel <menel@snikket.de>
parents: 6296
diff changeset
92 13 Works
502963b86fbc :multble modules: fix tab-> space
Menel <menel@snikket.de>
parents: 6296
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 ```