safe

Password protected secret keeper
git clone git://git.z3bra.org/safe.git
Log | Files | Refs | README | LICENSE

README (3233B)


      1 # safe
      2 
      3 Store your secrets in an encrypted safe, protected by a password.
      4 
      5 ## examples
      6 
      7 	# add a secret to your safe
      8 	safe -a my/deepest/secret < cute-kitten.gif
      9 
     10 	# retrieve a secret from your safe
     11 	safe my/deepest/secret
     12 
     13 	# list all your secrets
     14 	find .secrets -type f
     15 
     16 	# start a safe agent, export variables to the environment
     17 	# and push your key to it
     18 	eval $(safe-agent)
     19 	safe -r
     20 
     21 	# have the agent forget the key
     22 	kill -USR1 $SAFE_PID
     23 
     24 
     25 ## features
     26 
     27 + Only require a master password to unlock
     28 + Provide a way to open/lock the safe (agent)
     29 + Store any kind of secret (stream encryption)
     30 
     31 ## design
     32 
     33 Your safe is stored on disk as a directory tree, which location is set
     34 at compilation time (default: .secrets). This location can later be
     35 changed with the SAFE_DIR environment variable, or using the -s flag.
     36 
     37 	.secrets
     38 	.secrets/master
     39 	.secrets/webmail
     40 	.secrets/work/webmail
     41 	.secrets/work/master
     42 
     43 Each file represent a "secret" and is the concatenation of a salt and
     44 the data encrypted with this salt:
     45 
     46                 [16 bytes salt][encrypted data]
     47 
     48 Data is encrypted using the xchacha20[0] algorithm, using a key derived
     49 from your master password and a salt (stored along with your password).
     50 
     51 ## "master" entry
     52 
     53 The safe uses one entry named "master" (set at compile time) as a
     54 reference for your master password + salt.
     55 This entry is automatically created when you add your first entry to
     56 the safe. It contains your master password and can be retrieved just
     57 like any other entry from the safe. The content is not used for anything
     58 though, so it could be anything.
     59 
     60 What's so special about this entry is that its salt is the reference salt
     61 for all secrets added after this one (which typically means: ALL OF THEM.)
     62 As this salt is used to derivate a key, it is really important not to
     63 loose it, so it is stored with all other passwords as well, in case you
     64 accidentaly remove the "master" entry from the safe.
     65 
     66 If it ever happens, you can easily recreate it with the following
     67 commands (assuming "foo" is a secret that was previously created using
     68 the lost master):
     69 	
     70 	ln .secrets/foo .secrets/master
     71 	echo "your master password" | pass -a master2
     72 	unlink .secrets/master
     73 	mv .secrets/master{2,}
     74 	chmod 400 .secrets/master
     75 
     76 Note that a safe without a "master" entry can easily be corrupted as it
     77 may end up with different keys used to encrypt your secret, so treat the
     78 "master" entry with respect :)
     79 
     80 ## agent
     81 
     82 Typing your master password for each encryption/decryption is tedious,
     83 so the safe comes with a built-in agent that can save your key in memory,
     84 and serve it through a socket, so you don't have to type your password.
     85 
     86 Upon starting, the agent will output two shell variables:
     87 
     88 * SAFE_SOCK - containing the path to this agent's socket
     89 * SAFE_PID  - containing the PID of the currently started agent
     90 
     91 If you export these in your environment, later calls of safe(1) will
     92 use these variables to communicate with the agent and retrieve the key
     93 through the agent's socket.
     94 
     95 You can use the PID to kill the agent when you want to "lock" the safe.
     96 
     97 ## license
     98 This software is licensed under the ISC license, see the LICENSE file
     99 provided.
    100 
    101 [0]: https://download.libsodium.org/doc/advanced/stream_ciphers/xchacha20