PWS(1)
======
:doctype: manpage

NAME
----
pws - password store management

SYNOPSIS
--------
*pws* 'COMMAND' ['OPTIONS']

DESCRIPTION
-----------

The pws tool allows you to store passwords (or anything else, really) in
a set of encrypted files.  Each file can be encrypted to a different set
of users.  pws helps you with the bookkeeping of which keys to encrypt
each file to and provides a convinient wrapper to edit protected files.

In the intended use the directory with the encrypted passwords would be
under SCM control and shared with other people who need access.

initialization
--------------

First you need a file where your users and group are defined in.  This
file is named .users.  Lines consist of assignments of the form
 <username> = <keyfingerprint>
and
 @<groupname> = <username>|@<groupname> [, <username>|@<groupname> ...]

Lines starting with a # are comments and thus get ignored.

--------------------------------
% cat .users
# This file needs to be gpg signed by a key whose fingerprint
# is listed in ~/.pws.yaml

formorer   = 6E3966C1E1D15DB973D05B491E45F8CA9DE23B16
weasel     = 25FC1614B8F87B52FF2F99B962AF4031C82E0039
@admins    = formorer, weasel

zobel    = 6B1856428E41EC893D5DBDBB53B1AC6DB11B627B
maxx     = 30DC1D281D7932F55E673ABB28EEB35A3E8DCCC0
@vienna = zobel, maxx

@all = @admins, @vienna

# gpg --clear .users && mv .users.asc .users
--------------------------------

The .users file is designed to live in a SCM repository, such as git,
alongside all the other encrypted files.  In order to prevent
unauthorized tampering with the .users file - for tricking somebody to
re-encrypt data to the wrong key - the .users file needs to be
PGP-clearsigned with a key from a whitelist.

This whitelist lives in ~/.pws.yaml under the trusted_users key and
then under the directory name.  A sample file looks like:

---------------------------------
aliases:
  debian:
    - &tfheen   A28411A596193171331802C0B65A4871CA19D717
    - &weasel   25FC1614B8F87B52FF2F99B962AF4031C82E0039

trusted_users:
  "~/.pws":
   - *tfheen
  "~/debian/dsa-passwords":
   - *tfheen
   - *weasel
---------------------------------

adding a new file
-----------------

-----------------------------
% pws ed -n file
-----------------------------

editing files
-------------

Every file needs a header like:

------------------------------
access: @admins, maxx
------------------------------

You can edit the encrypted file with the pws tool: +pws ed file+.

updating the keyring
--------------------

If available as .keyring pws instructs GnuPG to use this keyring in
addition to the user's default keyrings.  This allows sharing of the
keyring in the repository.  Use +pws update-keyring+ to
update/initialize this keyring.


AUTHOR
------
Peter Palfrader <peter@palfrader.org>, Tollef Fog Heen <tfheen@err.no>