15370 Barranca Parkway Irvine, CA 92618 USA MAC OS X INTEGRATION GUIDE 2009 HID Global Corporation. All rights reserved. 47A3-904_A.0 C700 March 23, 2009
Crescendo Integration Guide MAC OS X 47A3-904, A.0 Contents About this Guide...3 Purpose...3 Audience...3 1 Introduction...4 1.1 Apple Keychain Services...4 1.2 TokenLounge...4 2 Tested Configurations...5 2.1 TokenLounge version...5 2.2 SafeSign Identity Client version...5 2.3 Operating System...5 2.4 Tokens...5 2.5 Smart Card Readers...5 2.6 Applications...6 3 TokenLounge Functionality...6 3.1 Keychain Access...6 3.2 Safari...7 3.3 Mail...8 3.4 VPN...8 3.5 Logon...9 4 Installation...10 4.1 Installation Process...10 4.2 Verify Installation...14 5 Known Issues...14 List of Figures Figure 1: Tokend packages: SafeSign.tokend...4 Figure 2: Keychain Access: Hardware token inserted...6 Figure 3: Enter the Keychain password: SafeSign IC Token keychain...6 Figure 4: Access Control settings...7 Figure 5: Enter the keychain password: Safari...7 Figure 6: Enter the keychain password: Mail...8 Figure 7: Enter the keychain password: VPN (pppd)...8 Figure 8: TokenLounge...9 Figure 9: TokenLounge: User linked to an identity...9 Figure 10: Install TokenLounge: Welcome to the TokenLounge Installer...10 Figure 11: Install TokenLounge: Software License Agreement...11 Figure 12: Software License Agreement: Agree to the terms...11 Figure 13: Install TokenLounge: Select a Destination...12 Figure 14: Install TokenLounge: Standard Install...12 Figure 15: Install: Authenticate...13 Figure 16: Install TokenLounge: Installation completed successfully...13 Figure 17: Applications: TokenLounge...14 Page 2 of 16 March 23, 2009
47A3-904, A.0 Crescendo Integration Guide MAC OS X About this Guide The information contained in this document is provided AS IS without any warranty. HID GLOBAL HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS WITH REGARD TO THE INFORMATION CONTAINED HEREIN, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON- INFRINGEMENT. IN NO EVENT SHALL HID GLOBAL BE LIABLE, WHETHER IN CONTRACT, TORT OR OTHERWISE FOR ANY INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING FROM USE OF INFORMATION CONTAINED IN THIS DOCUMENT. Windows is a registered trademark of Microsoft Corporation in the United States and other countries Purpose This guide defines the features, supported configurations and installation progress of TokenLounge for MAC OS X 10.4 and 10.5. Audience This manual is specifically designed for users of MAC OS X, who wish to use their HID Crescendo C700 card to obtain strong authentication. March 23, 2009 Page 3 of 16
Crescendo Integration Guide MAC OS X 47A3-904, A.0 1 Introduction 1.1 Apple Keychain Services Keychain Services provides secure storage of passwords, keys, certificates, and notes for one or more users. A user can unlock a keychain with a single password, and any Keychain Services aware application can then use that keychain to store and retrieve passwords. Using Keychain Services is the preferred means to work with hardware tokens on MAC OS X v10.4 and later. In order to do so, MAC OS X v10.4 and later implement the TokenD interface that allows smart card developers to make their cards appear to be key chains. 1.1.1 Use of PKCS #11 The use of PKCS #11 is not in all cases or applications possible, because: Apple does not provide any integration for PKCS#11 based applications. PKCS #11 requires the user to specify a PKCS #11 library to be dynamically loaded for the token in question. For example, in order to be able to use a token supported by SafeSign Identity Client in Mozilla Navigator, you need to install the SafeSign IC PKCS #11 Library as a security device in Mozilla (and for every other application you want to use a SafeSign IC token with). 1.1.2 TokenD TokenD is a component added to the security architecture from MAC OS X 10.4 (Tiger) onwards, to handle hardware tokens. It is used to handle hardware tokens and an OpenDarwin project is available to let anyone define (program) their own TokenD. 1.2 TokenLounge TokenLounge is the TokenD implementation for the MAC OS X Keychain. It can be found (like any other TokenD implementations) in: System/Library/Security/Tokend: Figure 1: Tokend packages: SafeSign.tokend Page 4 of 16 March 23, 2009
47A3-904, A.0 Crescendo Integration Guide MAC OS X 2 Tested Configurations TokenLounge was tested with the SafeSign Identity Client version, smart cards, USB tokens, smart card readers, applications and Macintosh environments listed. Note: TokenLounge is designed to support an extensive range of tokens (for example, those tokens supported by SafeSign Identity Client), only a specific number of token / reader (combinations) have been tested with MAC OS X, as a part of Quality Assurance procedures. 2.1 TokenLounge version The TokenLounge is version number 1.0.1. 2.2 SafeSign Identity Client version TokenLounge has been tested to work with SafeSign Identity Client Standard version 3.0 for MAC OS X. The version numbers of the components installed by SafeSign Identity Client Standard version 3.0 for MAC OS X, release 3.0, are: Description File name File version Java Card Handling Library libaetjcss.dylib 3.0.1737 PKCS #11 Cryptoki Library libaetpkss.dylib 3.0.1737 Token Administration Utility tokenadmin 3.0.0 This information can also be found in the Version Information dialog of the Token Administration Utility. 2.3 Operating System TokenLounge comes in a single installer for the following environments: MAC OS X 10.4 (Tiger) running on PPC/Intel MAC OS X 10.5 (Leopard) running on PPC/Intel 2.4 Tokens TokenLounge supports the following tokens through its integration of SafeSign Identity Client Standard version 3.0 for MAC OS X (PKCS #11 Library): HID Crescendo C700 2.5 Smart Card Readers TokenLounge supports the following smart card readers and USB tokens: OMNIKEY Desktop USB 3121 (using the native CCID MAC OS X driver which is part of the operating system); March 23, 2009 Page 5 of 16
Crescendo Integration Guide MAC OS X 47A3-904, A.0 2.6 Applications TokenLounge supports the following applications: Safari: version 3.2.1 Mail: version 3.5 VPN Logon with a hardware token 3 TokenLounge Functionality TokenLounge allows you to use the hardware tokens supported by SafeSign Identity Client for all applications that make use of the MAC OS X Keychain. The following examples show how TokenLounge works in a number of applications. 3.1 Keychain Access When a token supported by TokenLounge is inserted, it will become available within MAC OS X Keychain Access: Figure 2: Keychain Access: Hardware token inserted In the example above, the hardware token is labelled SafeSign IC Token. When you want to unlock the SafeSign IC Token keychain (if it is locked, as in the picture above), you need to click the lock icon. Upon clicking the lock icon, you will be asked to enter the password for the keychain: Figure 3: Enter the Keychain password: SafeSign IC Token keychain Page 6 of 16 March 23, 2009
47A3-904, A.0 Crescendo Integration Guide MAC OS X When you enter the PIN and click OK, the token will be unlocked. You can specify whether applications can access an item (such as the private key) on the token by clicking on the item and selecting the Access Control tab: Figure 4: Access Control settings By default, all applications are allowed to access this item. If you want to change this setting, you can select Confirm before allowing access and specify which applications are always allowed access. In the same way as you are asked to enter your keychain password here (Figure 3), you will need to do so in the application examples below. 3.2 Safari When using Safari to access a secure web site (that requires client authentication), you will be asked to enter the keychain password, because Safari wants to use your hardware token s keychain: Figure 5: Enter the keychain password: Safari Upon entering the keychain password for your token (as in the picture above) and clicking OK, you will be able to access the secure web site (if you are allowed to do so). March 23, 2009 Page 7 of 16
Crescendo Integration Guide MAC OS X 47A3-904, A.0 3.3 Mail When sending or receiving a signed and/or encrypted message with Mail, you will be asked to enter the keychain password, because Mail wants to use your token: Figure 6: Enter the keychain password: Mail Upon entering the keychain password for your token (as in the picture above), your message will be signed and/or decrypted. 3.4 VPN It is possible to use your token to set up a VPN connection. When connecting to a VPN, you will be asked to enter the keychain password, because VPN wants to use your token: Figure 7: Enter the keychain password: VPN (pppd) Upon entering the keychain password for your token (as in the picture above), the VPN connection will be set up. Page 8 of 16 March 23, 2009
47A3-904, A.0 Crescendo Integration Guide MAC OS X 3.5 Logon You can use your SafeSign IC hardware token to log on to your MAC OS X machine. Note: This type of logon is local (machine) logon, not network logon. In order to do so, you need to link an (your) identity to a user. You can do so by with the TokenLounge application, installed in Applications (see Figure 8). In our example, the identity Mira van Houten s ID will be linked to the user Mira van Houten : Figure 8: TokenLounge Click Link Identity to link the identity to the user. This will result in the following: Figure 9: TokenLounge: User linked to an identity Note: You may have to enter an administrator s password in order to complete the linking. Now you are able to log on with your hardware token to your MAC OS X machine. March 23, 2009 Page 9 of 16
Crescendo Integration Guide MAC OS X 47A3-904, A.0 4 Installation 4.1 Installation Process Note: Users need to have sufficient privileges and basic knowledge of Mac OS X to install TokenLounge for MAC OS X. 1. Save the installation file (TokenLounge.dmg) to a location on your MAC computer and double-click it. This will result in an installer package (TokenLounge.pkg) that can be installed. Click the file to install 2. This will open the Welcome to the AET TokenLounge Installer window, introducing the installer: Figure 10: Install TokenLounge: Welcome to the TokenLounge Installer Click Continue to proceed to the next step of the installation process Note: TokenLounge only runs on MAC OS X 10.4 or greater Page 10 of 16 March 23, 2009
47A3-904, A.0 Crescendo Integration Guide MAC OS X 3. The next window displays the Software License Agreement: Figure 11: Install TokenLounge: Software License Agreement Please read the License Agreement carefully, scrolling down to read the whole text. Click Continue when you have read and understood the License Agreement Note In order to go back to the previous step in the installation process, click Go Back In order to quit the installation process, click the red button in the top left corner of the dialog. 4. Upon clicking Continue, you will be asked to agree to terms of the software license agreement to continue installation: Figure 12: Software License Agreement: Agree to the terms Click Agree when you agree to the terms of the Software License Agreement and wish to continue installing SafeSign. Click Disagree to return to the Software License Agreement window. March 23, 2009 Page 11 of 16
Crescendo Integration Guide MAC OS X 47A3-904, A.0 5. Upon clicking Agree to accept the terms of the Software License Agreement (in Figure 12), you will be asked to select a destination for TokenLounge to be installed. This will allow you to select a destination volume to install the TokenLounge software in. In our example, the destination volume will be the local hard disk (called Macintosh HD ). Figure 13: Install TokenLounge: Select a Destination When you have selected the destination to install TokenLounge in, click Continue 6. Upon clicking Continue to install TokenLounge in the selected volume (Figure 13), the installer is ready to perform a standard installation of the software: Figure 14: Install TokenLounge: Standard Install Click Install to install TokenLounge If you want to change the destination to install TokenLounge inn, click Change Install Location Page 12 of 16 March 23, 2009
47A3-904, A.0 Crescendo Integration Guide MAC OS X 7. Upon clicking Install, you may be asked to authenticate with username and password: Figure 15: Install: Authenticate This may happen if you do not have sufficient privileges (because you need sufficient rights to install the SafeSign software). Enter the name and password of the root (administrator) and click OK to continue 8. Upon clicking OK, TokenLounge will be installed. You will be informed when the installation process is completed: Figure 16: Install TokenLounge: Installation completed successfully Click Close to close the TokenLounge Installer. March 23, 2009 Page 13 of 16
Crescendo Integration Guide MAC OS X 47A3-904, A.0 4.2 Verify Installation When TokenLounge is installed, you can verify that installation is successful by checking for the presence of the TokenLounge application in the Applications folder: Figure 17: Applications: TokenLounge 5 Known Issues 1. No support for File Vault. 2. In MAC OS X 10.4, it is possible change the password/pin for your hardware token in Keychain Access. This functionality is not available in MAC OS X 10.5. 3. There is a problem doing web authentication with Safari when using a Windows 2003 Server running IIS 6.0. You will not be asked for your (token) keychain password. 4. If you have made changes to the content of your token, for example, you deleted a Digital ID through the Token Utility, you will need to remove and reinsert your token, for these changes to be updated in Keychain Access. Page 14 of 16 March 23, 2009
47A3-904, A.0 Crescendo Integration Guide MAC OS X The original version of this guide was written by A.E.T. Europe B.V and this version is based on document ID1. SafeSign is a trademark of A.E.T. Europe B.V. All A.E.T. Europe B.V. product names are trademarks of A.E.T. Europe B.V. All other product and company names are trademarks or registered trademarks of their respective owners. A.E.T. EUROPE B.V. HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS WITH REGARD TO THE INFORMATION CONTAINED HEREIN, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT SHALL A.E.T. EUROPE B.V. BE LIABLE, WHETHER IN CONTRACT, TORT OR OTHERWISE, FOR ANY INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER INCLUDING BUT NOT LIMITED TO DAMAGES RESULTING FROM LOSS OF USE, DATA, PROFITS, REVENUES, OR CUSTOMERS, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF INFORMATION CONTAINED IN THIS DOCUMENT. March 23, 2009 Page 15 of 16
Crescendo Integration Guide MAC OS X 47A3-904, A.0 Page 16 of 16 March 23, 2009