opensc-initramfs-README

   1 openct with cryptsetup and luks in Debian
   2 -----------------------------------------
   3
   4 This is a overview on how you can make use of cryptsetup with your smartcard
   5 device supported by openct. Please make sure that your smartcard reader or token
   6 is supposed to be operated with openct and not with opensc or pcscd. You can get
   7 some information about the supported hardware by openct at the following
   8 homepage:
   9
  10         <http://www.opensc-project.org/openct/>
  11
  12 This example is based on the ability of openct to store arbitrary data objects
  13 on the smartcard. Note that you therefore have to use openct in version 0.6.12
  14 or newer, any versions before 0.6.12 do not properly support data objects.
  15
  16 Although this use case was done with the Aladdin eToken PRO 32k, an USB crypto
  17 token, this is a generic approach which works the same way with all supported
  18 smartcard devices by openct.
  19
  20 First of all, you should plug in your crypto token into USB or whatever
  21 interface it uses and initalize the reader with the following command (as root):
  22
  23         # openct-control init
  24
  25 To check if your reader has been detected, you can run:
  26
  27         # openct-tool list
  28
  29 This should give you a similar result to this:
  30
  31         0 Aladdin eToken PRO
  32
  33 If you do not see any reader listed, you have a problem and should read again
  34 about the supported hardware on <http://www.opensc-project.org/openct/> and make
  35 sure you have the required support (e.g. USB) compiled into your kernel needed
  36 to connect to your token. If you use a precompiled kernel from Debian,
  37 everything is already built kernelwise and you probably only need to load the
  38 module.
  39
  40 In case you want to erase your previously used smartcard, you can do that by
  41 executing the following command:
  42
  43         # pkcs15-init --erase-card
  44
  45 To setup the smartcard, you need to do the following:
  46
  47         # pkcs15-init --create-pkcs15
  48
  49 Caution: You are beeing asked about the 'Security Officer PIN' and the 'User
  50 unblocking PIN'. Although both of these pins are optional and can be left empty,
  51 you should never do this: In case the personal user pin is typed wrong for a
  52 given number (mostly three times), the smartcard is locked and can only be
  53 unlocked with the user unblocking pin. If you even mistype the user unblocking
  54 pin for a given number (mostly three times), the smartcard is locked and can
  55 only be unlocked with the security officer pin, which is the most superior pin
  56 in this hierarchy. With an unset (empty) security officer pin or user unblocking
  57 pin, depending on the smartcard, an attacker can have unlimited tries to crack
  58 your personal user pin, or, an attacker can simply make the smarcard unusable as
  59 it cannot be unlocked anymore at all.
  60
  61 To create a new identity on the smartcard, do the following:
  62
  63         # pkcs15-init --store-pin --auth-id 01 --label "Daniel Baumann"
  64
  65 If you have already one or more identities, you certainly want to bump the
  66 auth-id here, and normally, the label used to describe the identify is the
  67 persons first and last name.
  68
  69 As we want to use the smartcard with luks, we first need to get some random
  70 data:
  71
  72         # dd if=/dev/random of=data.txt bs=1 count=32
  73
  74 And we store that random data as a data object to the private section of the
  75 smartcard with:
  76
  77         # pkcs15-init --store-data data.txt --auth-id 01
  78
  79 As of the time of writing, openct version 0.6.12 is available and does not
  80 support labeling different data objects. Once this gets fixed in openct
  81 upstream, you can store multiple data objects to the smartcard (create them by
  82 appending '--label foo' to the above command and replace foo with the label you
  83 want to use).
  84
  85 Then, read the random data from the smartcard in order...
  86
  87         # pkcs15-tool --read-data-object pkcs15-init -o /proc/self/fd/3 3>&1 1>/dev/null 2>&1
  88         # pkcs15-tool --read-data-object pkcs15-init -o key.txt 1>/dev/null 2>&1
  89
  90 ...to import that output to luks as a valid key (assumed that /dev/sda5 is your
  91 encrypted partition):
  92
  93         # cryptsetup luksAddKey /dev/sda5 key.txt
  94
  95 To tell cryptsetup to let you authenticate with the openct backend, you need to
  96 pass the respective decrypt script to it as a parameter in /etc/crypttab
  97 (assumed that /dev/sda5 is your encrypted partition):
  98
  99         sda5_crypt /dev/sda5 none luks,keyscript=/lib/cryptsetup/scripts/decrypt_openct
 100
 101 At the moment all data objects have the same label 'pkcs15-init'. Once openct
 102 supports labeling data objects, you can pass the respective label to openct with
 103 the key parameter in /etc/crypttab like this:
 104
 105         sda5_crypt /dev/sda5 none luks,keyscript=/lib/cryptsetup/scripts/decrypt_openct,key=foo
 106
 107 For the time beeing, 'pkcs15-init' is passed to openct when no key is specified.
 108
 109 Don't forget to backup key.txt to a save place and remove the temporary files
 110 afterwards:
 111
 112         # shred -uz key.txt data.txt
 113
 114 Caution: cryptsetup as of version 1.0.5-1 does not support fallback to passphrase
 115 if smartcard authentification fails (bee it three times wrong pin or not
 116 compatible/not detected smartcard reader). That means, that for testing
 117 purposes, it is recommended to keep an initrd image in /boot available which
 118 does *not* use openct or opensc for authentification, so that you can change
 119 your bootloader configuration on the fly if something does not work out as
 120 expected. Therefore, copy your current initrd (the .bak backups from
 121 initramfs-tools can maybe get overwritten by update-initramfs during the setup
 122 of openct, so it is better to be on the save side):
 123
 124         # cp /boot/initrd.img-`uname -r` /boot/initrd.img-`uname -r`.temp
 125
 126 If you have completed all the steps upto now, you can update your initramfs
 127 image with:
 128
 129         # update-initramfs -u -k `uname -r`
 130
 131 and reboot your machine.
 132
 133  -- Daniel Baumann <baumann@swiss-it.ch>  Wed, 22 Aug 2007 10:36:00 +0200