Mercurial > prosody-modules

comparison mod_http_upload_external/README.markdown @ 2334:c728b2f77c7c

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_http_upload_external: Add README
author Matthew Wild <mwild1@gmail.com>
date Thu, 13 Oct 2016 18:58:53 +0100
parents
children f14bea5da323
comparison
equal deleted inserted replaced
2333:f86478a02b25 2334:c728b2f77c7c
1 ---
2 description: HTTP File Upload (external service)
3 labels: 'Stage-Alpha'
4 ---
5
6 Introduction
7 ============
8
9 This module implements [XEP-0363], which lets clients upload files
10 over HTTP to an external web server.
11
12 This module generates URLs that are signed using a HMAC. Any web service that can authenticate
13 these URLs can be used. There is a PHP implementation available
14 [here](https://hg.prosody.im/prosody-modules/raw-file/tip/mod_http_upload_external/share.php). To
15 implement your own service compatible with this module, check out the implementation notes below (and if you
16 publish your implementation - let us know!).
17
18 Configuration
19 =============
20
21 Add `"http_upload_external"` to modules_enabled in your global section, or under the host(s) you wish
22 to use it on.
23
24 External URL
25 ------------
26
27 You need to provide the path to the external service. Ensure it ends with '/'.
28
29 For example, to use the PHP implementation linked above, you might set it to:
30
31 ``` {.lua}
32 http_upload_external_base_url = "https://your.example.com/path/to/share.php/"
33 ```
34
35 Secret
36 ------
37
38 Set a long and unpredictable string as your secret. This is so the upload service can verify that
39 the upload comes from mod_http_upload_external, and random strangers can't upload to your server.
40
41 ``` {.lua}
42 http_upload_external_secret = "this is a secret string!"
43 ```
44
45 You need to set exactly the same secret string in your external service.
46
47 Limits
48 ------
49
50 A maximum file size can be set by:
51
52 ``` {.lua}
53 http_upload_external_file_size_limit = 123 -- bytes
54 ```
55
56 Default is 100MB (100\*1024\*1024).
57
58 Compatibility
59 =============
60
61 Works with Prosody 0.9.x and later.
62
63 Implementation
64 ==============
65
66 To implement your own external service that is compatible with this module, you need to expose a
67 simple API that allows the HTTP GET, HEAD and PUT methods on arbitrary URLs located on your service.
68
69 For example, if http_upload_external_base_url is set to `https://example.com/upload/` then your service
70 might receive the following requests:
71
72 Upload a new file:
73
74 ```
75 PUT https://example.com/upload/foo/bar.jpg?v=49e9309ff543ace93d25be90635ba8e9965c4f23fc885b2d86c947a5d59e55b2
76 ```
77
78 Recipient checks the file size and other headers:
79
80 ```
81 HEAD https://example.com/upload/foo/bar.jpg
82 ```
83
84 Recipient downloads the file:
85
86 ```
87 GET https://example.com/upload/foo/bar.jpg
88 ```
89
90 The only tricky logic is in validation of the PUT request. Firstly, don't overwrite existing files (return 409 Conflict).
91
92 Then you need to validate the auth token. This will be in the URL query parameter 'v'. If it is absent, fail with 403 Forbidden.
93
94 Calculate the expected auth token by reading the value of the Content-Length header of the PUT request. E.g. for a 1MB file
95 will have a Content-Length of '1048576'. Append this to the uploaded file name, separated by a space (0x20) character.
96
97 For the above example, you would end up with the following string: "foo/bar.jpg 1048576"
98
99 The auth token is a SHA256 HMAC of this string, using the configured secret as the key. E.g.
100
101 ```
102 calculated_auth_token = hmac_sha256("foo/bar.jpg 1048576", "secret string")
103 ```
104
105 If this is not equal to the 'v' parameter provided in the upload URL, reject the upload with 403 Forbidden.
106
107 Note: your language/environment may provide a function for doing a constant-time comparison of these, to guard against
108 timing attacks that may be used to discover the secret key.