Unknown option: "-7"
Unix manual page for SmartCardServices. (host=minya system=Darwin)
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:
<?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 asso-
ciated 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 environ-
ment. 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 (Ker-
beros), 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 con-
junction 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 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), UserSelector(7)
Mac OS X May 12, 2016 Mac OS X