PWCLIP(1)

NAME
pwclip - pwclip documentation

DESCRIPTION

pwclip is a password management tool. It's main target is having fast and comfortable access to passwords by storing them for a variable time in the systems clipboard (copy/paste buffer). It uses either GnuPG2 or OpenSSL (converted to GPGSM) keys for cryptographic operations. It also works with yubikey's challenge-response to generate uniq HMAC-SHA1 hashes as well. Windows support is volatile while i myself don't need it - bugreports or merge requests for features are very welcome: https://github.com/d0n/pwclip

The main feature is the pwcli/pwclip mode which provides easy access to the ~/.passcrypt file. That file is used by default as password storage. The program is executed in gui mode when pwclip is called and in cli mode when pwcli is called respectivly. It creates the ~/.passcrypt file which is gpg encrypted text using either the value of GPGKEY and/or RECIPIENTS from the user's environment as gpg-key for en/decrypting key/recipients. On startup it looks for a ~/.pwd.yaml file which is merged with the already known passwords from the ~/.passcrypt file if there already is one. All entrys in the ~/.passcrypt file will be overridden by entrys from the ~/.pwd.yaml file. Of course adding, removing or changing password entrys is also possible using pwcli(p) - see pwclip --help or man pwclip for details.

The second operating mode is for operating on yubikeys to generate uniq responses which might be used as passwords while they can be generated by that exact yubikey only. The first yubikey found on the system and the first slot, configured with (HMAC-SHA1) challenge-response, will be used.

To catch user input python's Tk (tkinter) library is used to create a simple password input window. The appropriate response is saved for only 3 seconds by default to not have it exposed as soon as it has been used. For the timer another environment variable used if set - PWCLIPTIME. The value of that variable is obviously used for setting the time to switch back to what you had in the clipboard bevore using pwclip. Optionally there is a text notification displayed on the screen if the comment field is set. It's intension is having a reminder for something attached to a login which is safe exposing to eyes watching what's on screen. Therefor python3's gi module's notify2 is used.

I would encourage you to bind pwclip to a shortcut within your X-Environment to have access to your passwords at any time. On Windows-Systems you need to create a link for it somewhere. When editing that link you may set a keyboard shortcut (could not find a nicer solution by now). The target for that link then whould be "%PYTHONINSTALLDIR%\scripts\pwclip.exe".

I've been trying my best to keep the passwords from unwanted access BUT i do !NOT GUARANTEE! that the passwords handled during runtime are safe from other users access (especially "root" on linux systems - help on that is very welcome) - please be aware of that!

Since version 1.2 openssl keys are supported. For the use with pwclip they will be converted to gpg-keys automaticly and gpgsm is used instead of gpg - openssl is not used for en/decryption to be precisely.

The ~/.pwd.yaml as well as the ~/.passcrypt file is assembled as a list of one or more users which should be named like the username used for current system login. You may have more than one users passwords in the passcrypt but any user who can store passwords also is able to read password stored for other users in that file. It is just of use for visual kategories if you have stored passwords for different systems users sharing the same passcrypt file. As an example: Whatever parson has a username called "bob" on one machine, and on some other machine he has a username called "cat". For both of them a different password is stored. If loged in as the user the ssh password was added to by default pwclip will look for the password entry under the currently loged-in user. The shared passcrypt file would be assembled like the attached YAML-Format section. If so providing -u or -A when beeing logged in as "bob" or "cat" respectivly can be omitted. If in doubt you're able to read the crypt file using "gpg -d ~/.passcrypt" as well (assuming the correct gpg-key is present).

YAML-FORMAT

---

bob:
    - ssh: - $om3(rypt!cPass

    - DoNotForgetSomethingReminder

    - othertool: - 0th3r(rypt!cPass

cat:
    - ssh: - $om30ther(rypticPass

SYNOPSIS
pwclip [options]

OPTIONS

--version
    show program's version number and exit

-D, --debug
    debugging mode

-A, --all
    switch to all users entrys ("d0n" only is default)

-o, --stdout
    print password to stdout (insecure and unrecommended)

-s, --show-passwords
    show passwords when listing (replaced by "*" is default)

-t seconds
    time to wait before resetting clip (3 is default)

-p PWD, --password PWD
    enter password for add/change actions (insecure & not recommended)

--comment COM
    enter comment for add/change actions

-R  use remote backup given by --remote-host

--remote-host HOST
    use HOST for connections

--remote-user USER
    use USER for connections to HOST ("d0n" is default)

-r ID ... , --recipients ID ...
    one ore more gpg-key ID(s) to use for encryption (strings seperated by spaces within "")

-u USER, --user USER
    query entrys only for USER (-A overrides, "d0n" is default)

-x, --x509
    force ssl compatible gpgsm mode - usually is autodetected (use --cert & --key for imports)

-C SSL-Certificate, --cert SSL-Certificate
    one-shot setting of SSL-Certificate

-K SSL-Private-Key, --key SSL-Private-Key
    one-shot setting of SSL-Private-Key

--ca SSL-CA-Certificate, --ca-cert SSL-CA-Certificate
    one-shot setting of SSL-CA-Certificate

-P CRYPTFILE, --passcrypt CRYPTFILE
    set location of CRYPTFILE to use as password store (~/.passcrypt is default)

-Y YAMLFILE, --yaml YAMLFILE
    set location of YAMLFILE to read whole sets of passwords from a yaml file (~/.pwd.yaml is default)

-S {1,2}, --slot {1,2}
    set one of the two yubikey slots (only useful with -y)

-y [SERIAL], --ykserial [SERIAL]
    switch to yubikey mode and optionally set SERIAL of yubikey (autoselect serial and slot is default)

-a ENTRY, --add ENTRY
    add ENTRY (password will be asked interactivly)

-c ENTRY, --change ENTRY
    change ENTRY (password will be asked interactivly)

-d ENTRY [ENTRY ...], --delete ENTRY [ENTRY ...]
    delete ENTRY(s) from the passcrypt list

-l [PATTERN], --list [PATTERN]
    pwclip an entry matching PATTERN if given - otherwise list all entrys

USAGE
Although is was planed as GUI-Program it's also possible to be executed from terminals. For Windows, Linux and OSX there is an appropriate executable packed which might be executed like the following examples will show:

-GPG-Mode-

If there is an environment variable called GPGKEYS it will use those keys to encrypt on changes to the password file. To list the password file you may use the list switch followed by optional search pattern like:

pwcli -l

or

pwcli -l $PATTERN

as you can see the yaml format tends to be used for multiple user names to better manage large lists. By default the current users entrys will be listed only. To have them all listed (or searched for by the above pattern example) use:

pwcli -A -l $PATTERN

To one-shot convert a key/cert pair in openssl x509 format, read passwords from passwords.yaml and list them:

pwcli -Y passwords.yaml --cert ssl.crt --key ssl.key --ca-cert ca.crt -l

-Yubikey-Mode-

The YKSERIAL environment variable is used if found to select the yubikey to use if more than one key is connected. Otherwise the first one found is chosen. Likewise it also accepts an option:

pwcli -y $YKSERIAL

To have it wait for a specific time like 60 seconds (bevore resetting the paste buffer to the previously copied value) the PWCLIPTIME environment variable is used or also the command accepts it as input:

pwcli -t 60 -l somename

Most of the options may be combined. For more information on possible options in cli mode please see:

pwcli --help

-GUI-Modes-

For the GUI-Mode just use one of the following commands, also accepting most of the commandline arguments:

pwclip

ykclip

TROUBLESHOOT

There are currently no known issues

Obsolete:

When using the yubikey challenge-response mode there is a bug in the usb_hid interface. This is because of python2 => 3 transition most likely and can be fixed by executing the following command:

sudo vi +':107s/\(.* =\).*/\1 response[0]/' +':wq' /usr/local/lib/python3.5/dist-packages/yubico/yubikey_4_usb_hid.py

Explained:

In line 107 of the file

/usr/local/lib/python3.5/dist-packages/yubico/yubikey_4_usb_hid.py

the ord() coversion of the response:

r_len = ord(response[0])

needs to be replaced by:

r_len = response[0]

CREDITS

I hope that this might be somewhat of help or at least be inspiring for own ideas. You're alway welcome to leave me a message for reviews or feature requests as well as bug reports: <mail@leonpelzer.de>

•   Python3 developers for IMHO one of the best programming languages

•   stackoverflow.com for hosting endless threads of troubleshooting

•   Pyperclip for the excellent Windows & OSX clipboard code

•   Conrad Parker for xsel as linux copy/paste backend

•   Yubico (cheap & solid HW-Security-Modules) & python-yubico developers

•   GNU Privacy Guard (basic kryptography) & python-gnupg developers

•   SonicLux for testing and telling me that a final version must not be 0.3.3 :D

SEE ALSO
python3(1), gpg2(1), gpgsm(1), openssl(1), ssh(1), yaml(1)

AUTHOR
Leon Pelzer

COPYRIGHT
2018, Leon Pelzer