629a27966a86827ec47dc82c7a4c1f988189dba2
[packages/opensc.git] / 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
This page took 0.083844 seconds and 2 git commands to generate.