--- /dev/null
+openct with cryptsetup and luks in Debian
+-----------------------------------------
+
+This is a overview on how you can make use of cryptsetup with your smartcard
+device supported by openct. Please make sure that your smartcard reader or token
+is supposed to be operated with openct and not with opensc or pcscd. You can get
+some information about the supported hardware by openct at the following
+homepage:
+
+ <http://www.opensc-project.org/openct/>
+
+This example is based on the ability of openct to store arbitrary data objects
+on the smartcard. Note that you therefore have to use openct in version 0.6.12
+or newer, any versions before 0.6.12 do not properly support data objects.
+
+Although this use case was done with the Aladdin eToken PRO 32k, an USB crypto
+token, this is a generic approach which works the same way with all supported
+smartcard devices by openct.
+
+First of all, you should plug in your crypto token into USB or whatever
+interface it uses and initalize the reader with the following command (as root):
+
+ # openct-control init
+
+To check if your reader has been detected, you can run:
+
+ # openct-tool list
+
+This should give you a similar result to this:
+
+ 0 Aladdin eToken PRO
+
+If you do not see any reader listed, you have a problem and should read again
+about the supported hardware on <http://www.opensc-project.org/openct/> and make
+sure you have the required support (e.g. USB) compiled into your kernel needed
+to connect to your token. If you use a precompiled kernel from Debian,
+everything is already built kernelwise and you probably only need to load the
+module.
+
+In case you want to erase your previously used smartcard, you can do that by
+executing the following command:
+
+ # pkcs15-init --erase-card
+
+To setup the smartcard, you need to do the following:
+
+ # pkcs15-init --create-pkcs15
+
+Caution: You are beeing asked about the 'Security Officer PIN' and the 'User
+unblocking PIN'. Although both of these pins are optional and can be left empty,
+you should never do this: In case the personal user pin is typed wrong for a
+given number (mostly three times), the smartcard is locked and can only be
+unlocked with the user unblocking pin. If you even mistype the user unblocking
+pin for a given number (mostly three times), the smartcard is locked and can
+only be unlocked with the security officer pin, which is the most superior pin
+in this hierarchy. With an unset (empty) security officer pin or user unblocking
+pin, depending on the smartcard, an attacker can have unlimited tries to crack
+your personal user pin, or, an attacker can simply make the smarcard unusable as
+it cannot be unlocked anymore at all.
+
+To create a new identity on the smartcard, do the following:
+
+ # pkcs15-init --store-pin --auth-id 01 --label "Daniel Baumann"
+
+If you have already one or more identities, you certainly want to bump the
+auth-id here, and normally, the label used to describe the identify is the
+persons first and last name.
+
+As we want to use the smartcard with luks, we first need to get some random
+data:
+
+ # dd if=/dev/random of=data.txt bs=1 count=32
+
+And we store that random data as a data object to the private section of the
+smartcard with:
+
+ # pkcs15-init --store-data data.txt --auth-id 01
+
+As of the time of writing, openct version 0.6.12 is available and does not
+support labeling different data objects. Once this gets fixed in openct
+upstream, you can store multiple data objects to the smartcard (create them by
+appending '--label foo' to the above command and replace foo with the label you
+want to use).
+
+Then, read the random data from the smartcard in order...
+
+ # pkcs15-tool --read-data-object pkcs15-init -o /proc/self/fd/3 3>&1 1>/dev/null 2>&1
+ # pkcs15-tool --read-data-object pkcs15-init -o key.txt 1>/dev/null 2>&1
+
+...to import that output to luks as a valid key (assumed that /dev/sda5 is your
+encrypted partition):
+
+ # cryptsetup luksAddKey /dev/sda5 key.txt
+
+To tell cryptsetup to let you authenticate with the openct backend, you need to
+pass the respective decrypt script to it as a parameter in /etc/crypttab
+(assumed that /dev/sda5 is your encrypted partition):
+
+ sda5_crypt /dev/sda5 none luks,keyscript=/lib/cryptsetup/scripts/decrypt_openct
+
+At the moment all data objects have the same label 'pkcs15-init'. Once openct
+supports labeling data objects, you can pass the respective label to openct with
+the key parameter in /etc/crypttab like this:
+
+ sda5_crypt /dev/sda5 none luks,keyscript=/lib/cryptsetup/scripts/decrypt_openct,key=foo
+
+For the time beeing, 'pkcs15-init' is passed to openct when no key is specified.
+
+Don't forget to backup key.txt to a save place and remove the temporary files
+afterwards:
+
+ # shred -uz key.txt data.txt
+
+Caution: cryptsetup as of version 1.0.5-1 does not support fallback to passphrase
+if smartcard authentification fails (bee it three times wrong pin or not
+compatible/not detected smartcard reader). That means, that for testing
+purposes, it is recommended to keep an initrd image in /boot available which
+does *not* use openct or opensc for authentification, so that you can change
+your bootloader configuration on the fly if something does not work out as
+expected. Therefore, copy your current initrd (the .bak backups from
+initramfs-tools can maybe get overwritten by update-initramfs during the setup
+of openct, so it is better to be on the save side):
+
+ # cp /boot/initrd.img-`uname -r` /boot/initrd.img-`uname -r`.temp
+
+If you have completed all the steps upto now, you can update your initramfs
+image with:
+
+ # update-initramfs -u -k `uname -r`
+
+and reboot your machine.
+
+ -- Daniel Baumann <baumann@swiss-it.ch> Wed, 22 Aug 2007 10:36:00 +0200
--- /dev/null
+#!/bin/sh
+
+set -e
+
+PREREQ="cryptroot"
+
+prereqs()
+{
+ echo "$PREREQ"
+}
+
+case $1 in
+ prereqs)
+ prereqs
+ exit 0
+ ;;
+esac
+
+. /usr/share/initramfs-tools/hook-functions
+
+# Hooks for loading smartcard reading software into the initramfs
+
+# Check whether cryptroot hook has installed decrypt_opensc script
+if [ ! -x ${DESTDIR}/keyscripts/decrypt_opensc ] ; then
+ exit 0
+fi
+
+# Install cryptroot key files into initramfs
+keys=$(sed 's/^\(.*,\|\)key=//; s/,.*//' ${DESTDIR}/conf/conf.d/cryptroot)
+
+if [ "${keys}" != "none" ]; then
+ if [ -z "${keys}" ]; then
+ echo $0: Missing key files in ${DESTDIR}/conf/conf.d/cryptroot >&2
+ cat ${DESTDIR}/conf/conf.d/cryptroot >&2
+ exit 1
+ fi
+ for key in ${keys} ; do
+ if [ ! -d ${DESTDIR}/$(dirname ${key}) ] ; then
+ mkdir -p ${DESTDIR}/$(dirname ${key})
+ fi
+ cp ${key} ${DESTDIR}/${key}
+ done
+fi
+
+# Install directories needed by smartcard reading daemon, command, and
+# key-script
+for dir in etc/opensc usr/lib/pcsc var/run tmp ; do
+ if [ ! -d ${DESTDIR}/${dir} ] ; then mkdir -p ${DESTDIR}/${dir} ; fi
+done
+
+# Install pcscd daemon, drivers, conf file, and include libgcc as well since
+# pcscd utilizes pthread_cancel
+copy_exec /usr/sbin/pcscd
+cp -r /usr/lib/pcsc ${DESTDIR}/usr/lib
+cp /etc/reader.conf ${DESTDIR}/etc
+
+# Install opensc commands and conf file
+copy_exec /usr/bin/opensc-tool
+copy_exec /usr/bin/pkcs15-crypt
+cp /etc/opensc/opensc.conf ${DESTDIR}/etc/opensc