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