Bump version for development.
[pwmd.git] / README
blob94b54a67abc8822761364e655fb3b6131191e324
1 Password Manager Daemon is a server that provides a way for applications to
2 securely store and retrieve data at a centralized location. The data is stored
3 in an XML file and clients connect and send commands to manipulate the data.
4 It mimics a filesystem in many ways with commands to store, copy, move and
5 delete elements.
7 There are quite a few password managers around and pwmd is similar to most.
8 The need for pwmd is that gnupg keys stored on a smartcard cannot be cached in
9 gpg-agent and therefore each access to a datafile would require the smartcard
10 present to decrypt it. Pwmd decrypts the datafile once and caches it in memory
11 and has it's own cache expiration settings rather than using the gpg-agent
12 cache.
14 You may also find pwmd useful if you have a few applications that require the
15 same credentials but hate having to update all those configuration files to
16 reflect any changes. The data file can be edited once with a pwmd client and
17 other clients can retrieve the updated shared info.  Similar to how a symbolic
18 link on a filesystem works. See the "Target Attribute" in the documentation
19 for details.
21 Some other features include:
23     * Multi-threaded. More than one client may access the data at the same
24       time
25     * OpenPGP encrypted XML data files via GnuPG with smartcard support
26     * Remote network connections via libpwmd over GnuTLS or SSH via a proxy
27     * Configuration file which supports file specific settings including:
28       cache expiration, passphrase file and more
29     * Logging to file and/or syslog
30     * Secure memory usage. Pwmd will zero out memory before freeing it and
31       also has the option to lock the entire process in RAM to avoid swapping
32       the data to virtual memory
33     * Per file and element ACL's including connections over TLS
36 Requirements:
37 -------------
38     C99 compiler - http://www.gnu.org/software/gcc
39                    Has been tested to work. Others should work fine, too.
41     libassuan    - ftp://ftp.gnupg.org/gcrypt/libassuan
42                    Protocol. Version 2.5.0 or later is required.
44     libgpg-error - http://www.gnupg.org
45                    Error handling. Version 1.29 or later is required.
47     gpg-agent    - http://www.gnupg.org
48                    Keypair generation, decryption and caching. Version 2.2.7
49                    or later is required.
51     pinentry     - http://www.gnupg.org
52                    Normally required for passphrase retrieval from gpg-agent.
54     libxml2      - http://xmlsoft.org
55                    Required for XML parsing and data manipulation.
57     libgpgme     - http://www.gnupg.org
58                    For data file crypto operations. Version 1.11.0 or later is
59                    required.
61     libgcrypt    - http://www.gnupg.org
62                    Cache encryption and hashing. Version 1.7.0 or later is
63                    required.
65     libgnutls    - http://www.gnu.org/software/gnutls/
66                    For encrypted connections over a TCP network. Version
67                    3.3.0 or later. Optional.
70 Installation:
71 -------------
72 ./configure && make install
74 For TLS support, pass --enable-gnutls to ./configure.
76 Typing 'pwmd' will start the server and wait for connections to
77 ~/.pwmd/socket.  Passing --allow-preset-passphrase to gpg-agent is recommended
78 and gpg-agent option --allow-loopback-pinentry is required if using a keyfile
79 or connecting over TLS. These options can be added to the gpg-agent.conf
80 configuration file in the gnupg home directory (~/.pwmd/.gnupg). See the
81 gpg-agent(1) manual page for details about these options and the pwmd
82 documentation for details about the location of the GnuPG home directory.
85 Connecting:
86 -----------
87 Any program that can connect to a UNIX domain socket will work although using
88 pwmc, a client included with libpwmd, is recommended:
90     echo command | pwmc filename
91 or interactively
92     pwmc filename
94     socat UNIX-CONNECT:$HOME/.pwmd/socket -
96 A much more user-friendly full featured client QPwmc is also available. It has
97 a nice Qt GUI and is much easier to use. See
98 https://gitlab.com/bjk/qpwmc/wikis for details.
100 Please read pwmd.info manual for protocol commands, syntax and
101 configuration details. A HTML version is also available in doc/pwmd.html.
104 GIT Repository
105 --------------
106 There is a public GIT repository available at Gitlab. Anonymous checkouts can
107 be done by doing:
109     git clone https://gitlab.com/bjk/pwmd
110     or from the mirror:
111     git clone git://repo.or.cz/pwmd.git
113 The gitweb interface can be viewed at:
115     https://gitlab.com/bjk/pwmd
116     or
117     http://repo.or.cz/w/pwmd.git
120 Mailing lists
121 -------------
122 For pwmd:
123 https://lists.sourceforge.net/lists/listinfo/pwmd-devel
125 And for libpwmd:
126 https://lists.sourceforge.net/lists/listinfo/libpwmd-devel
129 Issue tracker:
130 --------------
131 Please send any bug reports, feature requests or patches to the issue tracker
132 at Gitlab: https://gitlab.com/bjk/pwmd/issues.
135 Ben Kibbey <bjk@luxsci.net>
136 https://gitlab.com/bjk/pwmd/wikis