[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. To enable this you
need to:

Using libsectok:

(1) enable sectok support in OpenSSH:

	$ ./configure --with-sectok

(2) If you have used a previous version of ssh with your card, you
    must remove the old applet and keys.

	$ sectok
	sectok> login -d
	sectok> junload Ssh.bin
	sectok> delete 0012
	sectok> delete sh
	sectok> quit

(3) load the Java Cardlet to the Cyberflex card and set card passphrase:

	$ sectok
	sectok> login -d
	sectok> jload /usr/libdata/ssh/Ssh.bin
	sectok> setpass
	Enter new AUT0 passphrase:
	Re-enter passphrase:
	sectok> quit

	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.

(4) load a RSA key to the card:

	$ ssh-keygen -f /path/to/rsakey -U 1
	(where 1 is the reader number, you can also try 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: If you don't want to use a card passphrase, change the
    acl on the private key file:

	$ sectok
	sectok> login -d
	sectok> acl 0012 world: w
	 world: w
	 AUT0: w inval
	sectok> quit

	If you do this, anyone who has access to your card
	can assume your identity.  This is not recommended.


Using OpenSC:

(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 operations:

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

	$ ssh -I 1 otherhost

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

	$ ssh-add -s 1


-markus,
Tue Jul 17 23:54:51 CEST 2001

$OpenBSD: README.smartcard,v 1.9 2003/11/21 11:57:02 djm Exp $
Commit	Line	Data
93816ec8	1	How to use smartcards with OpenSSH?
93816ec8	2
8a547250	3	OpenSSH contains experimental support for authentication using
aff51935	4	Cyberflex smartcards and TODOS card readers, in addition to the cards
a1864983	5	with PKCS#15 structure supported by OpenSC. To enable this you
8a547250	6	need to:
6877d8b9	7
a1864983	8	Using libsectok:
6877d8b9	9
a1864983	10	(1) enable sectok support in OpenSSH:
	11
	12	$ ./configure --with-sectok
93816ec8	13
8a547250	14	(2) If you have used a previous version of ssh with your card, you
8a547250	15	must remove the old applet and keys.
93816ec8	16
	17	$ sectok
	18	sectok> login -d
8a547250	19	sectok> junload Ssh.bin
	20	sectok> delete 0012
	21	sectok> delete sh
93816ec8	22	sectok> quit
93816ec8	23
8a547250	24	(3) load the Java Cardlet to the Cyberflex card and set card passphrase:
93816ec8	25
	26	$ sectok
	27	sectok> login -d
8a547250	28	sectok> jload /usr/libdata/ssh/Ssh.bin
93816ec8	29	sectok> setpass
aff51935	30	Enter new AUT0 passphrase:
aff51935	31	Re-enter passphrase:
93816ec8	32	sectok> quit
93816ec8	33
93816ec8	34	Do not forget the passphrase. There is no way to
	35	recover if you do.
	36
	37	IMPORTANT WARNING: If you attempt to login with the
	38	wrong passphrase three times in a row, you will
	39	destroy your card.
	40
8a547250	41	(4) load a RSA key to the card:
49ef62db	42
8a547250	43	$ ssh-keygen -f /path/to/rsakey -U 1
8a547250	44	(where 1 is the reader number, you can also try 0)
49ef62db	45
8a547250	46	In spite of the name, this does not generate a key.
8a547250	47	It just loads an already existing key on to the card.
49ef62db	48
a1864983	49	(5) Optional: If you don't want to use a card passphrase, change the
8a547250	50	acl on the private key file:
93816ec8	51
8a547250	52	$ sectok
8a547250	53	sectok> login -d
aff51935	54	sectok> acl 0012 world: w
	55	world: w
	56	AUT0: w inval
8a547250	57	sectok> quit
93816ec8	58
8a547250	59	If you do this, anyone who has access to your card
8a547250	60	can assume your identity. This is not recommended.
93816ec8	61
a1864983	62
	63	Using OpenSC:
	64
	65	(1) install OpenSC:
	66
	67	Sources and instructions are available from
	68	http://www.opensc.org/
	69
	70	(2) enable OpenSC support in OpenSSH:
	71
	72	$ ./configure --with-opensc[=/path/to/opensc] [options]
	73
	74	(3) load a RSA key to the card:
	75
	76	Not supported yet.
	77
	78
	79	Common operations:
	80
	81	(1) tell the ssh client to use the card reader:
	82
	83	$ ssh -I 1 otherhost
	84
	85	(2) or tell the agent (don't forget to restart) to use the smartcard:
	86
	87	$ ssh-add -s 1
	88
	89
93816ec8	90	-markus,
8a547250	91	Tue Jul 17 23:54:51 CEST 2001
8a547250	92
aff51935	93	$OpenBSD: README.smartcard,v 1.9 2003/11/21 11:57:02 djm Exp $