Complete README and LICENSE. Ready to make it public!

2 files changed, 70 insertions, 11 deletions

diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..7a36d50
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 Adrien Wu, Arthur Wang, Hsiang-Jui Lin, Hsing-Yu Chen, Yang Han Li
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
index ac2fee0..d13eabe 100644
--- a/README.md
+++ b/README.md
@@ -1,21 +1,59 @@
-# NTU CNS Final Project
+# TorFS: Abusing Tor Onion service to store data
 
-## API
+## Authors
 
-### Start API Server
+* __Arthur Wang__, __Hsiang-Jui Lin__: Tor hidden service storage and virtual file system
+* __Hsing-Yu Chen__: Data block API
+* __Adrien Wu__, __Yang Han Li__: Reports and documentation
 
-Suppose the storage server is running on the same machine as your API server, and it is expecting gRPC requests via listening on port `8081`, then you will replace `ip:port` in the line below with `:8081`.
+## About this project
 
-`go run API.go chunk.pb.go -server "ip:port"`
+The TorFS project was initialted as a final project in [NTU Cryptography and Network Security course](https://www.csie.ntu.edu.tw/~hchsiao/courses/cns19.html). It was motivated by [dnsfs](https://github.com/benjojo/dnsfs) and [pingfs](https://github.com/yarrick/pingfs). We explored similar idea, that exploits storage from protocols which was not intended for this purpose, and discovered Tor hidden services can be regarded as reliable data storage.
 
-### Interact with API Server
+## How TorFS works
 
-Suppose the API server is running on the same machine as that of the client, the `curl` commands used to upload and download storage objects are listed below.
+To know about how TorFS works, we have to understand Onion services (formerly, hidden services). It provides anonymity to websites and other services beneath Tor's Onion network. Tor website already has a good [introduction](https://www.torproject.org/docs/onion-services.html.en). It deserves 10 minutes reading.
 
-#### Upload API
+To setup an Onion service, we generate a private/public long-term key pair for our service. Currently it allows Ed25519 or RSA1024 keys. We then advertise our service, named XYZ.onion or some. Tor does so by asking _introduction points_, basically Tor relays, to store our public keys. Whoever client visiting our service should learn about our public key, and setups up a _rendezvous point_.
 
-`curl localhost:8080/upload?name=storage_object_name --data-binary @file_to_be_uploaded`
+We have to make a stop here. We only need to store data without an actual service. It turns out the _introduction points_, along with our public key, can survive even the actual service is absent. As you can figure out, we put the stuffs into public keys and retrieve them back using _.onion_ addresses! That's basically how TorFS works.
 
-#### Download APi
+To state in details, we derived an algorithm to generate 1024-bit long RSA keys, 800 of 1024-bits is arbitrary data in the _n_ component (product of two primes). We manipulate remaining bits to satisfy RSA's constraints. We build a virtual file system that slice the files into 800-bit blocks, and map the replicas into _.onion_ addresses.
 
-`curl localhost:8080/download?name=storage_object_name > file_containing_downloaded_object`
+## Demo usage
+
+Since the our code uses async features, it requires Python 3.7 minimum.
+
+Install depent pacakges using `pip` or other package manager:
+
+```sh
+pip3 install -r requirements.txt
+```
+
+You can start a TorFS shell by `python3 ./src/main.py`.
+
+```
+torfs> help                        # Ask help to learn about command usages
+torfs> cp @demo/demo.jpg demo.jpg  # Upload our demo.jpg to Tor network
+torfs> ls .                        # List directory in virtual fs
+demo.jpg
+torfs> cp demo.jpg @demo_copy.jpg  # Download the file back
+torfs> exit
+```
+
+Following the demo above, we expect identical file contents.
+
+```
+$ sha256sum demo_copy.jpg demo/demo.jpg
+b053f4e17afa4c40d54fbf24caf5702e2db0935ee71f5333991b29da94de07d8  demo_copy.jpg
+b053f4e17afa4c40d54fbf24caf5702e2db0935ee71f5333991b29da94de07d8  demo/demo.jpg
+```
+
+## Disclaimer
+
+* The project is intended to as a proof-of-concept and for educational purpose. Do NOT distribute it for malicious means.
+* We have limited time to complete our project. The code is not guaranteed to be bug-free, and thus not suggested for production use.
+
+## License
+
+MIT