Using a Cryptographic Hardware Token with Linux: the OpenSSL Project's New Engin

by Paul Friberg

Public Key Infrastructure (PKI) is a critical technology in today's computer oriented world. Without it there would be no secure e-commerce transactions or secure connections. Remember the days when clear-text passwords regularly flew across the Net? That's history now due to the increasing diligence of "bad people" sniffing the Net, looking for potential security loopholes to exploit. These days, paranoia is the normal state for computer security, and PKI plays a role in helping to ease that paranoia.

PKI provides a high level of protection by allowing the signing of e-mails, encryption of sockets and other cryptographic functions. A large standards base has evolved around PKI, and the open-source domain has taken on the task of implementing those standards to a high degree. PKI is based on the now well known public/private key-pair interaction. In this interaction a public/private key-pair is generated, and the public-key is used by external entities to verify data signed or encrypted by the private key. The private-key is held securely by the owner. The key can be held secure by a passphrase on either an encrypted file or a hardware token.

Another important component of PKI is a certificate (X.509 format), a document that is signed by a known authority (known as a certificate authority or CA) and says the originator of the public-key is who they really say they are. In order to obtain a valid certificate, the key-pair owner must sign a certificate request using their private-key and send it to the CA. The certificate request provides the certificate authority with information about the owner of the key and a copy of the public-key.

Integrating a Token

With this background, I can start explaining our adventure with PKI. A client wanted to provide digitally signed e-mails for critical data originating from a Linux PC. The critical data had to arrive at a site and be assured that it originated from a given Linux PC. The client needed to perform this task using S/MIME, a standard designed for this purpose (see glossary). The client also wanted to use a hardware cryptographic token for security reasons. Hardware tokens are nearly tamper proof and assure that the data are originating from a given Linux PC provided that the token is plugged into it. Tamper switches on the PC and the token prevented either from being moved without authorities' knowledge.

Since my company prefers to start with open source tools, rather than dive into proprietary libraries or write new code from the "ground up", we quickly discovered the OpenSSL project. The OpenSSL project supported almost all of the necessary components needed to complete our client's project. I say almost all, otherwise our story would have ended here and proven rather boring. The client required the ability to store a 1,024-bit DSA private-key on a specific PCMCIA-based hardware token, generate a certificate request and then, using the certificate and the private-key, clear sign an e-mail using the S/MIME format.

As luck would have it, back in September 2000, the OpenSSL project released version 0.9.6 and a parallel release that included an engine component. The engine component caught our eye because it dealt with using cryptographic hardware tokens. Sadly, the token we were requested to integrate, the Chrysalis-ITS Luna2 PC card, was not on the list of the three tokens implemented in the engine. This forced us to go under the hood of the OpenSSL engine code.

Chrysalis-ITS provided our client with the libraries needed to interact with their token under both Solaris and Linux and the OpenSSL code-base compiles for both. Chrysalis-ITS's Luna2 toolkit library is based on the PKCS#11 standard that is documented by RSA Laboratories. The PKCS#11 is a C/C++ programming standard library for using a cryptographic hardware token with public-key technology. A quick e-mail to the author of the OpenSSL engine component, Geoff Thorpe, confirmed that it would be possible to use a PKCS#11 library with the way the engine was designed. Unfortunately, none of the other 3 cards implemented in the engine were using this standard library (they all had proprietary libraries), so we had to develop an engine implementation without any example code.

Actually, it is not true that we didn't have any example code to work with; we had access to the implementations for the other three hardware tokens. We also had done some work with the PKCS#11 library for the Luna2 token. However, each of these other hardware tokens used RSA (see glossary) and not DSA as the cryptographic mechanism. It seems RSA is the more prevalent method because it is a stronger cryptographic mechanism than DSA. One step forward with an example, but two steps backward since none implemented DSA. However, the CryptoSwift token implementation in OpenSSL, by Geoff Thorpe, did provide a DSA acceleration, so this was the best starting point to implement a solution for the Luna2.

It's interesting to watch different people's approaches to integrating systems. Some like to sit down and spend time reading manuals, and others like to dive in and get into the guts. I am one of the latter types. Rather than rely on reading volumes of manuals to understand how something is glued together, I prefer to run through the code with a debugger (ups is my particular favorite open source debugger). That way I can step in and out of all the functions, look at structures and see all the details being passed around. Once I get a handle on how it all glues together, I proceed to the manuals to get more specifics on code not presented clearly. While the OpenSSL project is doing a great job, some of the documentation on the cryptographic library (libcrypto) is a bit sparse. After testing the command line OpenSSL interface by running all of the tasks, without using the engine (using only text files holding the keys), I had a pretty good understanding of the way it was pieced together.

I next implemented the necessary engine structures for the token and tied the PKCS#11 calls to the appropriate functions. The only conversions necessary were the data types from the native PKCS#11 data into the OpenSSL values. The tricky part was binding all of the necessary PKCS#11 function calls dynamically at run time to the OpenSSL engine.

Some Problems Encountered

The engine implementation dynamically links with a hardware token's library at run time. The user specifies the engine type on the command line, and this loads the necessary library from a structure and links the needed token-specific functions. The "-engine" option to OpenSSL allows the end-user to specify the type of token to use. Under Linux, dynamic linking with a shared-object library happens with the dlopen() call. Unfortunately, the version of the Red Hat6.2 Linux libraries that Chrysalis-ITS provided us with had a minor flaw. One symbol was missing, something leftover from the Solaris libraries (from which the Linux implementation was presumably cloned). As soon as the dlopen() call returned, it indicated an error. The missing symbol, _IO, set me back a few days in head scratching as I tried to find the miscreant library that I was missing in the linking phase. After a few go rounds with the able Chrysalis-ITS customer support staff, I was back in action with a patched library. Its a testament to good customer support when they provide you with a patched library within 24 hours! Furthermore, we got permission to provide the include (cryptoki.h) files from the Luna2 toolkit back to the OpenSSL project.

With the new library in place, OpenSSL performed flawlessly with the engine code for building certificate requests. Unfortunately not all of the OpenSSL commands were implemented for use with the engine. In particular, I needed to sign e-mails using the OpenSSL smime command. After looking over the source code for the OpenSSL "req" implementation, I was able to port the command-line option (-keyform) necessary to get the smime command working within a few hours.

One tricky part of the implementation was deciding how engine-specific issues would be handled. In particular, a user needs to specify which key on the token should be used for signing and provide the pin number for access to a specific token. Because the token also fits into a PCMCIA slot, you have to indicate to the program the slot in which the token is placed. These issues were easily solved by the "-key" argument provided with the smime command. Normally the -key argument points to a file, but in the case of an engine, this is superfluous since the key is on the token. The Luna2, however,allows a number of keys to be placed on the token, so specifying the key that we wanted to use became necessary. Therefore, I used the -key argument to pass the name of the key, the pin number and the slot of the token to be used.

I wrote a simple token initialization program that loaded a DSA key-pair onto the token, and then we were ready to begin. The first thing we needed to perform S/MIME signing, besides the key-pair, was a certificate, and the way to get that was to build a certificate request. This was easy with the new OpenSSL Luna2 engine implementation:

openssl req -engine luna2 -keyform engine -text 
        -key DSA-public:1:1234 -config config_info -out cr.pem

The -key argument holds the name of the key, the PCMCIA slot the key is in and the user's pin number for the token.

The config_info file held the following information needed for the certificate request:

[ req ]
distinguished_name     = req_distinguished_name
prompt                 = no
[ req_distinguished_name ]
C                      = US
ST                     = New York
L                      = New Paltz
O                      = ISTI
OU                     = HQ
CN                     = Paul Friberg
emailAddress           =

Once I received a certificate back from the client's certificate authority, I was ready to sign e-mails using S/MIME. To do that with this implementation, I simply issued the following complex command line, using the file email.txt as input.

openssl smime -sign -engine luna2 -in email.txt -out
        -signer certficate.pem -keyform engine -inkey DSA-Public:1:1234 

The output of the command is a file ( that has a S/MIME clear signed content, with my certificate attached. The certificate is attached to give the receiver some assurance that I am who I claim to be. That is, if they believe the CA who issued it.

With this task finished we delivered a working solution to our client, complete with source code. Having the source code to implement and authors willing to talk with you significantly speeds development. Furthermore, having a customer support team that understands and supports Linux is a tremendous plus.

Paul Friberg is the Vice President of Instrumental Software Technologies, Inc., a software development firm specializing in custom solutions under UNIX and Linux. When not programming, he can often be found clinging to the side of a rock (not under it) or a frozen waterfall. He can be reached at

Load Disqus comments