Skip to content
password store
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


PWS(1) Manual Page


pws - password store management




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.


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-trusted-users

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

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

@all = @admins, @vienna

# gpg --clearsign .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-trusted-users, and simply takes one key fingerprint per line:

% cat ~/.pws-trusted-users

Currently this whitelist is the same for any pws repositories a user might have. A patch to remove this limitation would be nice.

listing files

This gives a listing of secure and other files.
% pws ls

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.

reencrypting a file

If your .users has changed, and new users should get access to existing files, you can use the reencrypt command.

% pws rc file

showing keys from a file

If you store YAML files in PWS, you can request a single key at a time:

% pws get users.yaml.asc /gannet/root/password

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.


Peter Palfrader <>

You can’t perform that action at this time.