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