olcf / pkpass

PKI based password manager

PKPass: Public Key Based Password Manager

RTD

https://pkpass.readthedocs.io/en/latest/

Requires >= Python 3.6

Overview

This is a basic password store and password manager for maintaining arbitrary secrets.

The password management solution provides:

• Encryption at Rest
• Password distribution/organization based on definable hierarchies
• Password creation timestamps
• Password history and change logs
• Distributed backup capabilities
• PIV/Smartcard Credential encryption/decryption
• Import and export functionality

Passwords that are created are distributed to recipients by public key encryption. The x509 certificate of the intended recipient is used to create an encrypted copy of the distributed password that is then saved in a password-specific git repository. Multiple encrypted copies of the secret are created, one for each user. End users then check out the git repo and are able to read passwords using their PIV/Smartcard credential to decrypt.

Install

Everything:

pip install pkpass-olcf

MacOs:

brew install olcf/tap/pkpass

x509 Certificate Repository

PKPass needs a trusted x509 certificate repository, which typically is managed using git. Certificates in this repository should all be signed by Certificate Authorities that can be found in the CABundle file that PKPass is configured to look at. Since this repository should be considered 'trusted', it is typically managed by a smaller trusted set of site administrators. PKPass validates all encryption certificates as they are used to make sure they are signed by a trusted Certificate Authority (CA).

You may also use a local x509 certificate repository that you sync with others using RSYNC, NFS, shared volumes, etc. You can configure the directory that pkpass will use for the certificate repository either on the command line, or through the .pkpassrc file.

The CABundle file to use can also be configured in the .pkpassrc file or on the command line.

Additionally, certificates should be named .cert. For example, the certificate for user 'jason' should be named 'jason.cert' inside this x509 directory.

Password Repository

PKPass also needs a directory to serve as a 'password database'. Like the x509 certificate repository, it is also typically managed with git to provide change control, history, and tracking of changes. Local directories can also be used and shared via rsync, NFS, shared volumes, etc if preferred.

To change the default password repository, you may specify another directory on the command line or in the .pkpassrc file.

pkpass's Issues

EOF (Ctrl-D) does not exit interpreter

The interpreter does not cleanly exit upon receiving an EOF, instead treating it as a command:

% pkpass
Welcome to PKPass (Public Key Based Password Manager) v2.7.8!
Type ? to list commands
pkpass> ^DCommand 'EOF' not found, see help (?) for available commands
pkpass>

Better user Errors for decryption

There are other instances that a decryption error happens than what is display in the error message

• no smartcard detected

  • selected card out of range of available slots
  • reader malfunction

• distributed to an older certificate

It would be nice if we could clean this up to allow for a less confusing user experience.

Clean up formatting of README

Several places in the readme there are bad formatting blocks that should really be in a code block.

Also, make it read a bit better so that people new to pkpass don't have to make so many assumptions

Setup script is a bash file

There's nothing particularly bad about having the bash file; but windows peeps won't be able to use it. We can keep the bash file in the event someone likes it. But we should add a setup.py

pkpass distribute should list recipients

When running pkpass distribute we should list the users that will get the password.

Card operations fail if in yubi mode, and non yubi reader is present.

% pkpass card
####################
Yubico YubiKey OTP+FIDO+CCID
Cherry GmbH SmartTerminal XX44
####################

Using SlotYubico YubiKey OTP+FIDO+CCID


PKPassError: Unsupported SC type for backend yubi.
Yubico not in:
Cherry GmbH SmartTerminal XX44

Allow promoted draft releases to trigger workflows

The created type in .github/workflows/pythonpublish.yml prevents draft releases later published from triggering workflows.

Add cert connector functionality

We should be able to use local and remote cert fetches

Catch yaml formatting errors

Do a better job checking for malformatted yaml and let the user know in nice non-stack traceable way.

Create escrow capability

Let users set a list of 'escrow' users that get passwords automatically encrypted for them if the credentials exist. Maybe this should by default be an 'escrow' user name.

Sites can put pre-commit hooks into their password-related git repositories to see if all yaml files include encrypted passwords for the escrow users. It's up to the sites to only merge passwords that have also been sent to escrow accounts

Interpreter mode crashes out on empty line

Providing an empty line to the interpreter results in a crash:

 % pkpass
Welcome to PKPass (Public Key Based Password Manager) v2.7.8!
Type ? to list commands
pkpass>
Generic exception caught:
	IndexError: list index out of range

Investigate removal of name from metadata

removing name from metadata would allow user to manually move password files around hopefully safely.

Create a user-runnable setup script

Let's create a setup script that users can run to help them create .pkpassrc and other files. Migrate certificates, and point them at the certificate store that they are setting up.

The script could also test to see if their environment is good and if openssl and pkcs15-tool things work.

openssl new warning for reading cert from stdin

pkpass/libpkpass/crypto.py

Line 363 in b006e07

return stdout.decode("UTF-8").rstrip()

need to strip a new openssl warning when reading from stdin

`git` interpreter command splits args unexpectidly

When using the interpreter-exclusive git command, quoted args are split on spaces, instead of being preserved.

Expectation:
git commit -am "chore: update example password"
(expands to ["git" "commit" "-am" "chore: update example password"])
[some_branch a1b2c3d] chore: Update Example Password
base/example/password +- 1

Reality:
git commit -am "chore: update example password"
(expands to ["git" "commit" "-am" "chore:" "update" "example" "password"])
fatal: paths 'update ...' with -a does not make sense

Creating password from stdin is not supported

ryan@hackbookpro:~/git/pkpass$ echo "whargarbl" | pkpass create --stdin testpw3
Enter Pin/Passphrase:
Enter password to create:

BlankPasswordError: User Provided password is blank or only spaces

allow distributing mutliple passwords at once

Description

We should allow a user to submit a list of password names to distribute, including the use of file globbing to allow for a well known short hand. This decreases the interactive need for bringing a new user onto a team where they need access to the team's passwords.

Note on file globbing

When using file globbing, pkpass should confirm with the user what password list is being distributed for verification.

Examples

• pkpass.py distribute pass1 pass2 pass3 pass4 -g test_group -u new_user
• pkpass.py distribute pass* -g test_group -u new_user

Better Exception Handling

Catch exceptions related to directories not existing for cert/key/passdb directories

Escrow users overwritten issue

There is a defect in the way escrow users work:
Given 2 users for the same password, lets say ngin and ginsburg
ngin escrows: a b c
ginsburg escrows c d e

ginsburg's c user would overwrite ngin's c user for this password. meaning users a and b may not be able to help recover the password.

Add specific card reader whitelisting and blacklisting capability

See pkcs11-tool with 3 card readers: One ACS white usb-c and two ubi-key usbc readers:

ryan@lappy486:~/git$ pkcs11-tool -L
Available slots:
Slot 0 (0x0): Yubico Yubikey 4 CCID 01
  token label        : PIV_II (PIV Card Holder pin)
  token manufacturer : piv_II
  token model        : PKCS#15 emulated
  token flags        : rng, login required, PIN initialized, token initialized
  hardware version   : 0.0
  firmware version   : 0.0
  serial num         : 879b355cb9eeff59
Slot 1 (0x4): ACS ACR39U ICC Reader
  token label        : PIV_II (PIV Card Holder pin)
  token manufacturer : piv_II
  token model        : PKCS#15 emulated
  token flags        : rng, login required, PIN initialized, token initialized
  hardware version   : 0.0
  firmware version   : 0.0
  serial num         : 4ce48d80a610d7eb
Slot 2 (0x8): Yubico Yubikey 4 CCID
  token label        : PIV_II (PIV Card Holder pin)
  token manufacturer : piv_II
  token model        : PKCS#15 emulated
  token flags        : rng, login required, PIN initialized, token initialized
  hardware version   : 0.0
  firmware version   : 0.0
  serial num         : 780a6656470c55be

We can detect and prefer serial numbers, manufacturers, or slots

Validate/Verify some paths before using them

Here, we are getting a trustchain verification error, but we should be checking to see if the ca.bundle file is correct and exists before we even try to run our openssl command.

TrustChainVerificationError: Error loading file /Users/uua/passdb/cabundles/ca.bundle
95931:error:02001002:system library:fopen:No such file or directory:/BuildRoot/Library/Caches/com.apple.xbs/Sources/OpenSSL098/OpenSSL098-64.50.7/src/crypto/bio/bss_file.c:126:fopen('/Users/uua/passdb/cabundles/ca.bundle','r')
95931:error:2006D080:BIO routines:BIO_new_file:no such file:/BuildRoot/Library/Caches/com.apple.xbs/Sources/OpenSSL098/OpenSSL098-64.50.7/src/crypto/bio/bss_file.c:129:
95931:error:0B084002:x509 certificate routines:X509_load_cert_crl_file:system lib:/BuildRoot/Library/Caches/com.apple.xbs/Sources/OpenSSL098/OpenSSL098-64.50.7/src/crypto/x509/by_file.c:274:
usage: verify [-verbose] [-CApath path] [-CAfile file] [-purpose purpose] [-crl_check] [-engine e] cert1 cert2 ...
recognized usages:
	sslclient 	SSL client
	sslserver 	SSL server
	nssslserver	Netscape SSL server
	smimesign 	S/MIME signing
	smimeencrypt	S/MIME encryption
	crlsign   	CRL signing
	any       	Any Purpose
	ocsphelper	OCSP helper

Interpreter reload on exit of edit command.

Allow full cache refresh while using interpreter, currently this scope is only pertaining to

• cwd
• recipient database

Add Yubico PIV Tool backend for crypto operations

Add an optional Yubico PIV Tool based backend for crypto operations to work in parallel with the existing OpenSC option.

AttributeError: 'Update' object has no attribute '_convert_strings_to_list'

Regression issue: can't modify user list in update

Feature Suggestion: verifyinstall for Alternate Backend

The verifyinstall command does not work using the alternate backend of yubico-piv-tool and libp11. Extending its functionality would assist users to install and configure using the alternate backend.

pkpass verifyinstall
Starting installed software check
The following packages were not found: 
	pkcs15-tool (available via opensc)

use schema version to decide decryption

This is an issue with the way I did legacy schemas. I forgot there's a schema version marker, and just embedded a try except.

Due to this, there exists a side effect of passwords existing as schema version 2 even though the file states version 1. cleanup will be necessary.

Test Case Coverage

We would like to increase code test case coverage. Some parts of this are inherently difficult; but if we can get the current functioning commands (create, distribute, list, list recipients, and show) all with some form of test cases (with the knowledge that some of this work is done at the time of ticket creation) then I would mark this as complete.

• create
• distribute
• list
• list recipients
• show

Update docs for Yubico PIV Tool backend for crypto operations

Add docs to go with #208

openssl changes

rsautl has been deprecated and is causes issues within unit tests on github actions, it's currently still working as expected on my local linux instance.

Additionally the fingerprint hash default has changed from sha1 to sha256, this screws up indexing since we initially didn't specify a type.

pkpassrc is in repo directory

I think pkpassrc file should be in the home directory by default; this allows users to keep their pkpassrc file in the event they remove the repo.

Show 'verbose' errors only if verbose is true

As an example: If the ca.bundle does not exist or is not valid, we can end up seeing a stack trace, due to the way that we print error messages that we gather. It's pretty easy to see that we're getting that trustchainverificationerror, but maybe we don't want to see the full output/stack trace of the exception that we caught unless we're running in verbose mode. In this case, just the first line may be sufficient and we can mask the openssl output when something goes funky.

TrustChainVerificationError: Error loading file /Users/uua/passdb/cabundles/ca.bundle
95931:error:02001002:system library:fopen:No such file or directory:/BuildRoot/Library/Caches/com.apple.xbs/Sources/OpenSSL098/OpenSSL098-64.50.7/src/crypto/bio/bss_file.c:126:fopen('/Users/uua/passdb/cabundles/ca.bundle','r')
95931:error:2006D080:BIO routines:BIO_new_file:no such file:/BuildRoot/Library/Caches/com.apple.xbs/Sources/OpenSSL098/OpenSSL098-64.50.7/src/crypto/bio/bss_file.c:129:
95931:error:0B084002:x509 certificate routines:X509_load_cert_crl_file:system lib:/BuildRoot/Library/Caches/com.apple.xbs/Sources/OpenSSL098/OpenSSL098-64.50.7/src/crypto/x509/by_file.c:274:
usage: verify [-verbose] [-CApath path] [-CAfile file] [-purpose purpose] [-crl_check] [-engine e] cert1 cert2 ...
recognized usages:
	sslclient 	SSL client
	sslserver 	SSL server
	nssslserver	Netscape SSL server
	smimesign 	S/MIME signing
	smimeencrypt	S/MIME encryption
	crlsign   	CRL signing
	any       	Any Purpose
	ocsphelper	OCSP helper

Create 'proxy' or 'on behalf of' functionality for reading secrets

A user who is authorized to have knowledge of another user's private key should be able to decrypt that user's secrets with a single invocation of pkpass.

For example, a team of systems administrators all need to know a database password. A keypair for the database exists so that the system the database runs on can deploy the password, and the systems administrators are all distributed the private key for the database keypair.

Given pkpass users 'user' and 'db' (db is an automated 'system' user), with user.cert, db.cert, and db.key stored in the appropriate directories, allow user to decrypt passwords 'on behalf of' db as long as user has been issued db's private key.

Something like this:
pkpass show -i user -b db database_password

Someone would have needed to distribute 'db.key' to user as a secret and pkpass would need to be able to find that secret, decrypt it using user's piv badge, and then use the decrypted private key to decrypt 'database_password'

Dedup password names

We don't need password names to be entered twice.

Let's set the password name of the password to be the name entered on the command line when passwords are created.

We should check during password read operations that the name field in the .yaml and filename are the same, and tell the user if something is fishy.

Turning off the validate flag can quiet these errors.

Make pkpass easier to run without a .pkpassrc file

Fully implement import/export functionality

Error when no private key directory found

Pkpass fails with:

(pkpass) ryan@ryansapro:~/git/pkpass$ ./pkpass.py create
Enter Pin/Passphrase: 

FileOpenError: File ./private found in config, could not be opened due to No such file or directory

When 'private' is not in the pkpassrc file. 'private' does not need to be defined for a successful run (i.e. when using a smartcard) so this should be a warning.

MacOs tempdir

MacOs's idea of a temp directory is
/var/folders/{unpredictable_crap}/{unpredictable_crap}/{more_crap}/
instead of
/tmp

sooo... hardcode this garbage to /tmp if is a mac?