== Author & Version ==YubiServe has been written by Alessio Periloso <mail at periloso.it> Version 1.0: 21/05/2010 Version 2.0: 19/11/2010 Version 2.9: 13/12/2010 Version 3.0: 14/12/2010 Version 3.1: 24/03/2011
Fixed issue #3, #4, #5, #6
== Description ==This simple service allows to authenticate Yubikeys and OATH Tokens using only a small sqlite database (the mysql support is optional!) The code has been released under GNU license (license into LICENSE file)
The project is divided into two parts:
The validation server (yubiserve.py)
== Installation ==Installation is pretty simple, you just have to install few python packages:
Under Debian, you can run: apt-get install python python-crypto python-openssl
Under Mageia, you will need to use: urpmi python-pycrypto python-OpenSSL
If you want to add the sqlite support, you should run: apt-get install python-sqlite sqlite3 is also supported, which is included with python in RHEL6.
Or, if you want to add the mysql support, you should run: apt-get install python-mysqldb If you chosen the mysql support, you must create a database and create the tables. The mysql dump is at src/dump.mysql.
Then, you have to generate the certificate for ssl validation, so if you don't already have a certificate you have to issue the following command to self-sign one: openssl req -new -x509 -keyout yubiserve.pem -out yubiserve.pem -days 365 -nodes
A good idea would be taking a look at yubiserve.cfg, to configure the validation server settings.
After installing the needed packages, you just need to extract the files to a directory, add the keys and launch the server (or, if you prefer you can launch the server before adding the keys, it doesn't matter).
== The database management tool ==The database management tool helps you to manage keys in the database. For detailed help, run the database management tool with ./dbconf.py
The tool allows you to add, delete, disable and enable keys/tokens. You can also add and remove API keys, to check the server signature in server responses. Everything is managed through nicknames, to make keys easy to remember who belong to.
For example, to add a new yubikey, write: ./dbconf.py -ya alessio vvkdtkjureru 980a8608b307 f1dc9c6585d600d06f9aae1abea2969e
In this example, 'alessio' is the key nickname, 'vvkdtkjureru' is the key public identity (the one you can see at the beginning of your OTPs), '980a8608b307' is the private identity of the OTP (you can read it when you program your key), and the last parameter is the AES Key.
To add a new OATH/HOTP: ./dbconf.py -ha alessio 4rvn24642402 f03ddacdfebb6396f60d7045f41de68f5c5e1c3f
In this other example, 'alessio' is still the nickname, '4rvn24642402' is the public identity of the token (it could be also 1, 2, 'alessio' or whatever you want; the Yubico implementation is 12 characters long)
To add a new API key: ./dbconf.py -aa alessio
When you add a new API key, the configuration tool will return both the api key (ex. 'UkxFMnNFNTV4clRYUExSOWlONzQ=') and the API key id meant to be used later in your queries to the Yubiserve validation server.
== The Yubiserve Validation Server ==Understanding how to use the Yubiserve web application is pretty simple. You just have to run it (./yubiserve.py) and send your queries through HTTP GET connections. The default listening port is 8000, the default listening ip is 0.0.0.0 (so you can connect to it from other machines). If you need it to answer only from local machine, you can change the ip to 127.0.0.1. The ssl port is by default the next one, so if the http validation server answers on port 8000, the ssl will answer on port 8001. Anyway, everything is easily customizable modifying the yubiserve.py file and changing the variables "yubiservePORT" for the HTTP port, "yubiserveSSLPORT" for the SSL port, "yubiserveHOST" for the listening ip. When you connect to the server (ex. http://192.168.0.1:8000/), it will answer with a simple page, asking you Yubico Yubikeys OTPs or OATH/HOTP tokens. The Yubico Yubikey needs only one parameter: the OTP. The OATH/HOTP tokens needs two parameters: the OTP itself (6 or 8 digits) and the Token Identifier. The token identifier can be any character string you prefer, or, according to the standard OATH implementation, the preceding string to the OTP. The Yubico implementation follows this standard. The Yubiserve Validation Server, according to the standard, will try to find the Token Identifier preceding the OTP. If the string is found, the OTP will be verified according to that string; in case of LCD tokens, the string is not automatically added, so you will need to insert your ID in the second box to allow the Validation Server to find your own identity.
== Querying the Yubiserve Validation Server ==Querying the Yubiserve Validation Server is pretty simple.
For Yubico Yubikeys, you will need to send a HTTP GET connection to:
http://
otp=vvnjbbkvjbcnhiretjvjfebbrdgrjjchdhtbderrdbhj status=OK t=2010-11-20T23:54:35 h=
As you can see, the 'h' parameter is not set, and this is because we didn't use
the signature through API Key. To use it, just add the 'id=
otp=vvnjbbkvjbcnhiretjvjfebbrdgrjjchdhtbderrdbhj status=OK t=2010-11-21T00:00:03 h=6lrhQPKo1I/RQA1KPnjpuiOvVMc=
To check the server signature, check the source code (you will have to do the exact same procedure to generate it and then just check if they are equal), or rely on the Yubico documentation on Validation Servers.
For OATH/HOTP keys, the query can be simplified or not.
If your token supports the 'Token Identifier', like Yubico Yubikeys, you can just
send one parameter, the generated string, and the Yubiserve Validation Server will
take care of looking for your key informations in the database.
If your token instead only generates the 6-8 digits, you will have to explicit
your publicID through another parameter.
So, you will have to query, via HTTP GET, the following address:
http://
otp=80l944311056173483 status=OK t=2010-11-21T00:04:59 h=
The 'h' parameter is not set, because we didn't specified the API Key id. To use the server signature, we will need to add the 'id' parameter, like in the following query: ex.: http://192.168.1.2:8000/wsapi/2.0/oathverify?otp=80l944311056173483&id=1 ex.: http://192.168.0.1:8000/wsapi/2.0/oathverify?otp=173483&publicid=80l944311056&id=1
And this would be the the response:
otp=80l944311056173483 status=OK t=2010-11-21T00:10:56 h=vYoG9Av8uG6OqVkmMFuANi4fyWw=
== Basic monitoring of the Yubiserve Validation Server ==The yubiserve tool allows you to set up basic monitoring by making an http request using the URI /healthcheck.
This check will confirm if the yubserve tool is capable of connecting to it's database and capable of performing queries. It also counts the number of enabled tokens/keys, and will produce a warning if no keys are enabled.
Options are: /healthcheck?service=all /healthcheck?service=oathtoken /healthcheck?service=yubikeys
Example: curl -s http://localhost:8000/healthcheck?service=yubikeys
Output format is: OK: (no message) WARN: multi-line warning message CRITICAL: multi-line warning message
HTTP result codes: 200 - OK / WARN 404 - Something bad, the health check did not run 500 - The healthcheck got an un-handled exception during operation. An error will be printed. 503 - The healthcheck found no enabled keys.
The recommended way to perform this is to use Nagios or other monitoring tool to poll the yubiserve health check and check the returned string starts with "OK:"
== Final thoughts ==That's all. Pretty simple, huh? Of course you can add new keys while the server is already running, without needing it to restart, and of course multiple queries a time are allowed, that's why the server is multithreaded.