pyhsm 1.0.4h

Python code for talking to a YubiHSM

This is the 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.

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

Copyright (c) 2011 Yubico AB See the file COPYING for licence statement.

Introduction

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 (e.g. 0.9.8, 0.9.8a, 0.9.8b all intended to be used with hardware version 0.9.8).

pyhsm also includes the regression test suite for the YubiHSM.

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.

and some smaller scripts in the utils/ and examples/ 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-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.

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.

It is primarily tested using Debian/Ubuntu, but is of course meant to work on as many platforms as possible.

pyhsm is installable in the standard-python way :

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

This requires the python-setuptools (well, the package is called that in Debian/Ubuntu).

You will also need the pyserial package (python-serial in Debian/Ubuntu) from http://pyserial.sourceforge.net/ and, to run the test suite, pycrypto from http://www.pycrypto.org/ (python-crypto in Debian/Ubuntu).

I use Ubuntu, so I created a PPA (Personal Package Archive) for easy installation (and removal) on Ubuntu systems.

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

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

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

If you want to work on Debian/Ubuntu packaging, or just build packages directly from version controlled sources, you can find it maintained in a git repository.

$ git clone git://github.com/Yubico/python-pyhsm-dpkg.git $ cd python-pyhsm-dpkg $ git-buildpackage

See https://github.com/Yubico/python-pyhsm-dpkg for more information.

---

Comments, feedback and patches welcome!

Fredrik Thulin <[e-mail]> 2011-03-28