tREADME.md - coffin - secure lan file storage on a device
HTML git clone git://parazyd.org/coffin.git
DIR Log
DIR Files
DIR Refs
DIR Submodules
DIR README
DIR LICENSE
---
tREADME.md (4714B)
---
1 COFFIN
2 ======
3
4 ## Crypto Office Filer For Important Nuggets
5
6 Secure dedicated LAN file storage made easy
7
8 ## What is this nonsense?
9
10 A coffin is a dedicated device you can use to keep your files on a safe
11 and encrypted place. The core workflow of the coffin is having a key
12 that is autodetected by the device once plugged in. Once detected, the
13 coffin will open the tomb that corresponds to that same key.
14 Now, you are able to access your files on the LAN.
15 Once you plug in your key again, that same tomb will be closed and your
16 files are once again unreadable.
17
18 ## Installation
19 Install the needed dependencies on a Debian-based distro:
20
21 ```
22 ; sudo apt-get install zsh cryptsetup libgcrypt20-dev apache2 wipe sshfs inotify-tools pinentry-curses pwgen gettext haveged sudo openssl
23 ```
24
25 Clone this repository to the device you will be using and update repo's
26 submodules.
27
28 ```
29 ; git clone https://github.com/parazyd/coffin.git coffin && cd coffin
30 ; git submodule update --init
31 ```
32
33 Run `make` in order to compile tomb's KDF modules.
34
35 ```
36 ; make
37 ```
38
39 Run `make install` as root in order to install and configure your
40 machine.
41
42 ```
43 ; sudo make install
44 ```
45
46 ## Usage
47
48 After installation, you will end up with an initscript in /etc/init.d/coffin
49 You can start coffin by issuing `/etc/init.d/coffin start` as root and the
50 watch script will begin to watch your /dev for new devices. You can see
51 coffin's output by issuing (as root) `tail -f /var/log/coffin`
52
53 ### Hooks
54
55 Hooks are oneliners written on your USB key which will trigger actions
56 on the coffin depending on their content. You can either create them
57 manually or use ready scripts (GUI or CLI) from the `helpers` directory.
58 Those scripts are interactive and self-explanatory so I shan't document
59 them here. However, if you wish to create your hooks manually, continue
60 reading. Actually, read anyway, it will give you insight on how coffin
61 works.
62
63 #### Hook syntax
64
65 ```
66 action:userName:tombName:options
67 ```
68
69 So far there are only two actions (create, delete) but more are to be
70 added in the future.
71 To create a hook, add one or more to the `.coffin` directory in a file
72 called `hook`. Separate each hook with a newline.
73
74 ##### Create hook
75
76 ```
77 create:userName:tombName:tombSize:features
78 create:undertaker:myAwesomeCrypt:50:webdav:sshfs
79 ```
80
81 So, to create a tomb, you will have to choose a username, a tomb name
82 and the size of your choice (in MiB). This is the bare minimum.
83 There are also features like `webdav` or `sshfs` that can be used to
84 access your files.
85
86 Currently implemented features:
87 * WebDAV
88 * SSH(FS)
89
90 Important note is that if you use any of the features listed above you
91 will have to add according files as well. For more info, please consult
92 the README file inside the `conf/` directory.
93
94 ##### Delete hook
95
96 ```
97 delete:userName:tombName
98 delete:undertaker:myAwesomeCrypt
99 ```
100
101 To delete an existing tomb, you will have to reuse your username you
102 used to create that tomb, and the tomb's name. You will also have to
103 have the tomb's keyfile along with it in order to delete your stuff.
104 Coffin will automatically delete your WebDAV info, but will keep the ssh
105 key if there is any.
106
107 #### Okay, I made a hook (I think?). What do I do now?
108
109 Provided it's correct, just plug your USB key to a box running coffin
110 and the magic happens. Coffin will recognize if there are any hooks and
111 perform according actions. After your first tomb is created, you can
112 plug the USB key back into your computer and there you will find some
113 new files coffin needs to work correctly.
114
115 ##### ttab
116
117 The ttab is a file holding info on your tombs. It's syntax is
118 supersimple:
119
120 ```
121 userName:tombName:dostuff
122 undertaker:myAwesomeCrypt:true
123 ```
124
125 You already recognize your username and tomb name. The third part is a
126 boolean value, telling coffin to either do stuff with this tomb or leave
127 it alone (ex: to open/close or not to open/close). You will have to edit
128 this value manually if you wish to do anything. The default value on a
129 newly created tomb is `true`.
130
131 Whether you've changed this value or not, you can plug your key back
132 into the coffin box and depending on the boolean value, coffin could
133 close your tomb and make your files unreadable and encrypted :)
134
135 #### How do I access my files?
136
137 If you haven't added any features like WebDAV, your only way is
138 accessing your files the way you accessed your box when installing.
139 If you've enabled WebDAV, just use a WebDAV client and connect to your
140 box with `https://addressof.coffin/tombName`. The SSL certificate was
141 generated on compile time and the fingerprint was shown to you. Compare
142 it now and set it to trusted if everything is okay. Login with the info
143 you provided when creating your tomb's hook.
144
145 ## Troubleshooting
146