
	PWMan Password Manager
	----------------------

PWMan is a password manager which uses gpg encryption to safeguard your data.
It provides a simple and easy to use command line (NCurses) interface to 
manage, store, search and retrieve your passwords.

The look and feel is based on Jaakko Heinonen's abook.


INSTALLATION REQUIREMENTS

 PWMan is distributed as source files, and hence needs to be compiled and 
 installed manually. Installation configuration should check and bring in
 all dependencies for you, but ensure you have the following development 
 libraries on your machine before commencing (as configuration will need 
 to be restarted from the beginning each time a dependency fails):

  * gcc or some other C compiler
  * libc6 standard C development libraries
  * ncurses development libraries
  * libxml2 GNOME XML library

 You can install all of these on e.g. Ubuntu with the following command:

  % sudo apt-get install libc6-dev libncurses5-dev libxml2 gcc 

 Or on Fedora with:

  % sudo yum install glibc-devel ncurses-devel libxml2-devel gcc


COMPILATION AND INSTALLATION

 All tasks related to compilation, deployment etc. are managed by the C
 utility make. First, configure the process: from within the top-level
 directory of the distribution run

  % ./configure

 If you already have all the necessary dependencies installed then this
 will run its course with no errors; otherwise try to fix any failed
 dependencies (on Ubuntu, this will always be possible using standard
 packages).

 Then run the following sequence of commands to compile, check and then
 install the compiled binary:

  % make
  % make check
  % sudo make install

 More detailed information, including other make options, can be found
 in the INSTALL file included in this distribution.


ROLLBACK

 Because pwman is installed separately from standard package management, you
 will need to take note of the files mentioned during "sudo make install"
 above in order to roll the installation back. As of v0.4.0, these are:

  * /usr/local/bin/pwman
  * /usr/local/bin/convert_pwdb
  * /usr/local/bin/pwdb2csv
  * /usr/local/man/man1/pwman.1


BEFORE USING PWMAN

 While compilation does not directly require it, usage relies on Gnu Privacy 
 Guard (gpg) being installed. You will need to specify a GnuPG ID the
 first time a user runs pwman, so this must be set up beforehand.

 There is more information on the gpg manpage, but you can probably just run

  % gpg --gen-key

 and follow the on-screen instructions.


SETUP

 When you first run pwman, it will prompt you for several things:

* GnuPG ID
   This is the ID of the GnuPG identity that will be used to encrypt the
    password database. You can specify this as your email address, or as
    the 8 (hex) digit key ID
   See http://www.dewinter.com/gnupg_howto/english/GPGMiniHowto.html if you
    are new to GnuPG, and need help importing or creating keys.
* Path to GnuPG
   PWMan needs to call GnuPG, to get it to decrypt and encrypt the password
    database. So, you need to tell PWMan where to find your copy of pgp
* Password Database File
   This is the filename to use for storing your password database in.
* Sign Password Database
   By default, the database is encrypted but not signed. Optionally, the
    database can be signed with your private key, which would then be
    checked when loading the database.
* Passphrase Timeout
   PWMan only remembers your GnuPG password for a limted amount of time. After
    this period has elapsed, you will need to re-enter it. This timeout is
    there as a security measure, in case you wander off from your computer
    without logging out.

 These configuration settings will be written to your home directory. You can
 change them at any time by running pwman, and pressing 'o' at any time.


PWMAN and GPG 2.1 onwards

 Starting with GPG 2.1, there have been some backwards-incompatible changes
 to how GPG accepts key passphrases from programs like pwman. If you are
 using GPG 2.1 or later, please ensure that your GPG Agent config file
 (normally ~/.gnupg/gpg-agent.conf) contains the entry
   allow-loopback-pinentry

 For more details, please see
 https://wiki.archlinux.org/index.php/GnuPG#Unattended_passphrase
 https://www.gnupg.org/documentation/manuals/gpgme/Pinentry-Mode.html
 (The former is easier to unstand, the latter is official but for developers!)


UPGRADE

 Currently, all versions of pwman use the same encryption scheme (gpg) and
 the same XML format. As such, to upgrade, simply drop in the new binary.


GETTING HELP

 Once pwman is running, and you have entered your (GnuPG) passphrase, you can
 hit '?' to get up the program help. This will tell you what all the keys are
 to perform actions in pwman.
 

LICENSE

 All files in this distribution are released under the GNU GENERAL PUBLIC 
 LICENSE.
 See COPYING FOR DETAILS.


CONTACT AUTHOR

 Send bugreports, fixes, wishes etc. to Nick Burch <code@gagravarr.org>
