From 6e5ad0c6739864adb8643aa93d9d42d44469ea15 Mon Sep 17 00:00:00 2001 From: Anton Khirnov Date: Thu, 15 Sep 2022 12:59:40 +0200 Subject: Add a readme file --- README | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) create mode 100644 README 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 '@' https:///pic.jpg +The server will reply with a URL like + https:///081c5e45316f0c65e945edc4622a8173451d4a808648f5e310ced8a7e079ffdf/pic.jpg +in the private mode or + https:///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. -- cgit v1.2.3