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