PKCS#11 Support in OpenSSH



Everyone knows OpenSSH, My work is to make it more secure, by allowing user to use smartcards in order to store their private keys. Track merge status at midrot bugzilla.

NEWS: Upstream implemented PKCS#11 support, without the use of pkcs11-helper library. This is a different implementation.

As a result I am no longer maintaining these patches.

OpenSSH Patches


Autoconf - error if pkcs11-helper is not found.

Add missing uuencode.h.

openssh-5.2pkcs11-0.26.tar.bz2  (also openssh-5.3)



More cleanups.




Add scp -# support. 



Fix typo in id message. 




More cleanups.

Add manpages. 



Use standard ssh-askpass instead of prompt program.

Please notice that the packaging is changed to individual patches, please refer to the README file. 



Major changes: Parameters changed again, please see ChangeLog.



Major changes:

1 pkcs11-helper is now external dependency.

2. ssh-add uses serialized ids, refer to README.pkcs11.

3. Specify --with-pkcs11 to configure in order to enable PKCS#11 support.


Works also with openssh-4.6p1, openssh-4.7p1


  - (alonbl) Rebase to openssh-5.2.

  - (alonbl) Autoconf - error if pkcs11-helper is not found.
  - (alonbl) Add missing uuencode.h.
  - (alonbl) Release 0.26

  - (alonbl) More cleanups.
  - (alonbl) Release 0.25

  - (alonbl) Add scp -# parameter.
  - (alonbl) Release 0.24

  - (alonbl) Rebase to openssh-4.9.

  - (alonbl) Fix typeo in add id message.
  - (alonbl) Release 0.23

 - (alonbl) Fix typeo in add id message.
 - (alonbl) Release 0.22

 - (alonbl) More cleanups.
 - (alonbl) Add manpages updates.
 - (alonbl) Release 0.22

 - (alonbl) I was not aware of the fact that askpass can be
   used in the agent environment.
   The PKCS#11 patch now use the standard ssh-askpass interface.
   So you must have one available at your system.
   Removed the prompt-prog argument from ssh-add.
 - (alonbl) The patch is now a tarball with split patches.
 - (alonbl) Releae 0.21

 - (alonbl) Indent file to meet BSD styles.
  - (alonbl) Modify parameters (again) to meet BSD styles.
   I truly regret that I keep modifying the parameters, I believe
   this is not the last time, as I don't have full cooperation of
   Get provider keys:
        ssh-add --pkcs11-show-ids ...
        ssh-keygen -K provider_info
   Add key:
        ssh-add --pkcs11-add-id ...
        ssh-add -I id [session_cache [cert_file]]

   Agentless operation (not recommended, OpenSC compatibility):
        ssh -# provider_info ...

   Because I don't wish to add more switches, I added a format
   for provider information:
   Most implementations require specifying only the library name.
- Rebase with openssh-4.7p1.
- (alonbl) Release 0.20

- (alonbl) Fixed typeo in X.509 detection, thanks for "Sandro Wefel".
- (alonbl) Release 0.19

- (alonbl) Removed pkcs11-helper since it is now a standalone library.
- (a lonbl) Default is PKCS#11 support is disabled, to enable configure
with --with-pkcs11
- (alonbl) Rebase with openssh-4.5p1.
- (alonbl) Release 0.18

- (alonbl) Removed logit from ssh-agent, thanks to Denniston, Todd.
- (alonbl) Release 0.17

- (alonbl) Major modification of ssh-add command-line parameters.
Now, a complete serialized certificate needs to be specified, this
in order to allow people to add id without forcing card to be available.
But to allow complete silent addition a certificate file also needed.
--pkcs11-show-ids is used in order to get a list of resources.
--pkcs11-add-id --pkcs11-id <serialized id> \
[--pkcs11-cert-file <cert_file>]
- (alonbl) PKCS#11 release 0.16

- (alonbl) OpenSC bug workaround.
- (alonbl) PKCS#11 release 0.15

- (alonbl) Some pkcs11-helper updates.
- (alonbl) Rebase against 4.4p1.
- (alonbl) PKCS#11 release 0.14

- (alonbl) PKCS#11 fixed handling multiproviders.
- (alonbl) PKCS#11 release 0.13

- (alonbl) PKCS#11 modifed to match X.509-5.5 patch, works OK with focing
ssh-rsa id.
- (alonbl) PKCS#11 removed --pkcs11-x509-force-ssh argument.
- (alonbl) PKCS#11 release 0.12

- (alonbl) PKCS#11 fix issues with gcc-2
- (alonbl) PKCS#11 fix issues with openssl-0.9.6 (first) version.
- (alonbl) PKCS#11 modified to match X.509-5.4 patch.
- (alonbl) PKCS#11 add --pkcs11-x509-force-ssh argument to force ssh id out
of X.509 certificate.
- (alonbl) PKCS#11 release 0.11

- (alonbl) PKCS#11 fix handling empty attributes.
- (alonbl) PKCS#11 release 0.10

- (alonbl) PKCS#11 code sync.
- (alonbl) PKCS#11 release 0.09


The PKCS#11 patch modify ssh-add and ssh-agent to support PKCS#11 private keys and certificates (

Implementation is based on pkcs11-helper (, it allows using multiple PKCS#11 providers at the same time, selecting keys by id, label or certificate subject, handling card removal and card insert events, handling card re-insert to a different slot, supporting session expiration.

A valid X.509 certificate should exist on the token, without X.509 support it is exported as regular RSA key. Self-signed certificates are treated as RSA key and not as X.509 RSA key.

If you like X.509 ( support apply the X.509 patch AFTER the PKCS#11 patch. You can use -o PubkeyAlgorithms=ssh-rsa in order to authenticate to none X.509 servers.

Please notice that a program such as x11-ssh-askpass must be installed on your system
to use smartcards with the agent. 

Usage can be printed using the following commands:

$ ssh-keygen -h
$ ssh-add -h
$ ssh -h

A common scenario is the following:

$ ssh-agent /bin/sh
$ ssh-add -K /usr/lib/pkcs11/
$ ssh-add -I 'serialized id'
$ ssh myhost

In order to see available objects, you can use:

$ ssh-keygen -K /usr/lib/pkcs11/

In order to add id without accessing the token, you must put the certificate in a PEM file and use:

$ ssh-add -I 'serialized id' -1 my.pem

Agentless configuration is also supported but not recommended, it loads all
available keys from provider:

$ ssh -# /usr/lib/pkcs11/ host1

In order to debug open two shells:

1$ rm -fr /tmp/s; ssh-agent -d -d -d -a /tmp/s
2$ SSH_AUTH_SOCK=/tmp/s; export SSH_AUTH_SOCK;
2$ [ssh-add]...

X.509 Support in OpenSSH

X.509 Support in OpenSSH

I recommend of using PKCS#11 with X.509 support developed by Roumen Petrov.

Why is X.509 related to smartcard support?

Current OpenSSH approach is good for small systems or individuals... But it does not scale. And worse when OpenSSH standard interface is raw keys on files, it creates a false sense of security. False because since OpenSSH have a record of a security product... And most people do not know better.

Let's say that the user knows that his key was stolen, now he has to create a list of every system that trusted his stolen key and remove the trust. During this phase, the user will most likely forget a few systems, that left vulnerable.

Most users will not report that their key was stolen and continue using it... The effort to update a new key in all the systems is too big. So every remote system is left vulnerable.

On enterprises, managing raw keys that are distributed all over with people come and go is very difficult, people that leave the enterprise will most likely be able to continue using their keys afterwards for a long period.

But there is an advantage... The user can backup his keys... So he can recover his keys from the last backup. So the user never loses his keys and can access his remote systems and modify their trust if he wishes by him-self.

Now... when user chooses to use smartcard, I assume he does this because it is more secure... and not because it is a neat device...

The environment should support this smartcard user. Smartcard keys cannot be backed up... So if the user
lose/locks/damages his card he also loses his keys. Since he does not have his key, he cannot generate a new key and modify the trust of remote systems by him-self... He need to contact the administrator of each remote system and ask him to update the trust, his situation is worse, since he has no way to prove his identity to the administrators, because he lost his keys...

Until all the administrators responses the remote systems are vulnerable... But please remember that there are few systems that the user forgets...

Again... If the user uses smartcard because he want to enhance security, the last requirement would be to revoke his last identity from *ALL* remote systems. X.509 provides this service.

In order to summarize my argument:

1. X.509 is needed since smartcard user cannot backup his keys, every change of smartcard result in remote system update for *ALL* systems. The management overhead is huge. When using X.509 the user enrolls a new certificate using a different key, and then can access all remote systems without any remote change.

2. X.509 is needed in order to revoke old identities, thus not allowing ghost identities to exist on remote systems. It completes the security requirements when moving from software based storage to smartcards.

3. People who use PKCS#11 most likely uses it in X.509 environment and they wishes to use the same identities also with openssh.

And on one sentence... If a user (on large scale) come to a conclusion that he wishes to use secure environment, he most likely use smartcard (PKCS#11) and X.509, drooping any will result in a security weakness.