aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAnton Khirnov <anton@khirnov.net>2022-09-15 12:59:40 +0200
committerAnton Khirnov <anton@khirnov.net>2022-09-15 12:59:40 +0200
commit6e5ad0c6739864adb8643aa93d9d42d44469ea15 (patch)
treecfbb59028e852417236ae9ab10ff50a1976eda22
parent51461609a05743adae7018932a986e3f4455f55e (diff)
Add a readme file
-rw-r--r--README37
1 files changed, 37 insertions, 0 deletions
diff --git a/README b/README
new file mode 100644
index 0000000..2882216
--- /dev/null
+++ b/README
@@ -0,0 +1,37 @@
+Fshare is a simple Python-based HTTP server for personal ad-hoc file sharing. You upload files in the form of HTTP PUT
+or POST requests and it returns a URL through which the file contents can be retrieved.
+
+Fshare has two modes of operation: private (the default) and public. In the private mode, the generated URLs are
+a HMAC computed from server's private key (which it generates on the first run) and the file contents. They should thus
+be unguessable as long as the server's key remains secret, and so can be used for sharing confidential information -
+only someone in possession of the URL can access the data.
+
+In the public mode (activated by the -P switch), the generated URLs are short and easy to remember - and therefore also
+easy to guess. This mode is useful for sharing non-sensitive data.
+
+Fshare works only with plain HTTP and does no limiting or authentication - anyone can upload data as they wish. In a
+typical setup it should be deployed behind a gateway such as Nginx, that will handle TLS, authentication, request size
+limits, etc.
+
+Fshare should be run as an executable Python script. It takes two mandatory arguments - the state dir and the data dir.
+The state dir contains server runtime data (such as the abovementioned private key), the data dir will contain the
+actual uploaded files.
+
+The data from a PUT/POST request is stored exactly as it was received. E.g. using curl one can upload files with
+ $ curl --data-binary '@<filename>' https://<server location>/pic.jpg
+The server will reply with a URL like
+ https://<server location>/081c5e45316f0c65e945edc4622a8173451d4a808648f5e310ced8a7e079ffdf/pic.jpg
+in the private mode or
+ https://<server location>/f2.jpg
+in the public mode. The data can be retrieved with a HTTP GET request for this URL.
+
+In GET requests, fshare only looks at the basename (i.e. stripping the extension, if any) of the first path component of
+the request location. You can thus add/change the extenion, add further arbitrary path components, or otherwise modify
+it as you wish. As long as the first component is unchanged, the same data will be returned.
+
+In PUT/POST requests, the request location is appended to the generated URL (in the public mode, only the extension of
+the last path component is used). As per the previous paragraph, this is done for convenience only and may be changed at
+will. Requests with an empty location will work as well, then the returned URL will be just the HMAC in the private mode
+and have no extension in the public mode.
+
+Fshare is distributed under the GNU AGPL licence.