tupdated docs - coffin - secure lan file storage on a device (HTM) git clone git://parazyd.org/coffin.git (DIR) Log (DIR) Files (DIR) Refs (DIR) Submodules (DIR) README (DIR) LICENSE --- (DIR) commit b51b18dfcb05b9a27dcf56a8e6d7e319da794d0c (DIR) parent 1806989bd2345e4b85ce7cfa552ee0eb9fc4e0a6 (HTM) Author: parazyd <parazyd@dyne.org> Date: Tue, 29 Mar 2016 18:45:59 +0200 updated docs Diffstat: M README.md | 86 ++++++++++++++++++++++++++++++- M conf/README | 25 ++++++++++++++++++++++--- M conf/webdav.skel | 2 +- M helpers/gmakehook | 16 ++++++++++------ 4 files changed, 117 insertions(+), 12 deletions(-) --- (DIR) diff --git a/README.md b/README.md t@@ -27,10 +27,92 @@ Run `make install` as root in order to install and configure your device. ## Notes -* `gmakehook` can be used to create coffin hooks in a more user-friendly - manner. It is a GUI (zenity) helper script. +* The initscript is not yet finished, so you will have to start coffin manually, + by entering the `src/` directory and running (as root) `./mourner` ## Usage +After installation, you will end up with an initscript in +/etc/init.d/coffin +You can start coffin by issuing `/etc/init.d/coffin start` and the watch +script will begin to watch your /dev for new devices. + +### Hooks +Hooks are oneliners written on your USB key which will trigger actions +on the coffin depending on their content. You can either create them +manually or use ready scripts (GUI or CLI) from the `helpers` directory. +Those scripts are interactive and self-explanatory so I shan't document +them here. However, if you wish to create your hooks manually, continue +reading. Actually, read anyway, it will give you insight on how coffin +works. + +#### Hook syntax +``` +action:userName:tombName:options +``` +So far there are only two actions (create, delete) but more are to be +added in the future. +To create a hook, add one or more to the `.coffin` directory in a file +called `hook`. Separate each hook with a newline. +##### Create hook +``` +create:userName:tombName:tombSize:features +create:undertaker:myAwesomeCrypt:50:webdav:sshfs +``` +So, to create a tomb, you will have to choose a username, a tomb name +and the size of your choice (in MiB). This is the bare minimum. +There are also features like `webdav` or `sshfs` that can be used to +access your files. +Currently implemented features: +* WebDAV +* SSHFS + +Important note is that if you use any of the features listed above you +will have to add according files as well. For more info, please consult +the README file inside the `conf/` directory. + +##### Delete hook +``` +delete:userName:tombName +delete:undertaker:myAwesomeCrypt +``` +To delete an existing tomb, you will have to reuse your username you +used to create that tomb, and the tomb's name. You will also have to +have the tomb's keyfile along with it in order to delete your stuff. +Coffin will automatically delete your WebDAV info, but will keep the ssh +key if there is any. + +#### Okay, I made a hook (I think?). What do I do now? +Provided it's correct, just plug your USB key to a box running coffin +and the magic happens. Coffin will recognize if there are any hooks and +perform according actions. After your first tomb is created, you can +plug the USB key back into your computer and there you will find some +new files coffin needs to work correctly. + +##### ttab +The ttab is a file holding info on your tombs. It's syntax is +supersimple: +``` +userName:tombName:dostuff +undertaker:myAwesomeCrypt:true +``` +You already recognize your username and tomb name. The third part is a +boolean value, telling coffin to either do stuff with this tomb or leave +it alone (ex: to open/close or not to open/close). You will have to edit +this value manually if you wish to do anything. The default value on a +newly created tomb is `true`. + +Whether you've changed this value or not, you can plug your key back +into the coffin box and depending on the boolean value, coffin could +close your tomb and make your files unreadable and encrypted :) + +#### How do I access my files? +If you haven't added any features like WebDAV, your only way is +accessing your files the way you accessed your box when installing. +If you've enabled WebDAV, just use a WebDAV client and connect to your +box with `https://addressof.coffin/tombName`. The SSL certificate was +generated on installation and the fingerprint was shown to you. Compare +it now and set it to trusted if everything is okay. Login with the info +you provided when creating your tomb's hook. ## Troubleshooting (DIR) diff --git a/conf/README b/conf/README t@@ -1,9 +1,28 @@ -To generate a WebDAV login entry by yourself, issue +Here's some more info on the features +# WebDAV +To generate a WebDAV login entry by yourself, issue the +following command: + +#################### `echo -n "yourUsername:WebDAV:" \ && echo -n "yourUsername:WebDAV:yourDavPassword" \ | md5sum \ | awk '{print $1}'` +#################### + +Add it to the 'davpasswd' file which is located in +/etc/apache2/DAV/davpasswd on your coffin box. Or add it now here, +before installation. + +The file 'webdav.skel' located in this directory is an example entry +for the WebDAV of your tomb. Insert correct info in it, and copy it to +your USB's .coffin directory and name it 'webdav.conf'. You have to do +this every time for each new tomb you create. +Remember to set the ':webdav' feature in your hook ;) -and add the output to 'davpasswd' which is located in the -apache directory. Or add it now here, before installing. +# SSHFS +In order to get SSH access with your new username, copy your SSH +pubkey to your USB's .coffin directory and name it 'tombName.pub' +You only have to do this once-per-username, not for every tomb. +Remember to set the ':sshfs' feature in your hook ;) (DIR) diff --git a/conf/webdav.skel b/conf/webdav.skel t@@ -9,5 +9,5 @@ alias /yourTombName /media/yourTombName AuthType Digest AuthName WebDAV AuthUserFile /etc/apache2/DAV/davpasswd - Require user yourCoffinUsername + Require user yourUsername </Directory> (DIR) diff --git a/helpers/gmakehook b/helpers/gmakehook t@@ -227,7 +227,11 @@ function _mountkey { sudo mkdir -p $keymount sudo mount $USBKEY $keymount - [[ -d $coffindot ]] || sudo mkdir $coffindot + sudo chown $UID:$GID $keymount + + [[ -d $coffindot ]] || { + mkdir $coffindot + } } function _main { t@@ -384,15 +388,15 @@ function _create { [[ $feats =~ "webdav" ]] && _writedavinfo [[ $? = 0 ]] && { _zenerr "Error" "Error writing WebDAV info." && exec _main } - [[ -n $sshpubkey ]] && sudo cp $sshpubkey $coffindot/$tombid.pub + [[ -n $sshpubkey ]] && cp $sshpubkey $coffindot/$tombid.pub [[ $? = 0 ]] && { _zenerr "Error" "Error writing SSH info." && exec _main } - [[ -n $bindhook ]] && print "$bindhook" | sudo tee $coffindot/bindhooks + [[ -n $bindhook ]] && print "$bindhook" | tee $coffindot/bindhooks [[ $? = 0 ]] && { _zenerr "Error" "Error writing bind-hook info." && exec _main } - [[ -n $posthook ]] && print "$posthook" | sudo tee $coffindot/posthooks + [[ -n $posthook ]] && print "$posthook" | tee $coffindot/posthooks [[ $? = 0 ]] && { _zenerr "Error" "Error writing post-hook info." && exec _main } - print "create:${UNDERTAKER}:${TOMBNAME}:${TOMBSIZE}:${feats}" | sudo tee $hooks + print "create:${UNDERTAKER}:${TOMBNAME}:${TOMBSIZE}:${feats}" >> $hooks _umountkey && _zeninfo "Success" "$hooks written successfully!\nPlug the USB key in the coffin to activate it." exec _main t@@ -447,7 +451,7 @@ function _delete { [[ $? = 0 ]] && _zeninfo "gmakehook" "Postponing..." && _umountkey && exec _main } - print "delete:${UNDERTAKER}:${TOMBNAME}" | sudo tee $hooks + print "delete:${UNDERTAKER}:${TOMBNAME}" >> sudo tee $hooks _umountkey && _zeninfo "Success" "$hooks written successfully!\nPlug the USB key in a coffin to activate it." exec _main }