SmartCardServices(7) BSD Miscellaneous Information Manual SmartCardServices(7)
NAME
SmartCardServices -- overview of SmartCard support
DESCRIPTION
SmartCardServices is a set of components for OS X SmartCard support.
Any SmartCard which supports the PIV standard is supported natively by OS X. Access to SmartCard items is possible using the keychain inter-
face. Applications can install additional drivers for SmartCards that are not natively supported.
SmartCard certificates are automatically added to user's keychain when a SmartCard is inserted. SmartCard certificates can be listed with
security using the list-smartcards or export-smartcard commands. Keychain Access GUI cannot be used to manipulate or list these certificates.
SETUP
To associate users with SmartCards, the system can be set up for either fixed key mapping or attribute based mapping. For fixed key use
sc_auth(8) or use the dialog which appears automatically when an unassociated SmartCard is inserted into a reader. This dialog can be glob-
ally suppressed by:
sudo defaults write /Library/Preferences/com.apple.security.smartcard UserPairing -bool NO
Attribute matching can be set up using the appropriate AttributeMapping section in the configuration file as described below. There is no
default configuration. If no AttributeMapping exists or the configuration file is missing, attribute matching is not used. If both fixed key
mapping and attribute mapping are able to associate the inserted SmartCard with a user, attribute mapping takes precedence.
By default certificates do not need to be trusted to allow association. Certificate trust can be globally modified by checkCertificateTrust
setting:
sudo defaults write /Library/Preferences/com.apple.security.smartcard checkCertificateTrust -int <level>
Possible level values are:
0 certificate trust check is turned off
1 certificate trust check is turned on
2 certificate trust check is turned on and revocation check is set to the soft level (unreachable OCSP/CRL means success)
3 certificate trust check is turned on and revocation check is set to the hard level (verified positive response is needed to
succeed)
CONFIGURATION FILE
The world-readable configuration file should be located at /etc/SmartcardLogin.plist and should be in a standard plist format. It may contain
the following optional sections:
UserSelectorPath
This string value points to the custom UserSelector process which is used for associating users with SmartCards. If this section is
not found or the component at that path does not exist, the system UserSelector is used.
TrustedAuthorities
It is possible to specify exact Certificate Authorities which will only be used for trust evaluation of SmartCard certificates. This
is sometimes called Certificate Pinning. Place SHA-256 fingerprints as string values (without spaces) of Certificate Authorities in
an array named TrustedAuthorities. When Certificate Pinning is used, SmartCard certificates issued by a Certificate Authority other
than those on this list won't be evaluated as trusted. Please note that if certificate check setting is turned off, TrustedAuthori-
ties will be ignored.
AttributeMapping
This section is used to set up an optional attribute mapping for the system UserSelector. For each available user record in OpenDi-
rectory, certificate field values are combined into a format string which is then compared to a predefined attribute string. Speci-
fying multiple OpenDirectory attribute strings or using conditional formatting in the format string is not supported. All items in
this section are mandatory.
fields contains an array of string values. This is the list of certificate field names that will be used to compare against the
attribute string. The following field names are supported:
Common Name
RFC 822 Name
NT Principal Name
Organization
OrganizationalUnit:1
OrganizationalUnit:2
OrganizationalUnit:3
Country
formatString contains a string value which specifies how certificate fields will be concatenated. Dollar sign plus number (starting
with 1) is replaced with the field value at the appropriate index.
dsAttributeString contains a string value. This defines the target attributes for the desired OpenDirectory user record. It will be
compared against the generated format strings.
ATTRIBUTE MAPPING CONFIG EXAMPLE
Let's have following sample configuration:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>AttributeMapping</key>
<dict>
<key>fields</key>
<array>
<string>Common Name</string>
<string>RFC 822 Name</string>
</array>
<key>formatString</key>
<string>$2-$1</string>
<key>dsAttributeString</key>
<string>dsAttrTypeNative:longName</string>
</dict>
</dict>
</plist>
Let's also have a certificate that has Common Name with value "John Appleseed" and RFC 822 Name with value "jappleseed@apple.com". For
formatString "$1-$2" the result would be jappleseed@apple.com-John Appleseed and this result would be compared to a dsAttrTypeNative:email
field. When a match is found, the corresponding user is considered associated with the SmartCard.
OFFLINE SMARTCARD LOGIN VIA KERBEROS CACHING
In environments where macOS clients may not always be able to reach Directory Servers, cached SmartCard login support is possible via Ker-
beros caching. This configuration allows users with network accounts to authenticate via SmartCard when operating outside the enterprise
environment. Note: Initial account setup requires machine binding and access to the directory server.
Mapping example
The following example SmartcardLogin.plist file matches the Subject Alternative Name type, NT Principal Name, in the identity on the Smart-
Card against the Directory Server's altSecurityIdentities field (Kerberos), allowing for offline login and authentication:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>AttributeMapping</key>
<dict>
<key>fields</key>
<array>
<string>NT Principal Name</string>
</array>
<key>formatString</key>
<string>Kerberos:$1</string>
<key>dsAttributeString</key>
<string>dsAttrTypeStandard:AltSecurityIdentities</string>
</dict>
</dict>
</plist>
Additional considerations
Certificate Checking: checkCertificateTrust should not be set to 3 (hard revocation check) if certificate revocation or OCSP servers are not
always available to the client machines.
User accounts should be created setting the "Create Mobile User on Login" flag in the Directory Utility application, when binding client
machines via the command line, or with a Configuration Profile. When used in conjunction with Kerberos Caching, a mobile user account will
allow users to authenticate either online and offline.
EXTENSION
Extensions can be created using the Xcode SmartCard Token Extension template.
To enable the app extension and make the token available to the system for authentication, you launch the sc_auth command line tool with
value of ''com.apple.ctk.class-id' from Info.plist:
sudo sc_auth enable_for_login -t com.example.HostApp.TokenExtension
SYSTEM REPORT
It is possible to show the current status of SmartCardServices by command:
system_profiler SPSmartCardsDataType
USB SMART CARD READER DRIVERS
OS X has built-in support for USB CCID class-compliant SmartCard readers. For other readers, install the reader driver in
/usr/local/libexec/SmartCardServices/drivers. Each driver is a bundle. The bundle contains an XML file Info.plist which contains the
device's USB vendor ID and product ID. For detailed description of the plist format and how to write a reader driver, see
http://pcsclite.alioth.debian.org/api/group__IFDHandler.html
SMART CARD APDU LOGGING
It is possible to turn on logging for SmartCards by setting the global preference:
sudo defaults write /Library/Preferences/com.apple.security.smartcard Logging -bool yes
After a SmartCard reader is connected (or after reboot) all operations including contents of sent and received APDU messages are logged into
the system log. Logging uses the subsystem com.apple.CryptoTokenKit and category APDULog so it is possible to set up logging with a predicate
(see log(1) ). Example:
log show --predicate '(subsystem == "com.apple.CryptoTokenKit") && (category == "APDULog")'
To avoid security risks that could occur if logging is turned on indefinitely, the logging setting is one-shot - it must be turned on by the
command above to start logging again with a new reader. This includes unplugging and replugging the same reader.
ENTITLEMENT
Sandboxed PCSC clients require 'com.apple.security.smartcard=YES' entitlement. Non-sandboxed PCSC clients do not require such entitlement (in
order to keep backward compatibility with macOS < 10.10). Users of TKSmartCard* API from CryptoTokenKit.framework always require that enti-
tlement no matter whether they are sandboxed or not.
SEE ALSO
SmartCardServices-legacy(7), sc_auth(8), defaults(1), log(1), ssh-keychain(8), pam_smartcard(8), security(1), UserSelector(7)
Mac OS X May 12, 2016 Mac OS X