busukajw / python-pyhsm Goto Github PK

PyHSM - Python YubiHSM Project
==============================

Introduction
------------

PyHSM is a Python package to talk to a YubiHSM.  The YubiHSM is
Yubico's take on the Hardware Security Module (HSM), designed for
protecting secrets on authentication servers, including cryptographic
keys and passwords, at unmatched simplicity and low cost.

License
-------

The project is licensed under the BSD license, see the file COPYING
for exact wording.

Description
-----------

PyHSM aims to be a reference implementation implementing all the
functions available in the YubiHSM. The base version number of pyhsm
will match the supported hardware version of the YubiHSM: PyHSM
releases 0.9.8, 0.9.8a, 0.9.8b are all intended to be used with
hardware version 0.9.8.

PyHSM also includes the regression test suite for the YubiHSM.

In general, see the files in utils/, examples/ yhsm-val/, and
yubikey-ksm/ to get an idea of how to use this code.

In addition to the YubiHSM communication library, PyHSM also contains
some applications utilizing the YubiHSM:

* yhsm-val: a simple validation server supporting validation of YubiKey
  OTPs, OATH codes and password hashes.

* yubikey-ksm: ykval YubiKey OTP decryption backend using the YubiHSM.

Some smaller scripts are in the utils/ directory:

* yhsm-linux-add-entropy: Feed Linux kernel with random entropy from
  the TRNG on the YubiHSM.

* yhsm-keystore-unlock: Unlock the key storage in the YubiHSM with your HSM
  password. Use with incorrect password to lock it again.

* yhsm-daemon: Talk to the YubiHSM directly over TCP.

And some more in examples/:

* yhsm-sysinfo.py: Print basic system information about the connected YubiHSM.

* yhsm-monitor-exit.py: Get a YubiHSM *in debug mode* to enter
  configuration mode again, without having to press the little button
  while inserting it into the USB port.

* yhsm-password-auth.py: Example of how to turn passwords (or hashes
  of passwords if you like PBKDF2) into AEADs that can be used to
  verify the password later on.

Installation
------------

PyHSM is known to work with Python 2.6 and 2.7, and is primarily
tested using Debian/Ubuntu, but is of course meant to work on as many
platforms as possible.

NOTE: If you want to use any of the daemons (yhsm-validation-server,
yhsm-yubikey-ksm) you will want to use Python 2.7 or later.
SocketServer.py lacks critical timeout handling in Python 2.6.

The pyserial package is needed, see:
http://pyserial.sourceforge.net/

  Debian: apt-get install python-serial

For database support SQLAlchemy is needed, see:
http://www.sqlalchemy.org/

  Debian: apt-get install python-sqlalchemy

To run the test suite, you need pycrypto, see:
http://www.pycrypto.org/

  Debian: apt-get install python-crypto

Please note that the pycrypto version has to be 2.1 or higher -- it is
known that RHEL6 has a lower version.

PyHSM is installed like other Python packages:

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

This requires the Debian/Ubuntu python-setuptools package.