manpagez: man pages & more
man SmartCardServices(7)
Home | html | info | man

SmartCardServices(7) BSD Miscellaneous Information Manual SmartCardServices(7)


     SmartCardServices -- overview of SmartCard support


     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.


     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/ 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-

           sudo defaults write /Library/Preferences/ 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-

     3             certificate trust check is turned on and revocation check
                   is set to the hard level (verified positive response is
                   needed to succeed)


     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:

              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.

              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

              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.


     Let's have following sample configuration:
               <string>Common Name</string>
               <string>RFC 822 Name</string>

     Let's also have a certificate that has Common Name with value "John
     Appleseed" and RFC 822 Name with value "". For
     formatString "$1-$2" the result would be
     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.


     Extensions can be created using the Xcode SmartCard Token Extension tem-


     It is possible to show the current status of SmartCardServices by com-

           system_profiler SPSmartCardsDataType


     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


     It is possible to turn on logging for SmartCards by setting the global

           sudo defaults write /Library/Preferences/ 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 and cate-
     gory APDULog so it is possible to set up logging with a predicate (see
     log(1) ). Example:

           log show --predicate '(subsystem == "") && (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.


     Sandboxed PCSC clients require '' 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.


     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
© 2000-2020
Individual documents may contain additional copyright information.