janlelis / pws

Command-Line Password Safe 🔐︎

A Clipboard based CLI Password Safe

pws is a command-line password safe/manager written in Ruby using AES-256-CBC and PBKDF2.

2023 Notice!

Although the gem works well and as described, its cryptographic foundations have not been updated since 10 years ago and might not reflect current best practices.

Usage

Setup

Make sure your computer has Ruby installed.

You can then install pws with: $ gem install pws

Run $ pws --help for usage information.

If you use pws on Linux, you will need to have xsel or xclip installed (for the clipboard to work).

Tips & Troubleshooting

How to use a .pws file in the current working directory

Besides using the --filename path/to/safe option, you can shortly call pws --cwd for using a .pws file in the current directory.

Check the .pws into version control and you have a great way to share a project's passwords within your team.

OpenSSL 1.0

You should use a Ruby that was built with bindings to an openssl version >= 1.0 or pws will fall back to a Ruby-only version of the PBKDF2 function, which is much slower. If using openssl 1.0 is not possible for you, you can work around that issue by using the --iterations option with a value below 75_000 (see help). If you have problems using openssl 1.0 with your Ruby, please look for a solution in this issue.

Updating from pws 0.9

The 0.9 password files are not compatible with the 1.0 version of pws, however, you can convert your safe with: $ pws resave --in 0.9 --out 1.0

Reading the source

Trust the code by reading the source! It's originally based on this tutorial. You might want to start reading in the 0.9.2 tag, because it's got less features and therefore is less code.

Projects built on top of PWS

• pws-otp Experimental OTP support for 2FA
• pwsqr Simple QR interface to pws gem. Helps to use your passwords on a smartphone.
• aws-pws A password-protected CredentialProvider for AWS
• omnivault Multi-platform keychain functionality

Blog Articles

• Packaging ruby programs in NixOS using PWS as example

Contributors

• namelessjon
• brianewing
• dquimper
• grapz
• thecatwasnot (cucumber specs loosely based on these)
• terabyte
• alex0112

J-_-L

© 2010-2021 Jan Lelis, MIT license

pws's Issues

PWS not adding my password to clipboard.

Hello.

Thank you for your magnificent work with this tool. Unfortunately I cannot manage PWS to work on my machine:

Specs:
OS: ArchLinux (x86_64)
Uname: Linux localhost 3.10.10-1-ARCH #1 SMP PREEMPT Fri Aug 30 11:30:06 CEST 2013 x86_64 GNU/Linux
Ruby: MRI 2.0.0-p247 (via RVM, pws is installed in @global gemset)
DE: KDE 4.11.0 (Klipper 0.9.7 is running)

What works:

• Adding passwords
• Listing keys
• Generating new passwords

What doesn't work:

• Getting my passwords.

Console log:

# assuming:
alias pwdstore='pws --filename /my/store/path'

master ✗ $ pwdstore get <key>
ACCESS GRANTED
The password for <key>
 is now available in your clipboard for 10 seconds

It's a really great tool and I want to use it right now. I hope you'll read this issue and at least try to help me ;).

Yours,
Marcin

Failing Cucumber Test

Summary:

On a fresh clone of the project I get a failing test:

Failing Scenarios:
cucumber features/show.feature:47 # Scenario: Also shows last change date for each entry

Steps to reproduce:

• macOS High Sierra 10.12.6
• ruby 2.5.0p0 (2017-12-25 revision 61468) [x86_64-darwin17]
  bundle exec rake spec

Detailed output:

Scenario: Also shows last change date for each entry                                                                                        # features/show.feature:47
    Given A safe exists with master password "my_master_password" and a key "github" with password "github_password" and timestamp "42424242" # features/step_definitions/pws_steps.rb:35
    When I run `pws show` interactively                                                                                                       # aruba-0.5.4/lib/aruba/cucumber.rb:104
    And I type "my_master_password"                                                                                                           # aruba-0.5.4/lib/aruba/cucumber.rb:108
    Then the output should contain "Entries"                                                                                                  # aruba-0.5.4/lib/aruba/cucumber.rb:131
    And the output should contain "github"                                                                                                    # aruba-0.5.4/lib/aruba/cucumber.rb:131
    And the output should contain "71-05-07"                                                                                                  # aruba-0.5.4/lib/aruba/cucumber.rb:131
      expected "Access password safe at /Users/alex/prog/pws/pws-test-45d7e9e2-45c9-4423-93ab-0012c03332b0 | Master password: ACCESS GRANTED\nEntries in /Users/alex/prog/pws/pws-test-45d7e9e2-45c9-4423-93ab-0012c03332b0\n- github 71-05-06\n" to include "71-05-07"
      Diff:
      @@ -1,2 +1,4 @@
      -71-05-07
      +Access password safe at /Users/alex/prog/pws/pws-test-45d7e9e2-45c9-4423-93ab-0012c03332b0 | Master password: ACCESS GRANTED
      +Entries in /Users/alex/prog/pws/pws-test-45d7e9e2-45c9-4423-93ab-0012c03332b0
      +- github 71-05-06
       (RSpec::Expectations::ExpectationNotMetError)
      ./features/support/env.rb:32:in `block in <top (required)>'
      features/show.feature:53:in `And the output should contain "71-05-07"'

Add username support

How about adding support for saving usernames as well?

Various Tests fail (some ruby-2.0 specific)

Repro:

rvm use ruby-2.0.0-p195@pws --create
gem install bundler; bundle install
rake spec

Observe 1 spec fails

Failures:

  1) PWS::Format::V1_0 misc generates the same kdf, no matter which implementation
     Failure/Error: PWS::Format::V1_0.kdf_ruby(password, salt, iterations).should ==
     TypeError:
       nil can't be coerced into Fixnum
     # ./lib/pws/format/1.0.rb:150:in `kdf_ruby'
     # ./spec/pws_format_1_0_spec.rb:179:in `block (3 levels) in <top (required)>'

Finished in 1 minute 19.92 seconds
65 examples, 1 failure

Do the same with ruby-1.9.3-p429 and specs pass, so it is probably a ruby 2.0 breakage. I ran it several times to ensure it wasn't just a random flake.

In related news, under ruby 1.9.3, some cucumber tests fail:

Failing Scenarios:
cucumber features/add.feature:48 # Scenario: Set a new password for "github", this also sets the timestamp
cucumber features/show.feature:47 # Scenario: Also shows last change date for each entry
cucumber features/update.feature:48 # Scenario: Set a new password for "github", this also sets the timestamp

81 scenarios (3 failed, 78 passed)
515 steps (3 failed, 512 passed)
1m51.225s

Again, I ran several times to confirm it wasn't just flakes. All three tests reliably failed on my machine (using the procedure I outlined above).

I will try to figure it out and submit a pull request if I have time to investigate further. I may also have some security improvements and/or additional features in future pull requests (will probably be a new version of the data format, V1.1 or something, with more rounds).

Thanks!
-Carl

Export feature

Storing your passwords safely is fine and dandy, but you definitely want to be able to export and/or back up your safe properly. While checking your safe files into whatever backup system you use might be fine, I'd still be more comfortable if I was able to export everything into a human readable format, in case I decide to no longer use pws, or if I have to access my stuff on a system that's unable to run pws.

Always Error "Key must be 32 bytes"

Hi,
i am trying to create a new pws safe but every password i enter is being rejected with the error message "Key must be 32 bytes". I checked the passwords byte length with other password safes like KeePass. I am using ruby2.4 and the latest version of pws.

Well after an afternoon of trying and searching i found this: attr-encrypted/encryptor#26
It is an Error of the OpenSSL Library.

pws doesn't work with ruby 2.2 because of cannot load such file -- digest/hmac (LoadError)

/home/rupert/.rvm/rubies/ruby-2.2.0/lib/ruby/2.2.0/rubygems/core_ext/kernel_require.rb:54:in require': cannot load such file -- digest/hmac (LoadError)`

Copying to clipboard in cygwin

The copying to clipboard does not work in cygwin. Can it be configured to use the putclip or /dev/clipboard feature in cygwin ?

Add support for alphanumeric/simple password generation

Problem

I often find myself needing to generate a password where characters such as ' " \ or a backtick are not allowed.

A while back the --exclude flag was added in #23, but I often find myself hitting this scenario:

$ pws gen example-passwd --exclude '\\`\'"'
dquote>

Usually I'm too lazy to figure out the proper quoting conventions for these characters in my current shell, and often my workflow for sites that block characters like these is to do this:

pws gen example-passwd --charpool 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz1234567890!@#$%^&*()_-+='

Which works, but is a bit much in terms of manual typing.
Even then, sometimes sites will reject some of those characters. So I end up defaulting to:

pws gen example-passwd --charpool 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz1234567890'

Proposed Solution:

Add two new options:

• --alphanumeric to generate a password only matching the character class [A-Za0-9a-z]
• --simple to generate a password only matching the character class [0-9a-zA-Z!@#$%^&*()]

I've taken the liberty of prototyping a few Gherkin tests about what the end behavior might look like:

Scenario: Generate a new password for "github", using only alphanumeric characters
    Given A safe exists with master password "my_master_password"
    When I run `pws generate github 0 --alphanumeric` interactively
    And I type "my_master_password"
    Then the output should contain "Master password:"
    And the output should contain "The password for github has been added"
    And  the output should contain "The password for github has been copied to your clipboard"
    And  the clipboard should match ^[0-9a-zA-Z]{64}$
Scenario: Generate a new password for "github", using only alphanumeric and no special characters
    Given A safe exists with master password "my_master_password"
    When I run `pws generate github 0 --basic` interactively
    And I type "my_master_password"
    Then the output should contain "Master password:"
    And the output should contain "The password for github has been added"
    And  the output should contain "The password for github has been copied to your clipboard"
    And  the clipboard should match ^[0-9a-zA-Z!@#$%^&*()]{64}$

Feature Request: Interactive shell

It would be nice to cache the password across multiple commands - this was the inspiration of the "multiadd" command I implemented - but sometimes I will be adding passwords in bulk then want to fix a typo, rename a password, remove it, change it, etc. When I am doing password maintenance tasks having to retype the pw multiple times is a pain.

I know the longer the process runs, the higher the danger of an attacker stealing the password out of memory (or it being swapped to disk) since you can't control that stuff in ruby, but as long as the user understands the risk, it seems to me a prompt which lets the user input commands interactively without re-entering the password would be great. The shell could automatically exit after some timeout (10 or 30 seconds) to prevent people from leaving it running when they are not actively using it.

I may try to implement this as well, just throwing the idea out there for discussion.

-Carl

Feature: Disallowed chars

Currently pws gen churns out a nice long random string of characters. This is great, except when certain characters are disallowed in a password, such as quotes ' ".

Feature request to disallow certain characters/specify only alphanumeric character sets when running pws gen.

pbkdf2_hmac() function is unimplemented on this machine

Hi,

I've updated to 1.0 and I'm trying to convert to the new file format, and got this error:

~$ pws resave --in 0.9 --out 1.0
ACCESS GRANTED
/Users/alx/.rvm/gems/ruby-1.9.2-p290/gems/pws-1.0.0/lib/pws/format/1.0.rb:127:in `pbkdf2_hmac': pbkdf2_hmac() function is unimplemented on this machine (NotImplementedError)
    from /Users/alx/.rvm/gems/ruby-1.9.2-p290/gems/pws-1.0.0/lib/pws/format/1.0.rb:127:in `kdf'
    from /Users/alx/.rvm/gems/ruby-1.9.2-p290/gems/pws-1.0.0/lib/pws/format/1.0.rb:35:in `encrypt'
    from /Users/alx/.rvm/gems/ruby-1.9.2-p290/gems/pws-1.0.0/lib/pws/format/1.0.rb:20:in `write'
    from /Users/alx/.rvm/gems/ruby-1.9.2-p290/gems/pws-1.0.0/lib/pws/format.rb:52:in `write'
    from /Users/alx/.rvm/gems/ruby-1.9.2-p290/gems/pws-1.0.0/lib/pws.rb:244:in `write_safe'
    from /Users/alx/.rvm/gems/ruby-1.9.2-p290/gems/pws-1.0.0/lib/pws.rb:196:in `resave'
    from /Users/alx/.rvm/gems/ruby-1.9.2-p290/gems/pws-1.0.0/lib/pws/runner.rb:135:in `public_send'
    from /Users/alx/.rvm/gems/ruby-1.9.2-p290/gems/pws-1.0.0/lib/pws/runner.rb:135:in `run'
    from /Users/alx/.rvm/gems/ruby-1.9.2-p290/gems/pws-1.0.0/bin/pws:4:in `<top (required)>'
    from /Users/alx/.rvm/gems/ruby-1.9.2-p290/bin/pws:19:in `load'
    from /Users/alx/.rvm/gems/ruby-1.9.2-p290/bin/pws:19:in `<main>'

My machine: macbook air 13" 2011, osx Lion 10.7.4, ruby 1.9.2-p290

Ask password twice while adding too?

The request is pretty straightforward, it'll be nice if pws asks for password recheck while adding too.

If you are comfortable with it, I'd love to make a PR :)

Feature: print password, and authenticated session

It would be awesome if we could have an authenticated session; and print password.

My use case is the following:
my .bashrc file grabs various ENV variables eg. AWS_SECRET_PASSWORD from a tool (such as pws).
something like:

AWS_SECRET_KEY=$(pws get aws_secret_key)

but I also would not want to do if there is plenty of keys

AWS_SECRET_KEY=$(pws get --print aws_secret_key)
FOO_SECRET=$(pws get --print foo_secret)

so having something like:

pws login # prompts for the password (maybe with an auto-log out)

AWS_SECRET_KEY=$(pws get --print aws_secret_key)
FOO_SECRET=$(pws get --print foo_secret)

pws logout

I know this is a lot to ask for, but just throwing up this idea.