pwclip
""""""

What pwclip is
==============

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 basically has two operating modes. One 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. For that function Windows is supported (see "Install" section).

The second operating mode does currently only work (as so far tested) on Linux
due to lack of cmdline handling of gpg4win (which i am not sure about and will
go into as soon as i find the time and motivation for that). It can be used to
create a ~/.pwdcrypt file which is gpg encrypted text using either the value of
GPGKEYS as gpg recipients if found in environment otherwise every key within
the users keyring will be used. For password-list managing there is a simple
"import" function. On startup it lookes for a ~/.pwd.yaml file and if found
merged with the already known passwords from the ~/.passcrypt if there is one.
All entrys in ~/.passcrypt will be overridden by the entrys from the
~/.pwd.yaml file. As soon as it has been merged the ~/.pwd.yaml file will be
deleted. See "YAML-Format" section for details.

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's used. The utility also
supports the input of any integer which is then used as timer. Otherwise the
environment is searched for PWCLIPTIME and uses the value of that environment
variable as timer. The timer is used as time in which the received password
stays in the paste buffer bevore its replaced by the previously copied value.
As you may see there is an optional commet which is used as text notification
displayed on the screen if set. Therefor python3's gi notify2 is used which is
another reason for discontinuing python2 support.

I highly encourage you to bind pwclip to a shortcut within your X-Environment
to have access to your stored passwords from within any program. For example
i like binding it to `Super-Middle-Mouse-Button` for the pwclip default mode
and `Strg-Shift-Middle-Mouse-Button` for the yubico mode. 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".


Last but not least i want to point something out: I've been trying my best
to keep the passwords secure from unwanted access BUT there is !NO GUARANTEE!
that the passwords handled with during runtime are safe from other users
access, especially root access on linux systems (help on that is very welcome).
Please be aware of that.


YAML-Format
===========

\-\-\-

realsystemuser:
    \- somename:
        \- Som3(rypt!cPass

        \- Some optional info to display as popup notification

    \- othername:
        \- Som3other(rypt!cPass



Installation
============

pwclip requires the "xsel" package on Debian-Like Systems to have access to
copy/paste buffers. On Windows Systems the libusb package must be integrated
to python3 as "USB-Backend". Here should be all infos needed for that:

* https://wiki.ubuntuusers.de/xsel/
* https://sourceforge.net/projects/libusb/
* http://libusb.info/

If you are on a Debian-Like systems, presuming you have my apt repository
deb.janeiskla.de/ubuntu in your sources list, install like:

$ apt-get install pwclip

Installing via pip3
--------------------

You can install this package from the Python Package Index (pyPI) by running:

* ``pip3 install pwclip``

and installing the dependencies (not managed by pip) manually.

Installing from a source distribution archive
---------------------------------------------
To install this package from a source distribution archive, do the following:

1. Extract all the files in the distribution archive to some directory on your
   system.

2. In that directory, run: ``python setup.py install``


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
--------
``pwclip``

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:

``pwclip -l``

or

``pwclip -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:

``pwclip -A -l $PATTERN``

To show even passwords in clear text (strongly unrecommanded for obvious
reasons) you may use:

``pwclip -l -s``

Most of the above may be combined.

Yubikey-Mode
------------
``pwclip -y``

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:

``pwclip -y $YKSERIAL``

Both-Modes
----------

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

``pwclip 5``

The timer option can only be privided last on cmdline.


Troubleshooting
===============

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 easily (having root privileges) by executing the following commands:
``sudo su -`` # only needed if current user isn't root already
``ykfile=/usr/local/lib/python3.5/dist-packages/yubico/yubikey_4_usb_hid.py``
``sudo vi +':107s/\(.* =\).*/\1 response[0]/' +':wq' $ykfile``
Explained in short the line
`r_len = ord(response[0])`
is replaced by
`r_len = response[0]`


Credits
=======

 * Python3 developers & the whole community (farmost those @stackoverflow.com)
 * Pyperclip for they excellent Windows & OSX clipboard code
 * Yubico (cheap & solid HW-Security-Modules) & python-yubico developers
 * GNU Privacy Guard (basic kryptography) & python-gnupg developers
 * SonicLux for telling me that a final version cannot and must not be 0.3.3 :D

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 requests, review or
feature/bug requests: <d0n@janeiskla.de>


Changelog
=========

0.4.31 (current)
----------------

Released: 2017-08-25

  * hotfix release for gui calls

  * readded work revoked unintensionally

  * fixed yubico mode and ykclip gui


0.4.30
------

Released: 2017-08-25

  * made reading configs somewhat more modular

  * made gui function accepting option for (pw/yk)mode switching

  * made yubikey challenge-response mode behave correctly

  * changed names of binaries to pwcli(cmdline), pwclip(gui), ykclip(gui)


0.4.29
------

Released: 2017-08-25

  * removed empty password check and info

  * added pwclip-gui to "provides" section in __pkginfo__.py

  * hotfix release (fixing password-prompter)


0.4.28
------

Released: 2017-08-24

  * fixed password-search function on cmdline

  * (still) preparing final version :D


0.4.27
------

Released: 2017-08-23

  * [W] hotfix for clipboard paste function to return objects correctly

  * implemented -S to set the slot number of the yubikey used which is
    only relevant for the challenge-response functionality (-y)

  * added a "Troubleshooting" section to README on fixing yubico-usb-hid-bug

  * (still) preparing final version


0.4.26
------

Released: 2017-08-22

  * changed entry-points to match reverted names - trying to find correct
    exec mode for windows

  * cleanup of build environment - preparing final version



Documentation
=============

http://packages.python.org/pwclip/
