pwss 0.5.1 → 0.6.0

Sign up to get free protection for your applications and to get access to all the features.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA1:
3
- metadata.gz: 0afa2b0c4dc43e457a4bb00e4ac66769d4efa1bc
4
- data.tar.gz: 3cf4b0444295371d822a70cb6f9da42c6232ee58
3
+ metadata.gz: 0c5ebe5c97190fd270c4b13f74291e55fc3bc0b0
4
+ data.tar.gz: 955e1c956e661ff7c96128cb33aa11eb929ecec5
5
5
  SHA512:
6
- metadata.gz: 466ada399ee11f8b68e22f826e10133961e52eccc657e233f36ea28e54f44f4230e207a5b4014fe7cc4d4d67656fb3c90847e0d5830258f20626c4d0c337b063
7
- data.tar.gz: 5b45a426241981275bc02d2f79197dcb0753a90d8a5034159c03116550dd4f8d65c4523d99083d7654e12ce03d2f8c1ad3781a5873f3d989d9f2344de4fc5f33
6
+ metadata.gz: 7536170a68721a0006ff16ecfd338347df23a3766c28ae37ebc3c71e94b56881f2f7ad17a6dc888de38db1cd5c5de5e9bd40164074e416252fa592f01734abcb
7
+ data.tar.gz: f007fc3a7f4ae81991cf23401113f207b34348fb893448b1ca002335325b676e2666f0c60fc840d6dc9132f5e84a469587dabecaecf181157c99b689a69dc887
data/.gitignore CHANGED
@@ -1,20 +1,11 @@
1
1
  *~
2
2
  .DS_Store
3
-
4
- *.gem
5
- *.rbc
6
- .bundle
7
- .config
8
- .yardoc
9
- Gemfile.lock
10
- InstalledFiles
11
- _yardoc
12
- coverage
13
- doc/
14
- lib/bundler/man
15
- pkg
16
- rdoc
17
- spec/reports
18
- test/tmp
19
- test/version_tmp
20
- tmp
3
+ /.bundle/
4
+ /.yardoc
5
+ /Gemfile.lock
6
+ /_yardoc/
7
+ /coverage/
8
+ /doc/
9
+ /pkg/
10
+ /spec/reports/
11
+ /tmp/
@@ -0,0 +1,4 @@
1
+ language: ruby
2
+ rvm:
3
+ - 2.2.3
4
+ before_install: gem install bundler -v 1.10.6
@@ -1,22 +1,21 @@
1
- Copyright (c) 2014 Adolfo Villafiorita
1
+ The MIT License (MIT)
2
2
 
3
- MIT License
3
+ Copyright (c) 2016 Adolfo Villafiorita
4
4
 
5
- Permission is hereby granted, free of charge, to any person obtaining
6
- a copy of this software and associated documentation files (the
7
- "Software"), to deal in the Software without restriction, including
8
- without limitation the rights to use, copy, modify, merge, publish,
9
- distribute, sublicense, and/or sell copies of the Software, and to
10
- permit persons to whom the Software is furnished to do so, subject to
11
- the following conditions:
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
12
11
 
13
- The above copyright notice and this permission notice shall be
14
- included in all copies or substantial portions of the Software.
12
+ The above copyright notice and this permission notice shall be included in
13
+ all copies or substantial portions of the Software.
15
14
 
16
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
17
- EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
18
- MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
19
- NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
20
- LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
21
- OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
22
- WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
21
+ THE SOFTWARE.
@@ -0,0 +1,454 @@
1
+ Pwss
2
+ ====
3
+
4
+ A password manager in the spirit of [pws](https://github.com/janlelis/pws) and
5
+ [pass](https://www.passwordstore.org/).
6
+
7
+ Different from pws and pass, PWSS manages password **files**. Each file can
8
+ contain multiple entries, possibly of different types (e.g., Entry,
9
+ CreditCard, BankAccount).
10
+
11
+ Entries in a file are structured. For instance, Entry (the default type)
12
+ stores the following fields:
13
+
14
+ - title
15
+ - username
16
+ - password
17
+ - url
18
+ - description
19
+
20
+ PWSS uses the YAML format to store files: thus, they are thus human-readable
21
+ and editable. Users can add their own fields to entries, if they wish to do
22
+ so.
23
+
24
+ Password files can be encrypted and commands allow to operate directly on
25
+ them.
26
+
27
+
28
+ Installation
29
+ ------------
30
+
31
+ Type from the command line:
32
+
33
+ $ gem install pwss
34
+
35
+ PWSS depends upon the following gems: [encryptor](https://rubygems.org/gems/encryptor), [slop](https://rubygems.org/gems/slop), [clipboard](https://rubygems.org/gems/clipboard), and, starting from version 0.6.0, [gpgme](https://rubygems.org/gems/gpgme).
36
+
37
+ Password generation can use the `pwgen` utility, if available.
38
+
39
+
40
+ Quick Start
41
+ -----------
42
+
43
+ Try the following:
44
+
45
+ $ pwss init -f pwss.yaml.enc
46
+ $ pwss add -f pwss.yaml.enc First Entry
47
+ $ pwss get -f pwss.yaml.enc First
48
+
49
+ If you do not specify a filename, `pwss` will initialize a `.pwss.yaml.enc` file in your home directory.
50
+
51
+ More information with:
52
+
53
+ $ pwss
54
+ $ pwss man
55
+ $ pwss help
56
+
57
+
58
+ Detailed Instructions
59
+ ---------------------
60
+
61
+ ### Environment Setup: Generate a Keypair for PWSS
62
+
63
+ By default `pwss` uses GPG public-key/private-key encryption. If you want to
64
+ stick to the default, the first step is setting up a key-pair with GPG.
65
+
66
+ Type the following commands from the command line:
67
+
68
+ $ gpg --gen-key
69
+ Real name: pwss-agent
70
+ Email address: pwss-agent@example.com
71
+
72
+ If everything goes as expected, `gpg` generates a key-pair associated to the
73
+ (fake) `pwss-agent@example.com` email, which is used by `pwss` to encrypt
74
+ files with GPG.
75
+
76
+ Note. If you prefer, you can also store files in plain-text or symmetrically
77
+ encrypted with OpenSSL. In these cases, you need to use the `-f` option to
78
+ specify the file format for password files.
79
+
80
+ ### Create a new Password file
81
+
82
+ `pwss init` creates a new password file, `.pwss.yaml.gpg` in your
83
+ home directory.
84
+
85
+ If you want to create multiple password files or store a password file in a
86
+ location of your choice, use the `-f` (`--filename`) option:
87
+
88
+ 1. `pwss init -f MYFILE`
89
+ 2. `pwss add -f MYFILE`
90
+ 3. `pwss get -f MYFILE`
91
+
92
+ The file extension determines whether the file is in plain-text or encrypted.
93
+ More in details, if the file ends in:
94
+
95
+ - ".gpg", `pwss` creates an asymetrically encrypted password file (public-key,
96
+ private-key). This is the default and it has some advantages: it does not
97
+ require a password when adding an entry, it uses GPG mechanism for entering
98
+ passwords (when decrypting the file), it allows you to store the password in
99
+ the system keychain (at least on OSX).
100
+ - ".enc", `pwss` creates a symmetrically encrypted password file. The library
101
+ used is OpenSSL and the algorithm is (AES-256-CBC).
102
+ - any other extension creates a plain text file. This is the simplest and
103
+ less secure scenario. There are situations, however, in which this is
104
+ reasonable. The internal format used by `pwss` is YAML. The password files
105
+ are thus easily editable, when they are in plain text.
106
+
107
+ You can also start from an existing file, as long as it is an array of YAML
108
+ records, each containing, at least, a `title` and, possibly, a `password`
109
+ field. (See section "Under the Hood" for more details.)
110
+
111
+ In this scenario, if can use the following commands, if you want to move to an
112
+ encrypted file:
113
+
114
+ 1. `pwss -f YOURFILE encrypt` to encrypt your existing password file
115
+ 2. `mv YOURFILE.gpg ~/.pwss.yaml.gpg` to move the encrypted file to the
116
+ default location (not necessary, but it simplifies the workflow)
117
+
118
+
119
+ ### Adding Entries
120
+
121
+ `pwss add` adds a new entry, possibly generating a random password.
122
+
123
+ If you prefer to operate on the file using a text editor, you can also `pwss
124
+ decrypt` the file, add the entry by hand, and `pwss encrypt` the file again or
125
+ just edit the file, if you don't care about encrypting your password file.
126
+
127
+ `pwss` supports different types of record, storing different information sets.
128
+ You can use the `-t` option to specify the type of an entry. **Use the command
129
+ `describe` to describe the fields stored by a specific type.**
130
+
131
+ By default `pwss` automatically generates a completely random password for new
132
+ entries. No attempt is made to make password readable or simpler to
133
+ remember. You can use the `-a` option to limit the generator to use only
134
+ digits and letters (\[0-9a-zA-Z\]): this is useful, for instance, for websites
135
+ and applications which accept only certain classes of characters. The option
136
+ `-l` controls the password length.
137
+
138
+ You can also enter the password yourself, using the `--ask` option.
139
+
140
+ After adding an entry, **its password is made available in the clipboard, so
141
+ that it can be used as needed**.
142
+
143
+ Example
144
+
145
+ pwss add
146
+
147
+ adds an entry with a random password of 16 chars. Fields such as title,
148
+ username, etc., will be asked from the console.
149
+
150
+ pwss add -t CreditCard --ask MasterCard
151
+
152
+ adds an entry of type `CreditCard`, whose title is "MasterCard". All the other
153
+ fields, including the password will be asked from the console.
154
+
155
+
156
+ ### Getting Entries
157
+
158
+ `pwss get string`:
159
+
160
+ 1. shows a recap of all entries whose **title** contains `string`
161
+ 2. lets the user choose an entry
162
+ 3. prints the chosen full entry (optionally hiding the sensitive fields)
163
+ 4. makes the password of the chosen entry available in the clipboard for 45
164
+ seconds
165
+
166
+ Use the `-w` option to control how long the password is available in the
167
+ clipboard. At the end of the waiting period `pwss` clears the clipboard.
168
+ **Remark: clipboards with history are not supported. In such cases the
169
+ password will be "pushed" in the clipboard history. You might want to take
170
+ this into account.** Use `0` to keep the password in the clipboard till a key
171
+ is pressed.
172
+
173
+ Use the `--stdout` option to output the password to the console.
174
+
175
+ Example
176
+
177
+ $ pwss get my_email -w 3
178
+
179
+ will retrieve a user selected entry whose title is `my_email` and make
180
+ the password available in the clipboard for `3` seconds.
181
+
182
+
183
+ ### Updating Entries
184
+
185
+ `pwss update --field field string`:
186
+
187
+ 1. shows a recap of all entries whose **title** contains `string`
188
+ 2. lets the user choose an entry
189
+ 3. asks the value for the new chosen `field`
190
+ 4. updates the password file
191
+ 5. if the field is a password, it makes the password available in the
192
+ clipboard
193
+
194
+ Note. `pwss` always asks the user to select or confirm the entry to be
195
+ updated.
196
+
197
+ For instance:
198
+
199
+ $ pwss update my_email -p --method alpha -l 10 -w 20
200
+
201
+ will update a user-chosen (or confirmed) entry whose title matches `my_email`,
202
+ by replacing the existing password with one of length `10` automatically
203
+ generated by `pwss`; the password contains only alphabetic characters and
204
+ digits. The new password is made available in the clipboard for `20` seconds.
205
+
206
+ ### Deleting Entries
207
+
208
+ `pwss destroy string` deletes an entry from a password file matching `string`.
209
+
210
+ Similar to update, the command requires the user to select (multiple matches)
211
+ or confirm (single match) which entry has to be deleted.
212
+
213
+ ### Moving from plain text to encrypted files (and viceversa)
214
+
215
+ You can use the `encrypt` and `decrypt` commands at any time to move from the
216
+ plain to the encrypted format.
217
+
218
+ $ pwss encrypt -f YOURFILE
219
+
220
+ will encrypt `YOURFILE`, while `decrypt` will perform the opposite operation.
221
+ By default password files are encrypted with GPG. You can use the option
222
+ `--symmetric` to change to a symmetric encryption using OpenSSL.
223
+
224
+ If you are using `gpg`, you need to create a gpg key `pwss-agent
225
+ <pwss-agent@example.com>`, as described above (See "Environment Setup:
226
+ Generate a Keypair for PWSS").
227
+
228
+ ### The default safe
229
+
230
+ By default `pwss` operates on `~/.pwss.yaml.enc`. If this file is not
231
+ found, `pwss` will try with `~/.pwss.yaml.gpg` and, if the previous
232
+ two files are not found, with `~/.pwss.yaml`. This allows one to keep
233
+ the file encrypted or in plain text without having to specify `-f`
234
+ every time.
235
+
236
+ If you are not sure which file `pwss` is operating on, use the
237
+ `default` command.
238
+
239
+
240
+ ### The Console
241
+
242
+ Starting from version 0.6.0, `pwss` comes with a console. The main advantage
243
+ is that the file you operate on is cached in memory and the master password
244
+ does not need to be entered any time you perform a query.
245
+
246
+ Note. The advantage is more evident when using symmetric encryption, since GPG
247
+ does not require a password for adding entries and it also already implement a
248
+ caching mechanism, which allows to perform multiple reading operations on a
249
+ password file without entering the password at every command.
250
+
251
+ To start the console, use the command `console`, optionally specifying a file.
252
+ The file is opened and used as the default file for all subsequent commands,
253
+ unless a command is given the `-f` option, in which case the command operates
254
+ on the file specified with `-f`.
255
+
256
+ To change the default file from an open console, use the `open -f` command.
257
+
258
+ Example
259
+
260
+ $ pwss console -f a.yaml.enc
261
+ Enter master password: ....
262
+
263
+ pwss:000> get an entry
264
+ ... (search in a.yaml.enc)
265
+ pwss:001> get another entry
266
+ ... (search in a.yaml.enc, no password asked)
267
+ pwss:002> open -f another_file.yaml
268
+ pwss:003> get another entry
269
+ ... (search in another_file.yaml)
270
+ pwss:004> get -f old.yaml another entry
271
+ ... (search in old.yaml)
272
+ pwss:005> get another entry
273
+ ... (search in the default file, i.e., another_file.yaml)
274
+
275
+ The syntax of the commands available in the console is the same you have
276
+ available from the shell. Type `help` if in doubt.
277
+
278
+
279
+ ### Under the Hood/Editing your file by hand
280
+
281
+ `pwss` adopts a human-readable format for storing passwords, when the file is
282
+ not encrypted, of course! (Unless you have mathematical super-powers and can
283
+ read encrypted text.)
284
+
285
+ The password file store data as an array of YAML records. By default, a
286
+ record contains:
287
+
288
+ - title
289
+ - username
290
+ - password
291
+ - url
292
+ - description
293
+
294
+ Notice that only `title` and `password` are required and
295
+
296
+ Example
297
+
298
+ - title: A webservice
299
+ username: username@example.com
300
+ password: 1234567890
301
+ url: http://www.example.com
302
+ description: |-
303
+ with a password like the one above, who needs a password file?
304
+
305
+ - title: My email
306
+ username: username@example.com
307
+ password: 1234567890
308
+ url: http://www.example.com
309
+ description: >
310
+ Also available via email client, with the following connection parameters
311
+ smtp.example.com
312
+ imap.example.com
313
+
314
+ ### Getting Help and Support
315
+
316
+ If in doubt, type `pwss` to get the list of available commands.
317
+
318
+ $ pwss
319
+
320
+ will show all command options.
321
+
322
+ $ pwss help cmd1 ... cmdN
323
+
324
+ will show the syntax of `cmd1`, ..., `cmdN`.
325
+
326
+ $ pwss man
327
+
328
+ will show the man page.
329
+
330
+
331
+ Changelog
332
+ ---------
333
+
334
+ - **Release 0.6.0** introduces some major changes to functions, command syntax,
335
+ and code structure.
336
+ More in details:
337
+ - `pwss` can now use **GPG** asymmetric encryption, if you wish so.
338
+ To enable `gpg` follow the instructions above. The advantage: no
339
+ need to enter a password for adding data.
340
+ - `pwss` will try different default files, before giving up (in order:
341
+ `~/.pwss.yaml.gpg`, `.pwss.yaml.enc`, `.pwss.yaml`). If
342
+ you are in doubt about which command `pwss` is operating on,
343
+ use the `pwss default` command.
344
+ - added a **console**, which allows to perform multiple operations on the
345
+ same file. When using symmetric encryption, one of the advantages is
346
+ that the password is entered only once. (Similarly for GPG, but in
347
+ this case GPG has password caching built-in.)
348
+ - added a `describe` command to list the entry types and their fields
349
+ - by default a random password is generated when adding
350
+ new entries. Use `--ask` to enter the password interactively
351
+ - added a new option `pwgen`, which uses the
352
+ `pwgen` command line utility for generating password
353
+ - `get` now accepts a specification of the field to copy to the
354
+ clipboard
355
+ - the `get` command now presents only basic fields of the matching
356
+ entries. This hides any sensitive field from view when searching for
357
+ entries. The full entry is shown when chosen, unless the `--hide` option
358
+ is used.
359
+ - a new `--hide` option of the `get` command allows to hide
360
+ sensitive data after a match. In this case you can still
361
+ copy a field using the `--field` option.
362
+ - the ids shown in the list generated by the get command are
363
+ absolute (i.e., the index of the entry in the file). This will
364
+ allow to add a command which gets an entry by ID.
365
+ - new type SIM for SIM cards (fields: title, pin, and puk)
366
+ - new type Code for a secret code (e.g., locker; fields: title and code)
367
+ - dropped support for `created_at` and `updated_at`. No problem if
368
+ an entry has them: `pwss` won't touch them. If you want to remove
369
+ these fields from your entries, use the `--clean-timestamp` option.
370
+ For instance: `pwss list --clean-timestamps > .new-pwss.yaml`
371
+
372
+ Bug fixes:
373
+ - the `list` command now shows the fields of all records always
374
+ in the same order. This fixes a readability problem with
375
+ manually entered fields ... and with the order in which recent
376
+ versions of `pwss` stored fields. If you want to clean your
377
+ password file, use `pwss list`.
378
+ - fixed a long-standing bug when updating the description field.
379
+ Now the field is correctly recognized as multiline and the
380
+ update function works as it should
381
+ - fixed a long-standing bug which stored the closing dot in
382
+ multiline fields
383
+ - fixed some typos in messages
384
+
385
+ - **Release 0.5.1** fixes a bug of the "add" command, which threw an
386
+ error if the title was not supplied on the command line. When adding
387
+ an entry, now it is possible to specify the title on the command
388
+ line or just wait for the title prompt
389
+
390
+ - **Release 0.5.0** This is a release mainly focused on
391
+ improving interaction. It includes small changes to the command
392
+ syntax and improved exit conditions. In details:
393
+ - **add** now accepts the title in the command line. For instance
394
+ `pwss add New Entry`
395
+ - **new** is now an alias for the **add** command
396
+ - **update** now requires to specify the field: use `-p`,
397
+ `--password`, or `--field password`, if you want to update the
398
+ password
399
+ - `pwss` now shows usage summary, if no arguments are given
400
+ - **C-c** is now trapped and properly managed (clearing
401
+ the clipboard)
402
+ - decryption errors are now properly managed
403
+ - the content of the clipboard is now restored after the waiting
404
+ period
405
+
406
+ - **Release 0.4.0**
407
+ - New `--stdout` option will output password to standard output
408
+ (useful for integration with other applications)
409
+ - New `--select N` option will automatically select the `N`th
410
+ entry (rather than asking the user to select an entry).
411
+
412
+ - **Release 0.3.0**
413
+ - internal refactoring: CLI parsing is now based on
414
+ [Slop](https://github.com/leejarvis/slop). The documentation has
415
+ been revised and should now be simpler to understand.
416
+ - added some controls to avoid overwriting existing files (in
417
+ particular: init, encrypt, and decrypt). The command is now less
418
+ Unix-like, but I hope you will appreciate a bit more safety.
419
+
420
+ - **Release 0.2.0** (never really made it to the public -- use
421
+ version 0.3.0)
422
+ - it is now possible to add entries of various types (= with
423
+ different fields). The supported types include: CreditCard,
424
+ BankAccount, SoftwareLicense. Use the -e (--entry) option to
425
+ specify the type of entry to add
426
+ - an empty string can now be used to exit (instead of -1) when
427
+ multiple matches are found
428
+
429
+ - **Release 0.1.0**
430
+ - the update command now allows one to update the password or any
431
+ other field of existing entries
432
+ - a simple password generator allows pwss to generate a random
433
+ password
434
+ - most commands make the password of the selected entry available
435
+ in the clipboard (useful, for instance, if you automatically
436
+ generate a password)
437
+ - a destroy command allows one to delete an entry from a password
438
+ file. Similar to get, all entries matching a query are shown. The user
439
+ is then asked to select which entry has to be deleted or stop.
440
+ User confirmation is required even in case of a single match.
441
+
442
+ License
443
+ -------
444
+
445
+ Licensed under the terms of the MIT License.
446
+
447
+ Contributing
448
+ ------------
449
+
450
+ 1. Fork it (http://github.com/<my-github-username>/pwss/fork )\
451
+ 2. Create your feature branch (`git checkout -b my-new-feature`)\
452
+ 3. Commit your changes (`git commit -am 'Add some feature'`)\
453
+ 4. Push to the branch (`git push origin my-new-feature`)\
454
+ 5. Create new Pull Request