Repository navigation
DISTRESS Usage Document
This is a guide on how to set up and run the DISTRESS system. DISTRESS is a distributed, encrypted file storage system. It was designed to be extensible and distributed across an arbitrary set of server nodes. To add a file to the system, run the DISTRESS client, while connecting to a running DISTRESS server.
When adding a file to the DISTRESS system, it is split into 1024-byte chunks, each encrypted by the same key. These chunks are stored in the DISTRESS server, and may be distributed across many servers in the future. The only way to reassemble these chunks into the original file is with the *.receipt file associated with each entry into DISTRESS. This *.receipt file describes which chunks are a part of the file, where they go when reassembled, and the critical information needed to decrypt each chunk. To retrieve, decrypt, or delete a file requires the associated *.receipt file with permissions granted by the original creator of the file. More on receipt files can be found in the descriptions of the import and export commands below.
DISTRESS can currently be installed on UNIX systems. To install the DISTRESS server, you must have Erlang installed.
If you have Erlang version R15B01 or later, just run make in the root directory.
If you have Erlang version R15B or older, you can run make oldcompile in the server directory.
The DISTRESS client does not require any installation or building.
To run the DISTRESS server after it has been built, run ./distressd. This will start the server on the local machine. This handles the key-value store for all files stored on the network. The current implementation lacks P2P replication capabilities, but running a single node should suffice for preliminary testing.
Before you can use the DISTRESS network, you must connect the client to a running server. Running the client requires Python 2.7.
The DISTRESS client defaults to connecting to a DISTRESS server on the local machine (localhost) and on port 65501. If you are running the server on a different server, you can change network settings by editing the configuration file located at ~/.config/distress/config. Here you can change your global encryption key, the network location of the connected DISTRESS server, and the location of your library file.
This library file is where your receipts will be stored. Feel free to, after storing the desired files, move it to a more secure location (such as a hidden partition).
To run the DISTRESS server, run the ./distress file in the cli directory. For a list of commands available to you, run ./distress -help. More information can be found on each command by running ./distress <command> -help. Current commands we have implemented include:
./distress add [options] <filepath> - Adds the selected file to the DISTRESS server. The file is encrypted and split into file chunks automatically and invisibly. Options include the ability to delete the file at a later date, use a custom encryption key, or adding multiple files/directories.
./distress get [options] <nameid> - Gets the specified file from the DISTRESS server. A file's nameid can be found by using the list command, detailed below. A get command will automatically decrypt and reassemble the specified file before writing it to the local directory (or another if specified).
./distress del [options] <nameid> - Removes the file from all instances of the DISTRESS servers. This will send a 'delete' command to the server. You can only remove the file if you have delete access, and the file is set to be removable when it was created. If the file is created to be removable, only the owner has delete permissions, which they can pass on to other users with the import and export commands.
./distress list [options] - Lists all the files you have added or imported into your library. This will print to the console every file you have added, its id, time added, and number of chunks. Run ./distress list -v (-v for verbose) to list all the information available.
./distress export [options] <nameid> <savepath> - By design, DISTRESS files are only accessible by the owner, whoever created the file. To share a file currently existing on the DISTRESS network, you can export a file you have created and save it to a .receipt file. When exporting the file, you can choose permissions for reading, deleting, both or neither. Read permissions will allow whoever has the .receipt file to get the file from the DISTRESS network and reassemble the file into its encrypted (original) form. Delete permissions allow whoever has the .receipt file to delete the contents of the file from the DISTRESS network, if the file was allowed to be deleted when it was originally added. Allowing both permissions lets a user retrieve or delete the file, while allowing neither permission lets a user download the encrypted chunks associated with the file, but does not allow them to decrypt/read the file, nor delete it from the network.
./distress import [options] <receipt path> - Imports a previously exported receipt to your local library. If the receipt is 'locked', use the option -l LOCK with the correct passphrase to import successfully.
./distress verify <receiptid> <file_path> - Checks if the receipt identified by receiptid describes the file located by file_path. The receipt must be imported into your local library for this command to work.