Ubuntu Wiki

This page will guide you though the process of setting up an ISO 7816-1,2,3,4 compliant cryptographic Smart Card to act as an LUKS unlock key and/or a user sign on token for KDE3.5.

Table of Contents

For Jaunty and above

I have replaced the old instructions below with an automated setup utility, currently published on my PPA here: https://launchpad.net/~kde3-maintainers/+archive/ppa/+sourcepub/685732/+listing-archive-extra

If you are using the KDE3.5 version of Kubuntu, you already have that PPA ready to use on your system--just install the package "smartcardauth".

Once that package is installed, go to "Start"-->"System"-->"SmartCard Authentication Setup". If you have an encrypted installation of Kubuntu, select "First Time Setup Wizard", click OK, and follow the instructions.

If you do not have an encrypted installation, and simply wish to use the automatic sign on functionality, select "Load Username" from the main menu. When you have completed that process, also select and complete "Load Password" and "Enable automatic logon for KDE3.5".

It is a good idea to change your SmartCard's transport key from the default manufacturer's key. Please select "Update SmartCard Transport Key" from the menu and follow the instructions.

If you encounter any problems, please file a bug report at http://bugs.pearsoncomputing.net This is still a somewhat experimental package, and bugs may exist in it.

I would like to extend functionality to also include Gnome. This should be a relatively simple task, and if anyone would like to help I would appreciate it!

Details of Bootup Sequence

• Ubuntu to SmartCard: Request challenge

• SmartCard to Ubuntu: Challenge

• Ubuntu to SmartCard: Encrypted challenge using DES and your preprogrammed key

• SmartCard to Ubuntu: Login result (successful/unsuccessful). If unsuccessful, do not continue and prompt user to manually enter LUKS passphrase.

• Ubuntu to Smartcard: Get LUKS key

• SmartCard to Ubuntu: 255-byte LUKS key

Known working hardware

• Computers:
  • Lenovo R61i
• Smart Card Readers:
  • Lenovo integrated USB reader [17ef:1003]

  • Dell Computer Corp. SmartCard Reader Keyboard [413c:2101]

  • Generic USB integrated reader
• Smart Cards:

  • Schlumberger MultiFlex 3k

• Operating Systems:
  • Kubuntu 'Hardy' 8.04 x64 KDE 3.5.9
  • Kubuntu 'Jaunty' 9.04 x64 and i386 KDE 3.5.10

Old Information

This will be a HOWTO for setting up SmartCard authentication for LUKS encrypted disks. I am using several scripts that others have written, as well as some of my own. For the most part, this HOWTO will focus on getting the SmartCard and associated LUKS unlock programs working, but a minimal LUKSHowTo has been added for continuity.

This HOWTO currently targets Schlumberger MultiFlex Smart Cards and Lenovo ThinkPad R61/T61 card readers, although other configurations may also work.

WARNING: I am not responsible if this HOWTO makes your system unbootable or worse. Consider this document as alpha quality--only users with experience in smart cards, initramfs, and LUKS should attempt this procedure.

Software Requirements

• pscsd
• initramfs-tools
• libpcsc-perl
• libpcsclite1
• libccid
• pcsc-tools
• opensc

Install the required software: sudo apt-get install pcscd initramfs-tools libpcsc-perl libpcsclite1 libccid pcsc-tools opensc

LUKS Setup

Much of this information has been taken from the excellent free tutorial at http://wejn.org/how-to-make-passwordless-cryptsetup.html, and then condensed and altered to integrate it into this HOWTO

• You must have an Ubuntu system that already has a LUKS passphrase encrypted root--this is doable with the Ubuntu Alternate Installation CD.

• Determine your encrypted partition: sudo cat /etc/crypttab You will see something like /dev/sda2; this is your encrypted root partition

• Create a directory sudo mkdir /crypto and sudo cd /crypto

• Generate a random 255-byte keyfile: sudo head -c 255 /dev/urandom > smart.key

• Execute sudo chown -R root /crypto , sudo chgrp -R root /crypto , and sudo chmod -R 600 /crypto -- this will lock down your keyfile so that only root can access it

• Now run sudo cryptsetup luksAddKey /dev/sda2 /crypto/smart.key, where /dev/sda2 is the device node you found earlier in crypttab. You will need to enter your primary encryption passphrase, which is what you have been using to start Ubuntu.

• Now /etc/initramfs-tools/modules must be edited. nano is my favorite text editor, so we'll use that: sudo nano /etc/initramfs-tools/modules Append the following lines to that file:

  • dm_moddm_crypt
    aes_x86_64
    sha256
    
    vfat
    fat
    nls_cp437
    nls_iso8859_1
    
    hci_usb
    usb_storage
    libusual
    ehci_hcd
    uhci_hcd
    usbcore
    
    ext2
    reiserfs

• Ctrl+S to save, Ctrl+X to exit.

• Now edit the crypttab file: sudo nano /etc/crypttab Change the key option field from none to smart.key and append ,keyscript=/usr/local/sbin/cryptosmartcard.sh to the luks option. Save and exit nano.

• cd /usr/local/sbin/ and download this script to that directory: cryptosmartcard.sh

• chmod a+x /usr/local/sbin/cryptosmartcard.sh to make the key retrieval script executable.

• update-initramfs -u all to update your initramfs image.

The updated script will still allow you to enter your LUKS password and start the system if the SmartCard breaks or is not available.

SmartCard Setup

• The SmartCard must be programmed with:

  • Your LUKS keyfile

  • A private key that only Ubuntu and the SmartCard will know

I have written a script to provide an easy SmartCard programming interface. You can download it here: loadsmartcard.sh

Simply make the script executable with sudo chmod a+x loadsmartcard.sh after download, then execute sudo ./loadsmartcard.sh from your favorite terminal program and follow the on-screen instructions.

You will need to:

• Update your transport key [AUT1] to a new, secure key that only the system and the SmartCard will know. The new transport key must be 16 hexadecimal characters in length.

• Upload the 255-byte LUKS keyfile in /crypto/smart.key to the SmartCard.

SmartCard programming is now complete! If you ever need to change the LUKS keyfile, simply repeat the last step with your new keyfile.

Initramfs Setup

• The initramfs image must be rebuilt in order to recognize the SmartCard at system startup and automatically load the keyfile.

  • Configure LUKS keyscript (see section above)

  • Download cryptopensc into the /etc/initramfs-tools/hooks directory.

  • Make that hook executable with sudo chmod a+x /etc/initramfs-tools/hooks/cryptopensc

  • You will need to make a new directory /smartbin for the other SmartCard scripts and utilities. Execute sudo mkdir /smartbin, then download scriptor and smartauth.sh into that directory.

  • Change <your key in hexidecimal> inside /smartbin/smartauth.sh file to match your AUT1 key.

  • Rebuild the initramfs with sudo update-initramfs -u

  • Lock down the /smartbin directory with sudo chmod -R 600 /smartbin This will prevent unauthorized users from accessing the SmartCard access key. It would also be a good idea to lock down the initramfs image with sudo chmod 600 "/boot/initrd.img-$(uname -r)"

KDE 3.x Automatic Login and Lock/Unlock

Install the extra required software: sudo apt-get install inn2

• Download the helper script smartauthmon.sh to /smartbin/smartauthmon.sh

• Change <your key in hexidecimal> inside the /smartbin/smartauthmon.sh file to match your AUT1 key.

• Set /smartbin/smartmonauth.sh to run as root in the background near KDE startup.