[gssapi-openssh.git] / openssh / 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
3c0ef626	1	How to use smartcards with OpenSSH?
3c0ef626	2
700318f3	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.
3c0ef626	6
700318f3	7	WARNING: Smartcard support is still in development.
700318f3	8	Keyfile formats, etc are still subject to change.
3c0ef626	9
700318f3	10	To enable sectok support:
3c0ef626	11
700318f3	12	(1) install sectok:
3c0ef626	13
700318f3	14	Sources and instructions are available from
3c0ef626	15	http://www.citi.umich.edu/projects/smartcard/sectok.html
3c0ef626	16
700318f3	17	(2) enable sectok support in OpenSSH:
3c0ef626	18
700318f3	19	$ ./configure --with-sectok[=/path/to/libsectok] [options]
3c0ef626	20
	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
700318f3	30	Please don't use your production RSA keys, since
3c0ef626	31	with the current version of sectok/ssh-keygen
700318f3	32	the private key file is still readable.
3c0ef626	33
700318f3	34	$ ssh-keygen -f /path/to/rsakey -U <readernum, eg. 0>
3c0ef626	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
700318f3	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:
3c0ef626	77
700318f3	78	$ ssh -I <readernum, eg. 0> otherhost
3c0ef626	79
700318f3	80	(2) or tell the agent (don't forget to restart) to use the smartcard:
3c0ef626	81
700318f3	82	$ ssh-add -s <readernum, eg. 0>
3c0ef626	83
3c0ef626	84	-markus,
700318f3	85	Sat Apr 13 13:48:10 EEST 2002