[openssh.git] / README.smartcard

How to use smartcards with OpenSSH?

OpenSSH contains experimental support for authentication using Cyberflex
smartcards and TODOS card readers, in addition to the cards with PKCS#15
structure supported by OpenSC.

WARNING: Smartcard support is still in development.
Keyfile formats, etc are still subject to change.

To enable sectok support:

(1) install sectok:

	Sources and instructions are available from
	http://www.citi.umich.edu/projects/smartcard/sectok.html

(2) enable sectok support in OpenSSH:

	$ ./configure --with-sectok[=/path/to/libsectok] [options]

(3) load the Java Cardlet to the Cyberflex card:

	$ sectok
	sectok> login -d
	sectok> jload /usr/libdata/ssh/Ssh.bin
	sectok> quit

(4) load a RSA key to the card:

	Please don't use your production RSA keys, since
	with the current version of sectok/ssh-keygen
	the private key file is still readable.

	$ ssh-keygen -f /path/to/rsakey -U <readernum, eg. 0>

	In spite of the name, this does not generate a key.
	It just loads an already existing key on to the card.

(5) optional:

	Change the card password so that only you can
	read the private key:

	$ sectok
	sectok> login -d
	sectok> setpass
	sectok> quit

	This prevents reading the key but not use of the
	key by the card applet.

	Do not forget the passphrase.  There is no way to
	recover if you do.

	IMPORTANT WARNING: If you attempt to login with the
	wrong passphrase three times in a row, you will
	destroy your card.

To enable OpenSC support:

(1) install OpenSC:

	Sources and instructions are available from
	http://www.opensc.org/

(2) enable OpenSC support in OpenSSH:

	$ ./configure --with-opensc[=/path/to/opensc] [options]

(3) load a RSA key to the card:

	Not supported yet.

Common smartcard options:

(1) tell the ssh client to use the card reader:

	$ ssh -I <readernum, eg. 0> otherhost

(2) or tell the agent (don't forget to restart) to use the smartcard:

	$ ssh-add -s <readernum, eg. 0>

-markus,
Sat Apr 13 13:48:10 EEST 2002
Commit	Line	Data
93816ec8	1	How to use smartcards with OpenSSH?
93816ec8	2
49ef62db	3	OpenSSH contains experimental support for authentication using Cyberflex
	4	smartcards and TODOS card readers, in addition to the cards with PKCS#15
	5	structure supported by OpenSC.
6877d8b9	6
49ef62db	7	WARNING: Smartcard support is still in development.
49ef62db	8	Keyfile formats, etc are still subject to change.
6877d8b9	9
49ef62db	10	To enable sectok support:
93816ec8	11
49ef62db	12	(1) install sectok:
93816ec8	13
49ef62db	14	Sources and instructions are available from
3b841aaa	15	http://www.citi.umich.edu/projects/smartcard/sectok.html
93816ec8	16
49ef62db	17	(2) enable sectok support in OpenSSH:
93816ec8	18
295c8801	19	$ ./configure --with-sectok[=/path/to/libsectok] [options]
3b841aaa	20
93816ec8	21	(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
49ef62db	30	Please don't use your production RSA keys, since
93816ec8	31	with the current version of sectok/ssh-keygen
49ef62db	32	the private key file is still readable.
93816ec8	33
49ef62db	34	$ ssh-keygen -f /path/to/rsakey -U <readernum, eg. 0>
93816ec8	35
	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
49ef62db	59	To enable OpenSC support:
	60
	61	(1) install OpenSC:
	62
	63	Sources and instructions are available from
	64	http://www.opensc.org/
	65
	66	(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
	74	Common smartcard options:
	75
	76	(1) tell the ssh client to use the card reader:
93816ec8	77
49ef62db	78	$ ssh -I <readernum, eg. 0> otherhost
93816ec8	79
49ef62db	80	(2) or tell the agent (don't forget to restart) to use the smartcard:
93816ec8	81
49ef62db	82	$ ssh-add -s <readernum, eg. 0>
93816ec8	83
93816ec8	84	-markus,
49ef62db	85	Sat Apr 13 13:48:10 EEST 2002