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 interface.
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 unasso-
ciated SmartCard is inserted into a reader. This dialog can be globally
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 set-
ting:
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 suc-
cess)
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.
AttributeMapping
This section is used to set up an optional attribute mapping for
the system UserSelector. For each available user record in
OpenDirectory, certificate field values are combined into a for-
mat string which is then compared to a predefined attribute
string. Specifying multiple OpenDirectory attribute strings or
using conditional formatting in the format string is not sup-
ported. 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 cer-
tificate fields will be concatenated. Dollar sign plus number
(starting with 1) is replaced with the field value at the appro-
priate index.
dsAttributeString contains a string value. This defines the tar-
get 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:
<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>
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 asso-
ciated with the SmartCard.
EXTENSION
Extensions can be created using the Xcode SmartCard Token Extension tem-
plate.
SYSTEM REPORT
It is possible to show the current status of SmartCardServices by com-
mand:
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 for-
mat 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 cate-
gory 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 indefi-
nitely, 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' enti-
tlement. Non-sandboxed PCSC clients do not require such entitlement (in
order to keep backward compatibility with macOS < 10.10). Users of TKS-
martCard* API from CryptoTokenKit.framework always require that entitle-
ment 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)
Mac OS X May 12, 2016 Mac OS X
Mac OS X 10.13.1 - Generated Thu Nov 9 15:54:45 CST 2017