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