README

== python-yubico
Python package for talking to YubiKeys.

Copyright (c) Yubico AB
Licensed under the BSD 2-clause license.
See the file COPYING for full licence statement.

=== Introduction
The YubiKey is a hardware token for authentication. The main
mode of the YubiKey is entering a one time password (or a strong
static password) by acting as a USB HID device, but there are
things one can do with bi-directional communication.

1) Configuration. The yubikey_config class should be a feature-
   wise complete implementation of everything that can be
   configured on YubiKeys version 1.3 to 2.2 (besides deprecated
   functions in YubiKey 1.x).
   See examples/configure_nist_test_key for an example.

2) Challenge-response. YubiKey 2.2 supports HMAC-SHA1 or Yubico
   challenge-response operations.
   See examples/nist_challenge_response for an example.

===  Example
Here is a trivial usage example :

[source, python]
----
#!/usr/bin/env python
""" Get version of connected YubiKey. """

import sys
import yubico

try:
    yubikey = yubico.find_yubikey(debug=False)
    print "Version : %s " % yubikey.version()
except yubico.yubico_exception.YubicoError as e:
    print "ERROR: %s" % e.reason
    sys.exit(1)
----

=== Installation
python-yubico is installable via pip:

  $ pip install yubico-python

Or, directly from the source package in the standard-python way:

  $ cd python-yubico-$ver
  $ python setup.py install

This requires the python-setuptools (well, the package is called
that in Debian/Ubuntu). You will also need the Python USB package
from http://pyusb.berlios.de/ - package called python-usb in
Debian/Ubuntu. Note that while both the 0.4 branch and the 1.0
branch are supported, the older 0.4 branch doesn't support 
re-attaching the kernel device driver on close, which will leave
the YubiKey in a state where it is unable to output OTPs until it
has been unplugged and plugged back in again.

If you use a recent Ubuntu release, you should be able to install
python-yubico with these commands :

  $ sudo add-apt-repository ppa:yubico/stable
  $ sudo apt-get update
  $ sudo apt-get install python-yubico

The Launchpad PPA key generated for our packages is 32CBA1A9.

If you use Windows, you will require a PyUSB backend. Python-yubico
has been tested with http://libusbx.org/ and confirmed working, 
without the need for replacing the device driver.