# SSH Secure Shell

On Windows you can use putty to establish secure shell connections with smart card authentication. The normal putty doesn't have smart card support, but if you install the PuTTY SC, it contains PKCS#11 support for Putty.

On Linux and Mac OS X you can use OpenSSH. OpenSSH does support smart card authentication, you have two alternatives:

- Mainline - only if the support for OpenSC is enabled during compile time. Most distributions however ship a binary package that does not include OpenSC support. You can simply download the source code or source rpm package, and recompile it using "configure --with-opensc=/usr".

- PKCS#11 - external patch available from here, this works with most smartcards, even ones that are not supported directly by OpenSC project.

Note that OpenSSH has a small issue: the "ssh" command does not ask for the smart card pin. This is known to the OpenSSH developers as bug 608. OpenSC includes a patch to fix OpenSSH in src/openssh/ask-for-pin.diff, we suggest to patch openssh source code with this file before compiling OpenSSH.

You can test if your openssh supports smart cards:

    $ ssh -I 0 user@server.example.org
    no support for smartcards.

If your openssh is compiled with smart card support, it will instead use the smart card in reader 0. Users of the ssh-agent can use "ssh-add -s 0" to send the pin to your agent, so you don't need to enter it for every connection.

## PuttyCard

PuTTYcard is a second, independent implementation to add smart card support to putty. Read more about it here, and download the files from opensc-project.org contrib directory.

## old content

# OpenSSH and OpenSC

OpenSSH contains support for opensc, if it was compiled with "--with-opensc". Unfortunately the openssh version included in most distributions is not compiled this way. You can recompile openssh yourself. Ready-to-use binary packages are available here:

Distribution | Download URL
Name | ADD URL
Gentoo | The USE-flag "smartcard" makes the openssh ebuild depend on opensc and apply appropriate patches. Add the USE-flag system-wide to /etc/make.conf or just for OpenSSH in /etc/portage/package.use and re-emerge openssh. `USE=smartcard emerge openssh` will still work but is discouraged by Gentoo.

If you compile OpenSSH yourself: Please apply the patch in opensc-0.9.6/src/openssh/ask-for-pin.diff. This patch fixes a small issue: openssh "ssh" command will not ask for a pin and thus not work well with smart cards. Ssh-add will ask for a pin, and thus ssh plus ssh-agent will work well. This patch adds code so that ssh will ask for the smartcard pin, too. This patch was not accepted upstream so far, the openssh development team has a concept for a rewrite towards a cleaner solution, but this is still pending. So for now the patch is our best option. Seel also: OpenSSH bug 608

## Using OpenSSH with a smartcard

    ssh -I 0 root@somehost

will use the smart card in reader 0 and private authentication keys on the card to authenticate as root on host somehost. This will of course only work if root@somehost has a ".ssh/authorized_keys" file and the public key related to this private key is in that file.

    ssh-keygen -D 0

will download the public key from your smart card and print it in ssh1 and ssh2 format. You only need one of those two lines. Put it into ".ssh/authorized_keys" on the target host and account like you do with a normal .ssh/id_rsa.pub file. You can add a space char and a comment at the end of the line, I usually add something like " aj@smartcard" so I know this is the key from my smartcard.

Starting with the next OpenSC release you can also use pkcs15-tool to display a public key in openssh format. To do this type

    pkcs15-tool --read-ssh-key [--reader 0] [--id 45]

the default reader is 0 and the default id is 45, so typically you don't need those options. (This might be useful for windows, since putty/pageant currently has no equivalent of "ssh-keygen -D 0".)

The OpenSSH public key format is defined at http://www.ietf.org/internet-drafts/draft-ietf-secsh-publickeyfile-09.txt

TODO: it would be propably nicer to have one --read-public-key parameter, and a second optional parameter --format with possible values der, pem, ssh1, ssh2. A patch to implement this would be very welcome.

## Using an agent

Most convinient way to do frequent authentications it to use the ssh-agent store your key. To do this you have to make sure ssh-agent is running, and it is accessible from your environment. Using XWindows the best way to start the agent is to edit the /etc/X11/Xsession.options file, and add this line:

    use-ssh-agent

This will automatically start the agent when you log in, and it will shut it down upon logout.

To see if the agent is accessible just type:

    $ ssh-add -l
    The agent has no identities.

If the agent is not accessible you'll get an error message. This command is also usefull to list the certificates you've already added to the agent.

To add your certificate to the agent you should type

    $ ssh-add -s 0

where 0 is the number of your certificate. The agent will ask for your pin, then it will store it decrypted for later use. Now you can simply ssh to the given hosts, without the need to type the pin again.

If you're accessing multiple hosts through ssh you can turn agent-forwarding on.

Using ssh-agent on a unix system has some security issues. Please make yourself clear with them before using these features.