Python code for talking to a YubiHSM
Project description
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 <fredrik@yubico.com> 2011-03-28
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.