#summary Introduction to low-level Yubikey C library
#labels Featured,Phase-Deploy

= Introduction =

This package make up the low-level C software development kit for the
Yubico authentication device, the Yubikey.  In particular:

* AUTHORS, COPYING, NEWS, README: meta-information about the project.

* yubikey.h, yubikey.c: Implementation of the library.

* selftest.c: Self tests of the library.

* ykdebug.c: Command line tool to print debug information about a token.

* modhex.c: Command-line tool for modhex encoding/decoding.

* simple.mk: Simple makefile to build the above parts.

* configure.ac, Makefile.am: Autoconf/Automake files.

= Building =

The simple way to build the package is by running 'make -f simple.mk
check'.  It will build each component, and also test them.  See below
for sample session.

{{{
$ make -f simple.mk clean
rm -f pof-test modhex tool *~ *.o
$ make -f simple.mk check
cc -I. -Wall   -c -o pof.o pof.c
cc -I. -Wall    pof-test.c pof.o   -o pof-test
cc -I. -Wall    modhex.c pof.o   -o modhex
cc -I. -Wall    tool.c pof.o   -o tool
./selftest
...
All tests successful
}}}

To build using the Autoconf, automake and libtool infrastructure,
which is recommend for more advanced purposes especially
cross-compilation, build it as follows.

{{{
$ autoreconf -fvi
$ ./configure
$ make check
}}}

= Self-tests =

After building the package, a binary "selftest" is created that
performs internal self-tests.  Invoke it as follows.

{{{
./pof-test
modhex-encode("test") = ifhgieif
Modhex-1 success
modhex-decode("ifhgieif") = test
Modhex-2 success
aes-decrypt (data=0123456789abcdef, key=abcdef0123456789)
 => 838a467f34639551755bd32a4a2f15e1
AES-1 success

All tests successful
}}}

= Command-line tools =

Two command line tools, modex and ykdebug, are included.

The "modhex" program converts data between modhex, normal hex, and
binary form.

The "ykdebug" program decrypts and parses one OTP given the OTP and
the AES key corresponding to that Yubikey.

{{{
$ ./modhex test
ifhgieif
$ ./modhex -d ifhgieif
test
$ ./modhex -h b565716f
nghgibhv
$ ./modhex -h -d nghgibhv
b565716f
$ ./ykdebug urtubjtnuihvntcreeeecvbregfjibtn dteffujedcflcindvdbrblehecuitvjkjevvehjd
warning: overlong token, ignoring prefix: dteffuje
Input:
  token: dcflcindvdbrblehecuitvjkjevvehjd
          20 4a 07 b2 f2 1c 1a 36 30 e7 df 89 83 ff 36 82 
  aeskey: urtubjtnuihvntcreeeecvbregfjibtn
          ec de 18 db e7 6f bd 0c 33 33 0f 1c 35 48 71 db 
Output:
          87 92 eb fe 26 cc 13 00 a8 c0 00 10 b4 08 6f 5b 

Struct:
  uid: 87 92 eb fe 26 cc 
  counter: 19 (0x0013)
  timestamp (low): 49320 (0xc0a8)
  timestamp (high): 0 (0x00)
  session use: 16 (0x10)
  random: 2228 (0x8b4)
  crc: 23407 (0x5b6f)

Derived:
  cleaned counter: 19 (0x0013)
  modhex uid: jikdunvudhrr
  triggered by caps lock: no
  crc: F0B8
  crc check: ok
$ ./ykdebug urtubjtnuihvntcreeeecvbregfjibtn dteffujehknhfjbrjnlnldnhcujvddbikngjrtgh
warning: overlong token, ignoring prefix: dteffuje
Input:
  token: hknhfjbrjnlnldnhcujvddbikngjrtgh
          69 b6 48 1c 8b ab a2 b6 0e 8f 22 17 9b 58 cd 56 
  aeskey: urtubjtnuihvntcreeeecvbregfjibtn
          ec de 18 db e7 6f bd 0c 33 33 0f 1c 35 48 71 db 
Output:
          87 92 eb fe 26 cc 13 00 30 c2 00 11 c8 9f 23 c8 

Struct:
  uid: 87 92 eb fe 26 cc 
  counter: 19 (0x0013)
  timestamp (low): 49712 (0xc230)
  timestamp (high): 0 (0x00)
  session use: 17 (0x11)
  random: 40904 (0x9fc8)
  crc: 51235 (0xc823)

Derived:
  cleaned counter: 19 (0x0013)
  modhex uid: jikdunvudhrr
  triggered by caps lock: no
  crc: F0B8
  crc check: ok
$ 
}}}

= Questions? =

Talk to <simon@yubico.com>.