CryptoTokenKit is Apple's take on programmatic access to smart cards and other tokens. It provides both low level access to tokens (comparable with PC/SC) and high level access for system wide integration of a token (comparable with Windows Smart Card Minidriver).
For further information about CryptoTokenKit please read the following ressources:
man 8 security
man 8 sc_auth
man 8 SmartCardServices
- Use Mandatory Smart Card Authentication
- Working with Smart Cards: macOS and Security
OpenSCToken aims at providing the existing functionality of OpenSC through CryptoTokenKit.
- Download the latest release of OpenSCToken
- Open the image (
.dmg
file) and drag OpenSCTokenApp to your Applications - Launching OpenSCTokenApp shows an empty application and registers the token driver.
Now your're ready to use the smart card even if the application is not running (as long as your card is supported by OpenSC).
- Show location of the registered OpenSCToken
pluginkit -v -m -D -i org.opensc-project.mac.opensctoken.OpenSCTokenApp.OpenSCToken
- List available smart cards and paired/unpaired identities:
sc_auth identities
- Pair a smart card with your account:
sc_auth pair ${HASH}
- Remove paired smart card from your account:
sc_auth unpair ${HASH}
- Disable dialog for pairing a smart card with the current account:
sc_auth pairing_ui -s disable
- Disable macOS' built-in token driver for the PIV card (Yubikey) to use use OpenSC instead:
sudo defaults write /Library/Preferences/com.apple.security.smartcard DisabledTokens -array com.apple.CryptoTokenKit.pivtoken
- Unregister OpenSCToken
pluginkit -r -i org.opensc-project.mac.opensctoken.OpenSCTokenApp.OpenSCToken
Comparison with OpenSC.tokend
- OpenSCToken supports multiple certificates, keys and PINs
- OpenSCToken has propper support for PIN pad on reader or token
- OpenSCToken offers easy login with smart card and automatically unlocks the login keychain
- Tokens are not visible in Keychain Access anymore (use
sc_auth
/security
from command line instead) - Many non-Apple applications do not yet support CryptoTokenKit. If OpenSCToken is used together with OpenSC.tokend, your token will appear twice in Safari and other Apple-apps.
Requirements:
- Xcode 8.0 or later; macOS 10.12 SDK or later
- help2man, gengetopt
- Code signing credentials
# Install dependencies
brew install help2man
brew install gengetopt
# Checkout OpenSCToken
git clone http://github.com/frankmorgner/OpenSCToken.git
# Checkout and build all dependencies (i.e. OpenSSL, OpenPACE and OpenSC)
cd OpenSCToken
./bootstrap
# Now build OpenSCTokenApp
xcodebuild -target OpenSCTokenApp -configuration Release -project OpenSCTokenApp.xcodeproj install DSTROOT=${PWD}/build
Once all dependencies are built, the project can be executed and debugged from Xcode. Running the application, adds OpenSCToken to the system's plug-in registry. After insterting a token, attach to the process OpenSCToken
for debugging with Xcode.
OpenSCToken requires macOS 10.12 or later. For registering the token driver, you have two options:
-
Run OpenSCTokenApp or execute
pluginkit -a /Applications/Utilities/OpenSCTokenApp.app/Contents/PlugIns/OpenSCToken.appex
: Registers OpenSC in the PlugInKit subsystem for the current user. Your token will be available after login. Note that database clean-ups may eventually remove the plug-in. -
Run OpenSCTokenApp as SecurityAgent
sudo -u _securityagent /Applications/Utilities/OpenSCTokenApp.app/Contents/MacOS/OpenSCTokenApp
or executesudo -u _securityagent pluginkit -a /Applications/Utilities/OpenSCTokenApp.app/Contents/PlugIns/OpenSCToken.appex
: Registers OpenSC globally. Your token will always be available.
OpenSCToken supports all configuration options from OpenSC. However, you need to make sure that files to be read or written are available from the token driver's sandbox.
For example, opensc.conf
, which is read by OpenSC, is available in /Applications/Utilities/OpenSCTokenApp.app/Contents/PlugIns/OpenSCToken.appex/Contents/Resources
. When using configuration options that need to write a file (e.g. debug_file
or file_cache_dir
), you need to make sure this is done in the token driver's Documents
directory (e.g. something like ~/Library/Containers/org.opensc-project.mac.opensctoken.OpenSCTokenApp.OpenSCToken/Data/Documents
). For your convenience, these locations are written to the system log when OpenSCToken is started with a smart card. Use the following commands to view the log:
sudo log config --mode "private_data:on"
log stream --predicate 'senderImagePath contains[cd] "OpenSCToken"'
Tested applications:
- Login to macOS with smart card
- Unlock login keychain
- Safari, Chrome (TLS client authentication)
Tested Mechanisms:
-
kSecKeyAlgorithmRSASignatureRaw
-
kSecKeyAlgorithmRSASignatureDigestPKCS1v15SHA1
-
kSecKeyAlgorithmRSASignatureDigestPKCS1v15SHA224
-
kSecKeyAlgorithmRSASignatureDigestPKCS1v15SHA256
-
kSecKeyAlgorithmRSASignatureDigestPKCS1v15SHA384
-
kSecKeyAlgorithmRSASignatureDigestPKCS1v15SHA512
-
kSecKeyAlgorithmECDSASignatureDigestX962SHA1
-
kSecKeyAlgorithmECDSASignatureMessageX962SHA224
-
kSecKeyAlgorithmECDSASignatureDigestX962SHA256
-
kSecKeyAlgorithmECDSASignatureDigestX962SHA384
-
kSecKeyAlgorithmECDSASignatureDigestX962SHA512
-
kSecKeyAlgorithmRSAEncryptionRaw
-
kSecKeyAlgorithmRSAEncryptionPKCS1
The unchecked mechanisms are implemented, but currently untested.
Copyright (C) 2017-2019 Frank Morgner frankmorgner@gmail.com