In this article we explain how to set up your computer to take advantage of the functionality offered by a smartcard.

The Genesi smartcard package includes:

• An Athena IIIe smartcard reader
• A CryptoFlex 32K smartcard

The primary reason we went with these components to implement smartcard support is because they're the de-facto standard and almost universally supported. The reader comes with a GPL driver which is kept up to date meticulously. The smartcard is supported by all popular operating systems and is compatible with a large number of open source applications out of the box. Your smartcard can be set up easily to authenticate you to both Linux, Mac OS X and even Windows computers and because of its GPL'ed driver, it is trivial to smartcard enable a PowerPC or a SPARC computer.

What is the advantage of a smartcard?

The simplest and cheapest type of smartcards available on the market are the memory cards. A memory card allows the user to store data and retrieve data from the card. Typically such cards offer 4k, 8k, 16k, 32k or 64k storage. To be able to read a memory card, you have to know how to interface with the memory chip embedded on the card. Typically this happens at register level. The data stored on the memory card can be read (and thus copied) by everyone. The only advantage offered by a memory card over a magnetic card (the predecessor of the smartcard) is that the memory card can hold more data.

Like a memory card, the more advanced 'true' smartcard is used to store and retrieve data. However, the more advanced smartcard runs its own operating system on the embedded chip designed to protect the data stored on the chip. The operating system that comes with the CryptoFlex smartcard implements various encryption algorithms and is able to generate private and public keypairs on the chip. Herein lies the true power of a smartcard. To explain, I'll use an example.

Private and public keys are commonly used to access a computer without a password. Using your private key you can log in to any system which has your public key installed without having to remember a password. You can distribute your public key without any risk because a public key cannot be used to compute the corresponding private key. Keeping your private key safe is however very important.

To generate a key pair, a computer is used, and that computer's security could be compromised without you knowing it. Your private key is thus only as safe as the computer it was generated on. This is where smartcards come into play. A smartcard such as the Cryptoflex contains a tiny operating system capable of generating key pairs. The private key never leaves the smartcard and thus can never be compromised. The smartcard cannot be duplicated by a computer as nobody has access to the private key. You can even use a compromised computer with a smartcard reader attached to it to generate a safe key pair as the only thing the cracker would be able to steal is your public key (which you do not need to protect).

The private key stored on the smartcard can still be -used- (which is not the same as 'read') to log in to a system holding the correspondig public key even though nobody can read the private key. This works like this: If you want to log in to a computer which has your public key installed, that computer answers your request to log in to the system by using your public key (available on the computer) to encrypt a message. That encrypted message is sent to your smartcard for decryption. The smartcard uses the private key for decryption (typically after asking for a PIN code) and returns the decrypted message, which is then sent back to the computer you want to log in to. The computer verifies whether the message is correct and allows you to log in to the system without ever providing a password and without compromising your private key.

Can smartcards be compromised?

No. A smartcard cannot be copied, nor can anyone have read access to the private key(s) stored on the smartcard. Typically the tiny operating system embedded on the smartcard also implements a pin code which has to be entered before the private key is allowed to decrypt a message. After 3 failed attempts to supply the correct pin code the smartcard can render access to the private keys inaccessible. Typically a smartcard also comes with a PUK code to unlock the card after 3 failed attempts. If the smartcard operating system registers 3 failed attempts to enter the PUK code, the entire card is rendered unusable. They only thing you can do is erase the card and initialize it with a new private key.

If you already have a private key somewhere, you can store it on the smartcard, but that renders your smartcard 'insecure' as the key could already have been compromised. So, if you use a card like the Genesi Cryptoflex to <i>generate</i> a private key, it is guaranteed never to be compromised as long as you don't deliberately give somebody your smartcard and your pin code. (and even then it would be impossible for that person to make a copy of the card).

What is PAM?

If you look at a Gentoo Linux based system, you'll see that there are a number of 'pam' files in /etc/pam.d. Let us consider one of them: /etc/pam.d/passwd;

#%PAM-1.0 auth include system-auth account include system-auth password include system-auth

As you may have guessed the 'passwd' pam script contains metadata on how a user invoking the 'passwd' command needs to be authenticated. Passwd is a command which allows the user to change his password. The 'include system-auth' in this script refers to another script called 'system-auth'. Looking at other files in the pam.d directory we see that a number of them refer to the system-auth script for authentication. Looking at that 'system-auth' script we see that it imposes various requirements on the user wanting to authenticate:

• the user needs to have a 'home' directory
• the user needs to have a user account
• the user password must be at least 2 characters long
• blank passwords are not allowed
• ...

If we want to authenticate users to the system using a public/private key pair and a smartcard we'll have to put some extra requirements in this file (A smartcard has to be inserted, pin code has to be right, ...). The driver of the Athena IIIe comes with a PAM module that takes care of everything. All we'll have to do is call that module in the pam scripts for the applications we want to smartcard enable.

The pam script also defines different authentication fallbacks. For instance, we can try to log in the user using a smartcard first, if that fails (no smartcard is inserted, no smartcard reader is connected), we can authenticate the user using a regular password. Please note that the way pam scripts are set up is very distribution specific. Please also note that an incorrect change to a pam script may render a system vulnerable. Pam can be set up quite easily to allow users to log in to a system without authenticating themselves. Care has to be taken here.

What is LDAP?

LDAP is a directory service i.e. a database with a predefined database schema to which you can connect to to figure out user information, computer information, network information. LDAP is often used to store users public keys. Using pam, a system can be set up easily to consult an LDAP database to fetch user information.

In combination with a pam module called pam_mkhomedir, (which Pieter van den Abeele has ported to various operating systems including Darwin and Solaris), users which have never logged in to a computer before can have a brand new homedir on that system created automatically for them. If you are interested in setting up LDAP to centralize user information in a large network, please don't hesitate to contact smartcards@genesippc.com.

The remainder of this article will focus on non-LDAP system authentication as that is what most of you are currently using.

Setting up the smartcard reader

Various tools and various protocols to speak to a smartcard reader have been created by various companies. Our reader is compatible with all of them. In this howto we'll focus on setting up a USB Athena IIIe Smart Card Reader on a Gentoo Linux machine. If you have a serial version of the reader, the procedure is very similar.

Step 1: Download the smartcard reader driver

The GPL'ed smartcard driver can be found here:

http://www.athena-scs.com/downloads.asp

In our case, we want:

http://www.athena-scs.com/downloads/asedriveiiie-3.1.tar.bz2

Please note that Athena updates its drivers on an almost weekly basis, so by the version number may have changed.

Step 2: Unpack the smartcard reader driver

You can fetch this package by executing the following command:

wget http://www.athena-scs.com/downloads/asedriveiiie-3.1.tar.bz2

Once the package is downloaded is has to be unpacked:

tar jxvpf asedriveiiie-3.1.tar.bz2

That creates two directories, one containing a driver for the serial version of the reader and one directory containing the driver for the usb version of the reader. In our case, we want the USB version as we have an USB reader:

cd asedriveiiieusb-3.1

Step 3: Install the smartcard reader driver

The smartcard driver communicates with the smartcard reader using a protocol called PCSC. This protocol was invented by Microsoft and is very low level, almost register level. Gentoo provides a GPL library called pcsc-lite which has to be installed for our driver to function properly. We therefore need to install it:

emerge pcsc-lite

In my case pcsc-lite-1.2.0 was installed. Your version may be different, but that should not be a problem. To install pcsc-lite on another Linux distribution, please refer to your operating system distribution handbook.

Now that pcsc-lite has been installed, we can continue building the driver:

./configure --with-pcsc-drivers-dir=/usr/lib

If you are using a 64bit operating system you may want to run instead:

./configure --with-pcsc-drivers-dir=/usr/lib64

Now run:

make

followed by a:

cp ./ifd-AseIIIeUSB.bundle/Contents/Linux/ifd-AseIIIeUSB /lib/ mysmartcardreader.so

If you are using a 64bit operating system this last step has to be:

cp ./ifd-AseIIIeUSB.bundle/Contents/Linux/ifd-AseIIIeUSB/lib64/mysmartcardreader.so

So, your smartcard reader driver is now correctly installed. All that remains is to tell PCSC about your reader and set up PAM.

Step 4: Configuring PCSC

Run:

installifd

This prompts the following question

"Please enter a friendly name for your reader (50 chars max)" "----------->"

which you can answer with:

"Genesi Smartcard Reader"

The following questions reads:

"Please enter the full path of the readers driver (4096 chars max)" "Example: /usr/lib/readers/usb/librdr_generic.so" "---------->"

which you have to answer with:

"/lib/mysmartcardreader.so"

The next question prompts you for the port to which the reader is attached. If you're using a serial port, select the correct com port. (On the Open Desktop Workstation using a serial reader, select option 2). If you're using an USB reader, select option 6 by typing in "6".

You have now successfully told PCSC about your smartcard reader. Your operating system is now able to use a low-level protocol to talk to smartcards or memory cards inside your reader. PCSC is a low level protocol, comparable to for example TCP/IP. We now need to install applications that speak to the smartcard using PCSC.

Step 5: Test PCSC

Run:

/etc/init.d/pcscd start

The light on your reader should turn on. /etc/init.d/pcscd is a startup script for the PCSC daemon, which manages your smartcard reader. It is a good thing to have this started automatically when booting your machine, as you'll want to use your smartcard reader to authenticate yourself when the machine has booted. To do this, run:

rc-update add pcscd default

Next time you boot PCSC will be automatically started and you will be able to use your smartcard reader. All that remains right now is to tell PAM about your smartcard reader and configure your own smartcard.

Step 6: Set up PAM

To tell PAM to try smartcard-based authentication before prompting us for a password when logging in to the computer, we need to make a small modification to the pam scripts installed in /etc/pam.d/

There is a smartcard package in Gentoo that comes with a PAM module. That application is called 'OpenSC'

OpenSC is a layer on top of PCSC and allows you to interact with different smartcard operating systems and different memory cards. To install the application on a Gentoo system execute the following command:

USE="pcsclite pam" emerge opensc

For the knowledgeable reader, opensc also has an ldap use flag which installs an ldap-capable PAM module as well. For more information regarding OpenSC and LDAP cfr. http://www.opensc.org/opensc/file/releases/opensc-0.9.6/PAM_README

OpenSC installed a PAM library called pam_opensc.so. We can refer to this library in our pam scripts.

Edit for example /etc/pam.d/system-auth and if you want to use opensc first, and fall back on normal password based authentication, you should add:

auth sufficient pam_opensc.so

right above the line which reads:

auth sufficient pam_unix.so likeauth nullok

PAM will now attempt to try a smartcard-based login if you try to log in to the system. If the smartcard-based login fails, the user will be prompted for a password.

For this step we used opensc-0.9.4, newer versions may behave differently. Please refer to your operating system distributor for information on how to install OpenSC on non-gentoo enabled operating systems.

Step 7: Set up the smartcard

First make sure pcscd is running. Then insert your smartcard into the reader. OpenSC implements various profiles you can use to initialize smartcards. Some profiles don't require PIN codes, other require PIN codes, others implement various special features. OpenSC comes with a configuration file allowing you to configure your own profile. That configuration file can be found in /usr/share/opensc/ opensc.conf.example. We have to copy that file to /etc/opensc.conf before we proceed:

cp /usr/share/opensc/opensc.conf.example /etc/opensc.conf

Note: version 0.9.6 doesn't seem to install this config file. That is probably a bug. 0.9.6 is currently unstable in Gentoo.

The default profile suits our needs perfectly. To initialize the smartcard in the reader execute:

pkcs15-init -E

OpenSC will ask us what transport key we use to talk with the card. A custom transport key can be used if you want to restrict which machines are able to speak to the smartcard. We use the default transport key, so just press enter. For the record, the default transport key is 2c:15:e5:26:e9:3e:8a:19. The card is now empty and can be initialized. To initialize the card we execute the following command:

pkcs15-init -C New Security Officer PIN (Optional - press return for no PIN). Please enter Security Officer PIN: Please type again to verify: Unblock Code for New User PIN (Optional - press return for no PIN). Please enter User unblocking PIN (PUK): Please type again to verify:

This command will ask for PIN and PUK codes for the Security officer. The security officer PIN code will be required if you want to alter the card in the future. The Security officer PUK code is used to unblock the security officer after 3 failed PIN codes.

Next step is to create a user and a pin. That pin is needed for using the keys we will create later.

pkcs15-init --store-pin --auth-id 01 --label "Pieter Van den Abeele" New User PIN. Please enter User PIN: Please type again to verify: Unblock Code for New User PIN (Optional - press return for no PIN). Please enter User unblocking PIN (PUK): Please type again to verify: Security officer PIN required. Please enter Security officer PIN:

Now create a key. Both pins are needed for this.

pkcs15-init --generate-key rsa/1024 --auth-id 01 Security officer PIN required. Please enter Security officer PIN: User PIN required. Please enter User PIN: Security officer PIN required. Please enter Security officer PIN:

We now have initialized the card and created a key. Using this key we can now create a 'certificate' we can issue to a system to which we want to log in to using the smartcard. To generate such a certificate run:

$ openssl OpenSSL> engine dynamic -pre SO_PATH:/usr/lib/opensc/engine_pkcs11.so \ -pre ID:pkcs11 -pre LIST_ADD:1 -pre LOAD \ -pre MODULE_PATH:opensc-pkcs11.so (dynamic) Dynamic engine loading support [Success]: SO_PATH:/home/aj/opentest/lib/opensc/engine_pkcs11.so [Success]: ID:pkcs11 [Success]: LIST_ADD:1 [Success]: LOAD Loaded: (pkcs11) pkcs11 engine OpenSSL> req -engine pkcs11 -new -key id_45 -keyform engine -out req.pem -text -x509 SmartCard PIN: You are about to be asked to enter information that will be incorporated into your certificate request. What you are about to enter is what is called a Distinguished Name or a DN. There are quite a few fields but you can leave some blank For some fields there will be a default value, If you enter '.', the field will be left blank. ----- Country Name (2 letter code) [AU]: . State or Province Name (full name) [Some-State]: . Locality Name (eg, city) []: . Organization Name (eg, company) [Internet Widgits Pty Ltd]: . Organizational Unit Name (eg, section) []: . Common Name (eg, YOUR name) []: Andreas Jellinghaus Email Address []: aj@dungeon.inka.de Please enter the following 'extra' attributes to be sent with your certificate request A challenge password []: An optional company name []: OpenSSL>

We can store this certificate on our smartcard:

$ pkcs15-init --store-certificate req.pem --auth-id 01 --id 45 -- format pem Security officer PIN required. Please enter Security officer PIN:

All that is left is to install the certificate onto the machine, inside our homedir and try out logging in using the smartcard:

Now every user needs to create a directory ".eid" in his or her home directory and put the certificate in a file called "authorized_certificates". To do this, enter the command (beware, this will overwrite the file):

$ pkcs15-tool -r 45 -o ~/.eid/authorized_certificates

Now try to login using the smart card. Remember to first insert your smart card into the reader, then enter your username, and then the pin on your key.

That's it. Questions welcome.

Pieter van den Abeele (smartcards@genesippc.com)