Overview

Mac OS X 10.4 has a native support for smart cards, called Tokend.

Native Mac applications (Safari browser, Mail client) will be able to automatically use the keys on the card that are supported by the Tokend.

There is an OpenSC tokend as part of OpenSC's sca package for Mac OS X. It uses the OpenSC library (the PKCS15 layer, not the pkcs11 lib) and should therefore support the same cards. It can be use together with other OpenSC lib/apps such as the pkcs11 lib for the Mozilla family of browsers and mail clients.

Currently supported are

• Keychain Access (to view the contents of the smart card)
• Safari browser (SSL client authentication)
• Mail client (sign and decrypt emails) -- Note: the account's mail address must be present in the cert

For more info:

• Max OS X:  http://developer.apple.com/documentation/MacOSX/Conceptual/OSX_Technology_Overview/ (OSX_Technology_Overview.pdf)
• Mac OS X for UNIX Users:  http://images.apple.com/macosx/pdf/MacOSX_UNIX_TB.pdf
• Apple-cdsa mailing list:  http://lists.apple.com/mailman/listinfo/apple-cdsa

Limitations:

• PIN handling is currently limited to only one pin.
• GUI talks about passwords but should talk about PINs
• No way to change other pins than the first one via a GUI
• Hardcoded to 1024b RSA (this was fixed in SCA 0.2.7).

How to build the OpenSC tokend

OpenSC.Tokend is installed by default by the last release of SCA. You don't need to build it as end user. This is for reference only (for developers and for curious...).

This is pretty complicated, most is based on the doc "Building Tokend Using the Darwin Build Scripts 1.1" that can be requested on the apple-cdsa mailing list. Here we will build the PPC and the i386 part on a PPC based Mac.

Make sure you have Mac OS X 10.4.6.

If you want SVN (subversion): download and install fink  http://fink.sourceforge.net/ and use fink to obtain svn: "sudo fink install svn-client" in a Terminal window.

1. download and install Xcode 2.2 or later from  http://developer.apple.com/tools/
2. Download, build and install darwinbuild 0.7.2 or later from  http://opendarwin.org/projects/darwinbuild/
3. Create a disk image to contain the build environment

(This way your regular system won't be modified when all frameworks etc. are downloaded)

• hdiutil create -size 2g -type UDIF -fs HFSX -volname Builds -uid 0 -gid -0 -attach Builds.dmg
• Become root (su or sudo /bin/bash)
• vsdbutil -a /Volumes/Builds (/Volumes/ is where all filesystems like disks, USB sticks and disk images are mounted)

Note: next time you start your Mac, you need to re-open the builds.dmg disk image again before you can work with it: double-click on it in Finder or do "hdiutil attach Builds.dmg" in a Terminal window.

4. Download and build the Tokend code from opendarwin

This is done in a subdirectory of /Volumes/Builds/. It's name depends on the 10.4.x version that you have. For example:

• For 10.4.4: Build8G32
• For 10.4.5: Build8H14 (note that Darwinbuild does not support Mac OS X later than 10.4.5)

(See  http://www.opensource.apple.com/darwinsource/ to find the build number (click on Source link, then on the TEXT link. The build number is in the first line. You also need to check  http://darwinsource.opendarwin.org/plists/ to see if the most recent version is available for darwinbuild)

In what follows, we assume we are building for 10.4.5.

• cd /Volumes/Builds
• mkdir Build8H14
• mkdir Build8G1454
• cd Build8H14
• /usr/local/bin/darwinbuild -init 8H14
• /usr/local/bin/darwinbuild -load gnutar
• /usr/local/bin/darwinxref -b 8A428 edit

This opens vi or vim (yes:-) where you have to remove 'i386' from RC_ARCHS (use the arrow keys to go to 'i386', then hit x to delete it, then use the ESC button to go back to normal mode and type :wq or :wq!)

• cd ../Build8G1454
• /usr/local/bin/darwinbuild -init 8G1454
• /usr/local/bin/darwinbuild -load gcc
• /usr/local/bin/darwinbuild -load libstdcxx
• /usr/local/bin/darwinbuild -load gnutar
• /usr/local/bin/darwinxref -b 8A428 edit

Remove now 'ppc' from RC_ARCHS

Fisrt, we build for PowerPC architecture.

• cd /Volumes/Builds/Build8H14
• sudo /usr/local/bin/darwinbuild Tokend

This command will download the Tokend-25868 code and all required libs,frameworks,... and build the tokend's as Apple did. It will take a while.

Then, we build for i386 architecture.

• cd /Volumes/Builds/Build8G1454
• sudo /usr/local/bin/darwinbuild Tokend

This command will download the Tokend-26098 code and all required libs,frameworks,... and build the tokend's as Apple did. It will take a while.

• cd /Developer/SDKs/MacOSX10.4u.sdk/Library && ln -sf /Library/OpenSC OpenSC

Your Darwinbuild environment is ready now. You only need to perform theses steps once.

5. Obtain and install sca.

Download the installer from http://www.opensc-project.org/sca/, or look at this site for info on how to get the sources and build it yourself

After installation, everything should be in /Library/OpenSC/.

During the process to build OpenSC.Tokend, we need the OpenSC libraries.

6. Obtain and build the OpenSC tokend code.

This is part of sca source, just search for the opensc.tokend/ directory.

Everything is done through the Makefile.

• make build-tokend ; make build-tokend-end

The Universal OpenSC.tokend will be placed in compiled-opensc_tokend/System/Library/Security/tokend

FYI: The Tokend-xxxxx/ directory is based on the one from opendarwin:

• The BELPIC, CAC, MuscleCard and Tokend targets/products were removed from the project
• The BELPIC, CAC and MuscleCard directories were removed
• The cpp files (not the .h files) from the Tokend dir were removed (it uses the libtokend.a lib that was made with /usr/local/bin/darwinbuild)
• The project has been modified to build with Xcode instead of with /usr/local/bin/darwinbuild

Tokend / usability notes

• If you update your certificates on the token make sure to remove the cache or old certificates shall be used:

  sudo rm -rf /var/db/TokenCache
  

  Another option might be not to give the token a pre-calculated id (see #7)
• Insert card, visit SSL site via safari, remove card, visit some other sites, insert card, go to the same SSL site again. On first visit one gets 'certificate rejected' but after pressing 'reload' pin is asked and page displayed correctly.
• Safari could warn when the validity period for a certificates is known to be bad - generic 'client ceritificate rejected' message is confusing