Smartcard as Keychain

The first step is to get it working with Mac OS X is to check that it shows up as a Keychain with the certificates you loaded on it. Open /Applications/Utilities/Keychain Access.app and look in the list of keychains at the top left. There should be an entry for your smartcard – if you didn’t give the smartcard a label when initialising it, the keychain will be named ‘OpenSC Card …’. If you click on the keychain in the list, you should see the contents include any certificates and keys that you loaded on the card. Make sure that any certificates that identify you, with associated private keys on the card, show up in the ‘My Certificates’ category.

If the card doesn’t show up as a keychain, it means the OpenSC Tokend (the software component which communicates with the card on behalf of OS X) isn’t operating properly. Unfortunately the best way to debug this is to look at the log files in Console.app.

In the system.log file when the card reader is plugged in you should see the smart card reader (SmartcardCCID) start up:

com.apple.securityd[44]: /SourceCache/SmartcardCCID/SmartcardCCID-35253/ccid/ccid/src/ifdhandler.c:1323:init_driver() Driver version: 1.3.8
pcscd[6663]: Non-smartcard device launched pcscd [Vendor: 0X54C, Product: 0X155]

Then when the card is inserted into the reader (or immediately afterwards, if you are using a USB token with integrated card and reader), you should see messages similar to this in the secure.log file:

com.apple.SecurityServer[44]: Token reader ACS ACR 38U-CCID 00 00 inserted into system
com.apple.SecurityServer[44]: token inserted into reader ACS ACR 38U-CCID 00 00
com.apple.SecurityServer[44]: reader ACS ACR 38U-CCID 00 00 inserted token “OpenSC Card” (OpenSC3090241616010310) subservice 2 using driver com.apple.tokend.opensc

This shows that a ‘token’ (i.e. a smartcard) was inserted into the card reader, and it was recognised by the OpenSC Tokend.

Login Authentication

To get Mac OS X to use this smartcard to authenticate you, it must have a certificate and accompanying private key already loaded onto it (see part 1). Now we must add an attribute to your user record in OS X containing the public key hash of the certificate. OS X will notice if a smartcard with the associated certificate and private key is inserted, and allow you to log in.

Adding the attribute can be done with a command-line tool named sc_auth. Insert the smartcard with the certificate you want to use, open up a terminal, and type in:

sc_auth hash

This should list the public key hashes and names of any identity certificates found in all your keychains, giving output similar to this:

DD5D693D420A9FEFDA979950142F8B592C869139 OpenSC Card (User PIN):Your Network ID Certificate
9A63B1932497A1D95967857FACD4A4B19A7C5226 com.apple.systemdefault
CCD99DBE1CE0D3962CA4D329BB5943EB83C78E68 localhost
BC944D344B2323615597B89DF836FEBF0177053C com.apple.kerberos.kdc

Ignore the com.apple… and localhost entries for now. The hash we want is the top one which relates to the certificate on your smartcard. It might also just be called ‘Private Key’. Copy your 40-character hash string from this row (the hexadecimal part before “OpenSC Card…”), and paste it into the following command:

sudo sc_auth accept -u username -h DD5D693D420A9FEFDA979950142F8B592C869139

Substitute your username for ‘username’ and your certificate hash value for the one above. sudo will ask for your password, then sc_auth will add an attribute to your user record identifying the certificate as one that is accepted for logging you in.

To test it, remove the smartcard, and log out. At the login window, insert the smartcard and wait a few seconds. The normal login window with a password box should change to showing a PIN prompt. Type in the smartcard’s PIN, and it should authenticate you using the associated private key on the smartcard, and log you in. You should also be able to authenticate yourself by typing in the PIN when performing an option that requires privileges (e.g. unlocking the padlock icon in System Preferences).

Digitally Signing and Encrypting Email

If you have the OpenSC tokend working, and a valid email signing certificate on your smartcard, Mail.app should be able to digitally sign and encrypt email, using the S/MIME standard, without any extra configuration. There are a few things to note, though:

• You need a valid (non-expired) certificate on the smartcard, with your email address in the emailAddress field.
• The email address on the cert must match your address as set up in your account in Mail.app (case sensitive).
• If you start Mail.app with no smartcard inserted, you may need to restart it to get the signing and encryption options to appear.
• Your email signing certificate must be issued by a widely trusted CA (e.g. Thawte, Verisign, Comodo, etc) for it to show as ‘trusted’ in other people’s mail clients.
• To encrypt an email to someone, you must have their email certificate, as well as having you own. You can digitally sign emails to anyone, though. The easiest way to get someone else’s email certificate is to get them to send you a signed email.

You’ll need:

• The Mac Installer Package from OpenSC
• A blank smartcard supported by OpenSC (see list)
• A card reader with Mac OS X support (The best choice is a CCID compliant USB device, see list)

I’m using a Feitian PKI card from gooze.eu which is supported by the entersafe driver in OpenSC. Other good choices are the Aventra MyEID card, or a blank JavaCard which can be loaded with the MUSCLE applet. Please note that I’ve only tested this with the Feitian PKI card and an ACR-38U CCID compatible reader – YMMV with other combinations of cards and readers! The OpenSC Wiki provides useful information on initialising many different types of cards.

Install OpenSC

Download the Mac Installer package mentioned above, and install the package contained within. This will install OpenSC to /Library/OpenSC, and also install a few other components which integrate OpenSC with Mac OS X. The most important of these is the Tokend (Token Daemon), a component which integrates your smartcard with the Keychain framework in OS X.

Testing OpenSC

Open a Terminal window. Plug the card reader into your Mac, and enter the command

opensc-tool --list-readers

You should see your card reader shown in the list, like this:

Readers known about:
Nr.    Driver     Name
0      pcsc       CASTLES EZ100PU 00 00

Then, insert your blank smartcard into the reader, and enter the command (assuming you are using reader 0):

opensc-tool --reader 0 --atr

You should see a string of hex digits which identifies your card. Now, check that OpenSC recognises the card and can match it to a driver:

opensc-tool --reader 0 --name

should print a human-readable name for the card. For my Feitian PKI card it just prints “entersafe”.

Initialising the PKCS#15 structure

If all these tests succeed, you can proceed to initialising the PKCS#15 structure on the card. For this we use the pkcs15-init command from OpenSC:

pkcs15-init -CT -p pkcs15+onepin --no-so-pin --pin yourpin --puk yourpuk --label "YourName"

The options here are:

• -C creates the PKCS#15 files.
• -T uses the default Transport Key (a key needed to access the card).
• -p pkcs15+onepin sets the card to use a single PIN for all operations.
• —no-so-pin tells the command we don’t want a Security Officer PIN.
• —pin yourpin specifies the PIN. Replace yourpin with whatever you want to use.
• —puk yourpuk specifies the PUK (Unblock code). Replace yourpuk with whatever you want to use.
• —label “YourName” gives the card a name which it’ll be displayed under in the Keychain and other applications.

We are only using one PIN here as the card will just be for personal use. We also don’t define a Security Officer PIN. The S.O. PIN is like an administrator password – it is used to protect the meta-data on the card including the PKCS#15 structure, in a situation where the person provisioning and issuing the card is not the same as the card’s end-user.

The PUK (Pin Unlock Key) is used to unblock the card if you have locked it due to too many incorrect PIN attempts. Make sure to define one as secure as possible and keep it safe in case you ever forget the PIN. To check that the command ran successfully, we can list the contents of the PKCS#15 structure on the card. This is done with the command:

pkcs15-tool --dump

This should show output something like this:

Using reader with a card: CASTLES EZ100PU 00 00
PKCS#15 Card [OpenSC Card]:
Version        : 1
Serial number  : 0143540243543568
Manufacturer ID: EnterSafe
Last update    : 20100423143625Z
Flags          : EID compliant

PIN [User PIN]
Com. Flags: 0x3
ID        : 01
Flags     : [0x30], initialized, needs-padding
Length    : min_len:4, max_len:16, stored_len:16
Pad char  : 0x00
Reference : 1
Type      : ascii-numeric
Path      : 3f005015

You can see that one PIN has been created, with an ID of 01.

Adding keys

To actually use the card for authentication, there must exist keys for encryption and digital signature on the card. Pairs of RSA public/private keys are the most commonly used form. Both the private and public keys are generated or loaded onto the card. The public key may be read from the card, but the private key may not be read – it stays on the card. The private key can only be used to encrypt / sign data by sending the card the PIN and the data to be signed. By this mechanism, it is ensured that only the person holding the card, and knowing the PIN, can make use of the private key.

Option 1 – Generate a key pair on the card

This is one of the most secure options, as the private key is generated on the card and never leaves it. To generate a 2048bit RSA key pair, use the command:

pkcs15-init -G rsa/2048 -a 01 -u sign,decrypt

The options used here are:

• -G rsa/2048 to generate a 2048-bit RSA keypair.
• -a 01 to protect the key with auth ID 01 (the ID of the PIN you previously defined).
• -u sign,decrypt to allow both signing and decryption with the key.

A 2048-bit key is recommended, however some cards may only support 1024 bit keys. You may be asked for your PIN several times during the process, which could take some time. Once it is over, the output of pkcs15-tool –dump should show a “Private RSA Key” and “Public RSA Key”.

To make use of the key with Mac OS X, it needs to be associated with a X.509 certificate stored on the card. The certificate must be signed with the private key on the card. To accomplish this, we will use OpenSSL with the engine_pkcs11 component from OpenSC to generate a self-signed certificate.

First, start OpenSSL:

$ openssl
OpenSSL>

Now, load the PKCS#11 engine, with the correct PKCS#11 module from OpenSC:

OpenSSL> engine dynamic -pre SO_PATH:/Library/OpenSC/lib/engines/engine_pkcs11.so \
-pre ID:pkcs11 -pre LIST_ADD:1 -pre LOAD -pre MODULE_PATH:/Library/OpenSC/lib/pkcs11/onepin-opensc-pkcs11.so
(dynamic) Dynamic engine loading support
[Success]: SO_PATH:/Library/OpenSC/lib/engines/engine_pkcs11.so
[Success]: ID:pkcs11
[Success]: LIST_ADD:1
[Success]: LOAD
[Success]: MODULE_PATH:/Library/OpenSC/lib/pkcs11/onepin-opensc-pkcs11.so
Loaded: (pkcs11) pkcs11 engine

Now the engine is loaded, tell OpenSSL to generate a self-signed certificate:

OpenSSL> req -engine pkcs11 -new -key id_45 -keyform engine -x509 -out cert.pem -text -days 365

This requests a self-signed certificate, with the private key id_45 (If the private key you generated has a different ID number, shown in pkcs15-tool –dump, use that instead of 45). We also ask for a validity period of 365 days (1 year). You will be asked for the smartcard’s PIN, then some information to put in the certificate such as your locality, name and e-mail address. This information can be left blank if you wish. After entering this information, the certificate will be written to the file cert.pem.

Finally, load the certificate onto the card with the command

pkcs15-init -X cert.pem --auth-id 01 --id 45 --format pem

After this is done, the output of pkcs15-tool –dump should show both the private and public keys, and an X.509 certificate, all with the same ID.

Option 2 – Load a certificate and private key onto the card

This can be more useful if you already have a certificate from a CA, for example the free e-mail signing certs that are issued by instantssl.com, or a certificate issued by your organization. Assuming your certificate and key are packaged in a PKCS#12 format file, use the following command to import them onto the card:

pkcs15-init -S cert.p12 --format PKCS12 --auth-id 01

This will store the cert and private key on the card and associate them together.

Option 3 – Use the PKCS#11 plugin in Firefox to get a certificate from a CA

This method generates the key pair on the card, like option 1, for added security. It then uses the keys to make a certificate signing request with a CA, and when the CA sends back the signed certificate, it installs the certificate on the card. It will only work if the CA uses a web-based issuing process, using the <keygen> element to generate the key in the browser and submit a signing request.

First you need to add the OpenSC PKCS#11 plugin to Firefox. PKCS#11 is a standard for plugins which communicate with security devices and can use the devices to perform encryption-related operations. Firefox can make use of devices with PKCS#11-compatible plugins, and luckily OpenSC provides such a plugin which will work with all types of card supported by OpenSC.

Open the Firefox Preferences, and in the Advanced tab select Encryption. Click “Security Devices” and you should see the following window:

Click “Load” and enter “OpenSC” for the module name. Click Browse for the module filename, and choose:

/Library/OpenSC/lib/onepin-opensc-pkcs11.so

for the path. Click OK and you should see a new OpenSC module in the list, with some slots under it. If your reader and card are plugged in, one of the slots should display your card. If it shows up, you know that PKCS#11 is working OK.

Now click OK on the Device Manager window, and close the Preferences window. Go to the CA’s site (for example InstantSSL / Comodo) and follow their procedures to get a certificate. The CA will first ask your browser to generate a key, at this point Firefox should ask if you want to generate the key using your PKCS#11 device. Select your card and generate the key (you will be prompted for your PIN). The CA will then give you more steps to follow to collect the signed certificate – normally they will send you a link by e-mail after generating it. Visit the link to collect the certificate  using Firefox, with your card and reader plugged in, and Firefox should detect that the certificate is associated with your key on the smartcard, and offer to also install it on the card.

After installing the certificate, it should show up in the “View Certificates” window in the Advanced Encryption preferences in Firefox.

Using the keys and certificates

The guide so far has shown how to install OpenSC and initialise your smartcard, but how do you use the card once all this is done? That will be the subject of the second part of this guide, which will be posted soon.

When I connected it to my Mac in USB drive mode to transfer files, it appeared in the Finder as two storage devices, one for the internal storage and one for the memory stick. When I’d finished transferring files I would click Eject on the memory stick’s device to safely remove it. Then I’d do the same on the internal storage’s device, but this would eventually fail and report an I/O error. The phone’s screen would show that the USB connection had ended, but one of the devices would still show in the Finder. If I then unplugged the USB cable the Finder would tell me that data might have been lost since I didn’t eject the storage device properly.

I eventually found a workaround – go into the Disk Utility app, and Unmount (not Eject) one device, then Eject the other. The order didn’t seem to matter, as the Eject would cause both devices to disappear. However this required me to launch Disk Utility to do the unmounting every time I had to unplug the phone from the Mac.

I started to get fed up of the extra time and clicking involved, so I decided to write a single-function Service to do the unmounting. Check it out here.

Download, unzip and place the plugin in /Library/Address Book Plug-Ins/ and restart Address Book. You should then be able to click on a phone number on a person’s card and select “Send SMS via Bluetooth” to send them a SMS.

The source code is also available, under the same MIT license as the original emitSMS source code.

Notes

The plugin should be compatible with Address Book in Leopard and Snow Leopard.

To use the plugin (or the emitSMS widget, in fact) you need to set up a virtual serial port over Bluetooth to your phone. This will normally be set up automatically by OS X when you pair your phone with your Mac, but the serial ports can be edited in the Bluetooth panel in System Preferences if necessary. (edit: No longer necessary in the latest version, all you need to do is pair your phone with your Mac).

After you select a port to use in the pop-up menu, it will test the port for SMS sending capabilities. The port will only be usable if the test succeeds. Some phones seem to be a little flaky when communicating via Bluetooth and require the test to be run a few times before it can establish a connection successfully. If it fails initially, try clicking on the port again.

If ‘Long Messages’ is not enabled your messages will be limited to 160 characters (or 70 characters if you use symbols outside the standard GSM set, e.g. ^ ). Not all phones support the sending of long messages (actually splitting the message into several SMSs). Additionally, not all phones support requesting delivery receipts.

In general, if your phone works with the emitSMS dashboard widget, it should work with this plugin as the same underlying method is used to send the SMSs.

The aim is to rotate the mirrors () to reflect the laser beam from the source () to blow up all the triggers () and then enter the target (). Rotate the mirrors by tapping on them and then dragging to align the mirror at a particular angle. You start with an amount of energy which is constantly declining (the green bar). Directing the beam into a spike () or reflecting the beam back to the source will cause it to overload (represented by the red bar). If the source is overloaded too much or if you run out of energy, you lose a life. There are also rotating blocks which only allow the beam to pass at a certain angle (), teleports () which work in pairs, and blocks which randomize the beam direction (). In addition, in some levels there are gremlins which roam about the board and mess with your stuff. You can get rid of them by tapping on them repeatedly.

There are a few things I’d like to add to the game, like highscore saving and a level editor, which might appear if I have time to work on it. For now it comes with all the levels from the original game. You can download it here. Any comments, bug reports, etc are welcome!

The binary can be found here, and the modified parts of the source code can be downloaded here. Please let me know if you find any bugs related to using the GDB stub – I’ve tested it a bit and most features seem to work, but this is the first time I’ve worked on the DesMuME code and I may have overlooked something. I take no responsibility for bugs in the unmodified Mac version of DesMuME though

How to use it:

Currently the only method of specifying the debugger ports to use is on the command line. So, open up Terminal.app and run DesMuME from there, like so:

orange:~ sigmaris$ /path/to/DeSmuME.app/Contents/MacOS/DeSmuME -arm9gdb 20000

Note the single dash before the argument. This will start the ARM9 stub listening on port 20000. You can also use -arm7gdb <port> to start the ARM7 stub. You can omit either of the arm9gdb or arm7gdb arguments and it won’t start the respective GDB stubs at all. If startup was successful you should see log messages like this on the console:

2009-04-05 22:32:41.896 DeSmuME[29404:10b] Using ARM9 GDB port 20000

Then go to the DesMuME window, set up a FAT image if necessary, and load your homebrew ROM. You’ll notice it doesn’t start immediately but just shows a white screen. It is waiting for GDB to connect, so go ahead and start it up (I assume you have devkitPRO installed in /usr/local)

orange:~ sigmaris$ /usr/local/devkitPRO/devkitARM/bin/arm-eabi-gdb homebrew.elf

You should point gdb to the compiled ELF file of the homebrew ROM that you loaded earlier. You should see the (gdb) prompt, now tell GDB to connect to the DesMuME stub:

(gdb) target remote :20000
Remote debugging using :20000
0x02000000 in _start ()
(gdb)

If you see the above output, you’re ready to start debugging. For example, set a breakpoint on a function that you use in your homebrew program, and then enter ‘cont’ to tell DesMuME to continue running the program. You should see your program run up to the breakpoint and then stop, and GDB will print a message saying it encountered the breakpoint. You can now examine the state of local variables, print a backtrace, or step line-by-line through your code.

Hopefully this will be useful for some homebrew DS developers on the Mac. Unfortunately, even with the GDB stub in place, DesMuME doesn’t catch many of the errors that would trip you up on a real DS like writes to invalid memory and other similar errors. But being able to jump in anywhere and examine the running state of your code is a step forward from just using tons of iprintf() calls