hmac-otp/libcrypt/README

What is this thing?
-------------------

This device is a hash-based-one-time-password (=HOTP, RFC 4226) generator. You
can use them to make an existing authentication more secure or as a single
authentication barrier to enter a system (although I wouldn't recoment that).
You can easily do both on linux machines using the oath toolkit 
(http://www.nongnu.org/oath-toolkit/).

How does it work?
-----------------

The device is an USB-Stick, which opearates as a virtual keyboard. A login
sequence usually happens like this:

    1. When asked for the OTP, plug in the device and wait a few seconds
    2. The device should generate a few keystrokes - this is the token
    3. Confirm the login by pressing the button on the device this will 
       generate an ENTER-keystroke and the internal counter is icremented
       by one.
    4. Pressing the button again resets the device, and the sequence
       repeats. Otherwise just unplug it.

How to install the firmware?
----------------------------

You will need the avr-gcc toolchain (avr-gcc, avr-binutils and the avrlibc).
Go to the source tree (the same directory where this file should be). Now edit
the Makefile. If you don't know what you're doing simply edit the "SECRET"
define: 
    
    SECRET = -DSECLEN=6 -DSECRET="{0xC0, 0xFF, 0xEE, 0xDE, 0xCA, 0xDE}" 

It is recomended to take a secret of length 20 (longer secrets are supported but
do not provide additional security). This is basically a sha1 digest. I usually
do the following to generate secrets:

    >head /dev/urandom | sha1sum
    11d64fc6fcff5f198976b86cc590fb58a04dc422  -

The resulting define would be:

    SECRET = -DSECLEN=20 -DSECRET="{0x11, 0xd6, 0x4f, 0xc6, 0xfc, 0xff, ...}" 

Once you're done simply type make. If the compilation runs well, you will end 
up with some .hex files:
    - The main file: hotp.hex (this goes to the flash)
    - The eeprom init: eeprom.hex (this goes to the internal eeprom)

You can upload them by typing "make install". 
Now configure the server side: Provide the secret you just used, the initial
counter value is 0 (Remember to keep a working terminal somewhere in case you 
lock yourself out). After doing this try to login, if it works you should 
remove the secret from the makefile and also prevent the microcontroller from
beeing read. Do this by typing "make lock"

Security considerations:
------------------------

If you're interested in HOTP security in general, pleas read the corresponding
sections in the RFC 4226. This section deals with the security of the device
hardware.

The device was designed in order to provide additional security, not as the
only protection from attacking/entering your system. If your entire 
authentication is based on this device you should consider the following: 

Anyone who obtains a one time passwordt(=token) from the device, will be able
to authenticate as you until the system and the token-generator get synchronized 
(i.e. your next legitimate login)!

The ATtiny85 contains two Lock bits which can be programmed (=set to 0) in order
to protect the program and EEPROM memory. While the program contains the shared
secret, the EEPROM contains the counter used to compute the. Although the shared 
secret is a little more critical, nobody should know either one of them. You 
should therefore enable the two lock bits. 

If you lose the token-generator it might be hard to get into the system. You
could ask the super user, to look up the counter and secret or disable the 
HOTP login method. If you lost your super users token-generator and you have
physical access to the device you can use a live-cd to rescue your system. 
There are several tutorials on the web that describe how to do that. And if
you don't have physical access or can't ask your super user I can only recomend
not to loose the token-generator.