Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 169 lines (119 sloc) 6.036 kB
317d9bd @cadrian fix #5
authored
1 # General description
2
7d9473f @cadrian added the "typical use" section
authored
3 `pwdmgr` is a small and simple password manager utility.
364a0a8 @cadrian readme
authored
4
5 Typical use is through *dmenu* (<http://tools.suckless.org/dmenu/>)
6
7 An *administration console* is also provided.
8
9 ## Features:
10
11 - enter a pass key, the actual password is copied in X clipboard
12 - vault encrypted via openssl (Blowfish Cipher) using a master key
13 - vault merge
14 - vault up/download
15
16 ## Dependencies:
17
317d9bd @cadrian fix #5
authored
18 - **xclip** (mandatory)
19 - **openssl** (mandatory)
ad321de @cadrian more doc
authored
20 - **zenity** (mandatory)
c40ac26 @cadrian fixed README: missing dependency :-) + typo
authored
21 - **less** (almost mandatory, for the *list* command and all kinds of
22 help)
317d9bd @cadrian fix #5
authored
23 - either **curl** or **scp** (optional, but useful if you want to
ad321de @cadrian more doc
authored
24 keep your vault in the cloud)
317d9bd @cadrian fix #5
authored
25 - **dmenu** (optional, but useful if you don't want to use the
ad321de @cadrian more doc
authored
26 console for nominal use case -- you may also use zenity)
317d9bd @cadrian fix #5
authored
27 - **xterm** (optional, but useful to let the console open itself in
28 graphical environments)
7d9473f @cadrian added the "typical use" section
authored
29
30 ## Typical use
31
86d8008 @cadrian fixed doc
authored
32 For a per-user install:
33
34 - bind `<super>k` to *$HOME/.local/bin/pwdmgr_menu*
35 - bind `<super><shift>k` to *$HOME/.local/bin/pwdmgr_console*
317d9bd @cadrian fix #5
authored
36
37 # Configuration
38
39 The configuration file is usually found in your home directory:
40 `$HOME/.pwdmgr/config.rc`
41
42 A system-wide configuration file may be found at `/etc/pwdmgr.rc`.
43
44 Some sample files are available in the documentation section of your
45 package (the default install places those files in
235206e @cadrian misc fixes, preparing to deliver V0.0.4
authored
46 `/usr/local/share/doc/pwdmgr/`). Look at the `sample-*.rc` files.
317d9bd @cadrian fix #5
authored
47
c40ac26 @cadrian fixed README: missing dependency :-) + typo
authored
48 Those files are auto-documented. Just open them and read the comments
317d9bd @cadrian fix #5
authored
49 to find how to modify them.
50
51 # Features details
52
53 ## Password management
54
55 Passwords are kept in a single file, known as the *vault*. This file
56 is encrypted by a "master pass phrase". It is the only pass you'll
57 need to know!
58
59 The passwords are referenced by a unique key. They are never displayed
60 in clear text.
61
62 ## The server
63
64 The server is responsible for keeping the vault open using a pass
65 phrase you'll need to type only once.
66
67 To close the vault, just type `stop` in the administration console
68 (see below). It will stop the server.
69
70 ## The menu
71
72 The menu is a very quick and efficient way of getting a password. Just
73 enter the key of the password you need; the password is made available
ad321de @cadrian more doc
authored
74 in the X clipboard, just type `ctrl-V` or click the middle button of
317d9bd @cadrian fix #5
authored
75 your mouse to paste it in a password form.
76
77 The most typical use is all the web login sites (google, facebook,
78 banks...) Never have duplicate passwords anymore!
79
80 ## The administration console
81
82 The administration console allows more operations on the vault. The
83 most useful is ceraintly the `add` command, that will add a new vault
84 entry using the provided key.
85
86 For instance, `add foo` will generate a unique random password and
87 store it in the vault using the key *foo*. The password is also made
88 available to the X clipboard for pasting in the form of the new
89 account you are just creating `:-)`
90
ad321de @cadrian more doc
authored
91 You may also specify a *recipe* for the password generation; for
92 instance, type `add foo generate 6n` to generate a 6 figures
93 password. The recipe grammar is:
94
95 recipe <- mix ('+' mix)* # all the ingredients will be mixed
96 mix <- quantity ingredient+ # n times the ingredients
97 quantity <- [0-9]* # default 1
98 ingredient <- 'a' # alphabetic
99 / 'n' # numeric
100 / 's' # symbols
101
317d9bd @cadrian fix #5
authored
102 Another usage is `add foo prompt`. In that case, the password is not
103 generated, but you will need to enter it in the dialog that pops
104 up. The password is then stored in the vault and also made available
105 in the X clipboard. This usage is not recommended except for
106 already-known passwords (to fill up your vault), or for sites that
107 have ugly (and usually weak) password policies.
108
109 For other commands, just type `help`.
110
111 ## Remoting and merging
112
113 OK, now you have a vault at home in your desktop, another on your
114 laptop, a third one at work. How do you merge them?
115
116 First, you must define a *central location* where your vault is to be
117 kept. Preferably a cloud space you own.
118
119 Fill in the corresponding fields in the configuration file.
120
121 When those fields are correctly set, the administration console
122 provides a few useful commands:
123
124 - `save` saves your local vault up to the cloud
125 - `load` loads the vault from the cloud (it overwrites your local one!)
126 - `merge` attempts to merge both the local cloud and the one in the
127 vault, saving the result back up to the cloud.
128
129 Let's focus on that last operation, which should be the most
130 common. The merge should work as expected. Added keys are added,
131 removed keys are removed.
132
133 The only difficult case arise if a key is updated in both vaults. In
134 that case, the one with the greatest number of changes wins; if equal,
135 then the local version wins.
136
137 Note that, to help merge take decisions in the latter case, keys are
138 never really deleted from the vault. They are simply marked as being
139 removed.
a14fc17 @cadrian fix #6 - proxy support
authored
140
141 ## Proxy support
142
143 Proxies are supported when using the *curl* protocol: the console
144 installs the `ALL_PROXY` variable using the following keys in the
145 `[proxy]` section of the configuration file:
146
147 - `protocol` specifies the proxy protocol
148 - `host` is the only mandatory key; it contains the name of the proxy host
149 - `port` specifies a port, if different from the default (e.g. 8080)
150 - `user` gives a user name, if the proxy needs authentication
151 - `pass` gives a password key, to be retrieved from the vault
152
153 ## Important note
154
155 pwdmgr is a local password manager. As such, it needs to provide
156 passwords in cleartext to other processes (mainly the X clipboard).
157
158 It is important to understand that, under such circumstances, there is
159 no reason to make pwdmgr overly secure. It can be subject to many
160 local exploits (reading its environment variables, its memory sections
161 etc. may provide cleartext passwords).
162
163 On the other hand, there should be no remote exploits, because the
164 vault load/save protocol only sends and receives encrypted vault
165 streams.
166
167 Just take the needed steps to ensure that your machine is not remotely
168 exploitable.
Something went wrong with that request. Please try again.