blob: 29bec8dc64e90cc972641a69980bb507caec2621 [file] [log] [blame]
Damien Millerd97c2ce2001-09-18 15:06:21 +10001How to use smartcards with OpenSSH?
2
Damien Millerf6195f22002-04-23 22:48:46 +10003OpenSSH contains experimental support for authentication using Cyberflex
4smartcards and TODOS card readers, in addition to the cards with PKCS#15
5structure supported by OpenSC.
Damien Miller8124e1a2001-09-25 10:21:28 +10006
Damien Millerf6195f22002-04-23 22:48:46 +10007WARNING: Smartcard support is still in development.
8Keyfile formats, etc are still subject to change.
Damien Miller8124e1a2001-09-25 10:21:28 +10009
Damien Millerf6195f22002-04-23 22:48:46 +100010To enable sectok support:
Damien Millerd97c2ce2001-09-18 15:06:21 +100011
Damien Millerf6195f22002-04-23 22:48:46 +100012(1) install sectok:
Damien Millerd97c2ce2001-09-18 15:06:21 +100013
Damien Millerf6195f22002-04-23 22:48:46 +100014 Sources and instructions are available from
Damien Miller7a62b772001-09-18 15:44:34 +100015 http://www.citi.umich.edu/projects/smartcard/sectok.html
Damien Millerd97c2ce2001-09-18 15:06:21 +100016
Damien Millerf6195f22002-04-23 22:48:46 +100017(2) enable sectok support in OpenSSH:
Damien Millerd97c2ce2001-09-18 15:06:21 +100018
Ben Lindstroma42694f2002-04-05 16:11:45 +000019 $ ./configure --with-sectok[=/path/to/libsectok] [options]
Damien Miller7a62b772001-09-18 15:44:34 +100020
Damien Millerd97c2ce2001-09-18 15:06:21 +100021(3) load the Java Cardlet to the Cyberflex card:
22
23 $ sectok
24 sectok> login -d
25 sectok> jload /usr/libdata/ssh/Ssh.bin
26 sectok> quit
27
28(4) load a RSA key to the card:
29
Damien Millerf6195f22002-04-23 22:48:46 +100030 Please don't use your production RSA keys, since
Damien Millerd97c2ce2001-09-18 15:06:21 +100031 with the current version of sectok/ssh-keygen
Damien Millerf6195f22002-04-23 22:48:46 +100032 the private key file is still readable.
Damien Millerd97c2ce2001-09-18 15:06:21 +100033
Damien Millerf6195f22002-04-23 22:48:46 +100034 $ ssh-keygen -f /path/to/rsakey -U <readernum, eg. 0>
Damien Millerd97c2ce2001-09-18 15:06:21 +100035
36 In spite of the name, this does not generate a key.
37 It just loads an already existing key on to the card.
38
39(5) optional:
40
41 Change the card password so that only you can
42 read the private key:
43
44 $ sectok
45 sectok> login -d
46 sectok> setpass
47 sectok> quit
48
49 This prevents reading the key but not use of the
50 key by the card applet.
51
52 Do not forget the passphrase. There is no way to
53 recover if you do.
54
55 IMPORTANT WARNING: If you attempt to login with the
56 wrong passphrase three times in a row, you will
57 destroy your card.
58
Damien Millerf6195f22002-04-23 22:48:46 +100059To enable OpenSC support:
Damien Millerd97c2ce2001-09-18 15:06:21 +100060
Damien Millerf6195f22002-04-23 22:48:46 +100061(1) install OpenSC:
Damien Millerd97c2ce2001-09-18 15:06:21 +100062
Damien Millerf6195f22002-04-23 22:48:46 +100063 Sources and instructions are available from
64 http://www.opensc.org/
Damien Millerd97c2ce2001-09-18 15:06:21 +100065
Damien Millerf6195f22002-04-23 22:48:46 +100066(2) enable OpenSC support in OpenSSH:
67
68 $ ./configure --with-opensc[=/path/to/opensc] [options]
69
70(3) load a RSA key to the card:
71
72 Not supported yet.
73
74Common smartcard options:
75
76(1) tell the ssh client to use the card reader:
77
78 $ ssh -I <readernum, eg. 0> otherhost
79
80(2) or tell the agent (don't forget to restart) to use the smartcard:
81
82 $ ssh-add -s <readernum, eg. 0>
Damien Millerd97c2ce2001-09-18 15:06:21 +100083
84-markus,
Damien Millerf6195f22002-04-23 22:48:46 +100085Sat Apr 13 13:48:10 EEST 2002