Mac OS X 10.4: Enabling smart card login

This article has been archived and is no longer updated by Apple.

Mac OS X 10.4 Tiger greatly enhances integration for smart cards, as described in this advanced article. The configuration required is much simpler than in previous Mac OS X versions.

Important: The format of the configuration file and the scripts used to configure smart card login have changed from Mac OS X 10.3.x. Do not copy or use these files directly from a previous version of Mac OS X, or it may make the system unusable. It is no longer necessary to manually run pcscd, as this daemon is started automatically by Mac OS X when it detects a smart card reader.

It is safe to install a successfully modified /etc/authorization to enable smart card login on any client system, even those without smart card readers. If no reader or card is present, the user will continue to see the default login window, and there will be no performance impact.

To support login with a smart card on Mac OS X 10.4, the card must support signing with a public key. In addition, the card itself must have a plugin, known as a tokend, that can communicate with securityd and the card itself.

Tokends installed with Mac OS X 10.4

There are three tokends installed as part of the base Mac OS X installation.

"CAC"  US Federal Government:
CAC: Common Access Card
GSC-IS: Government Smart Card Interoperability Specification v2.1
"BELPIC"Belgian Personal Identity Card
"JPKI"Japanese Public Key Infrastructure card

Smart cards that are not compliant with the specifications listed above would require a supporting tokend be installed for the smart card to be recognized and available to applications.

Enabling smart card login

Enabling smart card login is controlled through entries in the /etc/authorization file. Perform the following steps in Terminal to modify the authorization file.

  1. Execute this command: sudo -s
  2. Execute this command: cd /etc
  3. Execute this command: cp authorization authorization.orig
  4. Execute this command: cp authorization /tmp/authorization.mod
    Don't quit Terminal.
  5. Next, edit the "/tmp/authorization.mod" file in pico, or your favorite text editor, or the plist editor that comes with the Apple Developer Kit.
  6. Make the following changes to the"mechanisms" Array inside the "system.login.console" rights:

    • After the string "<string>builtin:auto-login,privileged</string>" add the string "<string>builtin:smartcard-sniffer,privileged</string>"

    • After the string "<string>builtin:reset-password,privileged</string>" remove the string "<string>authinternal</string>" then add string "<string>builtin:authenticate,privileged</string>"

  7. Make the following changes to the "mechanisms" Array inside the "authenticate" rules:

    • add the following string to the beginning of the array "<string>builtin:smartcard-sniffer,privileged</string>"

    • after the string "<string>builtin:authenticate</string>" remove the string "<string>authinternal</string>" then add the string "<string>builtin:authenticate,privileged</string>"

  8. After saving the changes, go back to Terminal and execute the following command (while still in the sudo -s session):

    cp /tmp/authorization.mod /etc/authorization

This final step will replace the system's active authorization file with your edited version. These changes take place immediately so you do not need to restart.

Smart cards and Directory Services

Part of the login process is to do a lookup for the expected user in a directory service such as Open Directory, LDAP, or Active Directory. The first and recommended method to link a smart card user with a record in a directory service is to add the hash of the public key to the user's directory record. This is the most convenient and most secure way of identifying a smart card user.  The second method is to lookup the user based on values drawn from the email signing certificate as required for the US Federal Government smart card use.

A script is preinstalled to assist you in binding a smart card to a user's local directory domain record. This is /usr/sbin/sc_auth:

myhostname#  /usr/sbin/sc_auth -h   
Usage:  sc_auth accept [-v] [-u user] [-k keyname] # by key on inserted card(s)
        sc_auth accept [-v] [-u user] -h hash # by known pubkey hash
        sc_auth remove [-v] [-u user] # remove all public keys for this user
        sc_auth hash [-k keyname] # print hashes for keys on inserted card(s)

An example of the output from this for a US Department of Defense Common Access Card is:

myhostname% sc_auth hash
01C2F20D8964BE7701B57B63B0A1795B8F2604C1 Identity Private Key
443F30C356E676F447CD4DA89F46CC0CCED19737 Email Signing Private Key
4845564C1F8C6B378C19B8F262CE422933CF1FD1 Email Encryption Private Key

To add a user to the local directory

myhostname% sudo sc_auth accept -u myuser -h 01C2F20D8964BE7701B57B63B0A1795B8F2604C1

...where "01C2F20D8964BE7701B57B63B0A1795B8F2604C1" is the hash for the key associated with the Identity Private Key.  Refer to the script for further usage instructions. You will need to run this as a user authorized to modify the directory.  In this example, any of the hash entries listed could have been used for associating the card to the account.  If desired, more than one smart card can be associated with a single user account by running the script again with the hash from the additional card(s).

The script adds a field to the user's authentication_authority property. For example, after executing the command above, the authentication_authority property for the user looks like:

myhostname% dscl . -read /Users/myuser
    "authentication_authority" = ( ";ShadowHash;", ";pubkeyhash;         01C2F20D8964BE7701B57B63B0A1795B8F2604C1" );

One can immediately log in to a new session using the smart card.

Smart card login uses Open Directory for all of its user lookups, so any supported directory structure will function properly.

Other Directory schema

The method used by sc_auth described above is the recommended way to link a user to their directory entry. However, some sites use an alternative lookup method or are unable to modify their schema for various reasons. To address this, there is a way to configure the smart card authorization plugin to use an attribute mapping method which maps various attributes from a certificate on the smart card to a different field in the directory. This is primarily provided to support the Common Access Card, although it does work with similarly designed smart cards.

The configuration file is an array of dictionaries. Each dictionary in this array represents the data needed to determine one search key in an Open Directory search. If no configuration file is present, the built in method of using the public key hash will be used. The file is at /etc/cacloginconfig.plist .

            <string>NT Principal Name</string>

This might produce a search string key (dsAttributeString) of "0123456789@mil".  Note that the token after "dsAttrTypeNative:" would be the actual name of the attribute to use in your directory schema.
            <string>RFC 822 Name</string>
            <string>NT Principal Name</string>

This might produce a search string of "":

There was a similar, but more complicated way of doing this in Mac OS X 10.3. To support the improved integration of smart cards, some unused functionality was removed, providing a much simpler configuration.

The only fields that may appear in the "fields" section of the file are

    Key String    Example

    Country    US
    Organization    U.S. Government
    Organizational Unit:1    DoD
    Organizational Unit:2    PKI
    Organizational Unit:3    USN
    Common Name    SURNAME.GIVEN.MI.1160048910
    RFC 822 Name
    NT Principal Name    1160048910@mil

These will be extracted from the e-mail signing certificate. Spaces and capitalization are significant. "Organizational Unit:1" refers to the top level OU and will typically be "DoD".  "Organizational Unit:3" refers to the bottom level OU and may be for example "USN".

Example of /var/log/secure.log:

May 26 22:55:11 envy SecurityAgent[3900]: Showing Login Window
May 26 22:55:25 envy Token reader SchlumbergerSema eGate 0 0 inserted into system
May 26 22:55:25 envy token inserted into reader SchlumbergerSema eGate 0 0
May 26 22:55:32 envy reader SchlumbergerSema eGate 0 0 inserted token "[User Key]               " ([User Key]              ) subservice 37 using driver

(This is where the PIN prompt login window appears.)

May 26 22:55:32 envy SecurityAgent[3900]: Showing Login Window
May 26 22:55:36 envy SecurityAgent[3900]: User Authenticated: continue login process
May 26 22:55:44 envy Succeeded authorizing right system.login.console by process /System/Library/CoreServices/ for authorization created by /System/Library/CoreServices/
May 26 22:55:44 envy Succeeded authorizing right system.login.done by process /System/Library/CoreServices/ for authorization created by /System/Library/CoreServices/

A good method for validating that the Smart Card is being recognized by the system is that the smart card appears in the Keychains list.  When selecting the keychain in the list all certificates and keys appear within the Keychain Access window.

Published Date: Feb 20, 2012