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

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