err.no Git - pwstore/blob - README.asciidoc

   1 pwstore documentation
   2 =====================
   3 Peter Palfrader, Alexander Wirt
   4 v0.1 July 2011
   5
   6
   7 introduction
   8 ------------
   9
  10 The pws tool allows you to store passwords (or anything else, really) in
  11 a set of encrypted files.  Each file can be encrypted to a different set
  12 of users.  pws helps you with the bookkeeping of which keys to encrypt
  13 each file to and provides a convinient wrapper to edit protected files.
  14
  15 initialization
  16 --------------
  17
  18 First you need a file where your users and group are defined in.  This
  19 file is named .users.  Lines consist of assignments of the form
  20  <username> = <keyfingerprint>
  21 and
  22  @<groupname> = <username>|@<groupname> [, [<username>|@<groupname> ...]
  23
  24 Lines starting with a # are comments and thus get ignored.
  25
  26 --------------------------------
  27 cat .users
  28
  29 # This file needs to be gpg signed by a key whose fingerprint
  30 # is listed in ~/.pws-trusted-users
  31
  32 formorer   = 6E3966C1E1D15DB973D05B491E45F8CA9DE23B16
  33 weasel     = 25FC1614B8F87B52FF2F99B962AF4031C82E0039
  34 @admins    = formorer, weasel
  35
  36 zobel    = 6B1856428E41EC893D5DBDBB53B1AC6DB11B627B
  37 maxx     = 30DC1D281D7932F55E673ABB28EEB35A3E8DCCC0
  38 @vienna = zobel, maxx
  39
  40 @all = @admins, @vienna
  41
  42 # gpg --clear .users && mv .users.asc .users
  43 --------------------------------
  44
  45 The .users file is designed to live in a SCM repository, such as git,
  46 alongside all the other encrypted files.  In order to prevent
  47 unauthorized tampering with the .users file - for tricking somebody to
  48 re-encrypt data to the wrong key - the .users file needs to be
  49 PGP-clearsigned with a key from a whitelist.
  50
  51 This whitelist lives in ~/.pws-trusted-users, and simply takes one
  52 key fingerprint per line:
  53
  54 ---------------------------------
  55 # cat ~/.pws-trusted-users
  56
  57 #formorer
  58 6E3966C1E1D15DB973D05B491E45F8CA9DE23B16
  59 ---------------------------------
  60
  61 Currently this whitelist is the same for any pws repositories a user
  62 might have.  A patch to remove this limitation would be nice.
  63
  64
  65 adding a new file
  66 -----------------
  67
  68 -----------------------------
  69 # pws ed -n file
  70 -----------------------------
  71
  72 editing files
  73 -------------
  74
  75 Every file needs a header like:
  76
  77 ------------------------------
  78 access: @all
  79 ------------------------------
  80
  81 You can edit the encrypted file with the pws tool: +pwd ed file+.
  82
  83 updating the keyring
  84 --------------------
  85
  86 If available as .keyring pws instructs GnuPG to use this keyring in
  87 addition to the user's default keyrings.  This allows sharing of the
  88 keyring in the repository.  Use +pws update-keyring+ to
  89 update/initialize this keyring.
  90