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

   1 PWS(1)
   2 ======
   3 :doctype: manpage
   4
   5 NAME
   6 ----
   7 pws - password store management
   8
   9 SYNOPSIS
  10 --------
  11 *pws* 'COMMAND' ['OPTIONS']
  12
  13 DESCRIPTION
  14 -----------
  15
  16 The pws tool allows you to store passwords (or anything else, really) in
  17 a set of encrypted files.  Each file can be encrypted to a different set
  18 of users.  pws helps you with the bookkeeping of which keys to encrypt
  19 each file to and provides a convinient wrapper to edit protected files.
  20
  21 In the intended use the directory with the encrypted passwords would be
  22 under SCM control and shared with other people who need access.
  23
  24 initialization
  25 --------------
  26
  27 First you need a file where your users and group are defined in.  This
  28 file is named .users.  Lines consist of assignments of the form
  29  <username> = <keyfingerprint>
  30 and
  31  @<groupname> = <username>|@<groupname> [, <username>|@<groupname> ...]
  32
  33 Lines starting with a # are comments and thus get ignored.
  34
  35 --------------------------------
  36 % cat .users
  37 # This file needs to be gpg signed by a key whose fingerprint
  38 # is listed in ~/.pws.yaml
  39
  40 formorer   = 6E3966C1E1D15DB973D05B491E45F8CA9DE23B16
  41 weasel     = 25FC1614B8F87B52FF2F99B962AF4031C82E0039
  42 @admins    = formorer, weasel
  43
  44 zobel    = 6B1856428E41EC893D5DBDBB53B1AC6DB11B627B
  45 maxx     = 30DC1D281D7932F55E673ABB28EEB35A3E8DCCC0
  46 @vienna = zobel, maxx
  47
  48 @all = @admins, @vienna
  49
  50 # gpg --clear .users && mv .users.asc .users
  51 --------------------------------
  52
  53 The .users file is designed to live in a SCM repository, such as git,
  54 alongside all the other encrypted files.  In order to prevent
  55 unauthorized tampering with the .users file - for tricking somebody to
  56 re-encrypt data to the wrong key - the .users file needs to be
  57 PGP-clearsigned with a key from a whitelist.
  58
  59 This whitelist lives in ~/.pws.yaml under the trusted_users key and
  60 then under the directory name.  A sample file looks like:
  61
  62 ---------------------------------
  63 aliases:
  64   debian:
  65     - &tfheen   A28411A596193171331802C0B65A4871CA19D717
  66     - &weasel   25FC1614B8F87B52FF2F99B962AF4031C82E0039
  67
  68 trusted_users:
  69   "~/.pws":
  70    - *tfheen
  71   "~/debian/dsa-passwords":
  72    - *tfheen
  73    - *weasel
  74 ---------------------------------
  75
  76 adding a new file
  77 -----------------
  78
  79 -----------------------------
  80 % pws ed -n file
  81 -----------------------------
  82
  83 editing files
  84 -------------
  85
  86 Every file needs a header like:
  87
  88 ------------------------------
  89 access: @admins, maxx
  90 ------------------------------
  91
  92 You can edit the encrypted file with the pws tool: +pws ed file+.
  93
  94 updating the keyring
  95 --------------------
  96
  97 If available as .keyring pws instructs GnuPG to use this keyring in
  98 addition to the user's default keyrings.  This allows sharing of the
  99 keyring in the repository.  Use +pws update-keyring+ to
 100 update/initialize this keyring.
 101
 102
 103 AUTHOR
 104 ------
 105 Peter Palfrader <peter@palfrader.org>, Tollef Fog Heen <tfheen@err.no>