Introduction

The Truststore is an add-on to the Trust1Connector that enables you to use PKCS#11 smart cards for authentication and signing. The Truststore is available as of version 3.8. By default it is NOT enabled.

Important difference between Modules and the Truststore

There is an important difference between a smart card that is read via the Truststore or directly via the Trust1Connector. Smart Cards that are implemented in the Trust1Connector are called Modules. A Module will return ALL information and certificates available on the Smart Card to the consuming application. The Truststore only reads the certificates of the Smart Card and can therefor only be used in authentication and signing use cases.

High Level Technical Introduction

The Truststore module for the Trust1Connector interfaces with the respective Certificate Manager and KeyChain of Windows and Mac OS.

The store (used further as a shorthand for Truststore) implements the following use cases:

• detecting the certificates in the personal certificate store which can be used for authentication and signing

• X509 parsing of the certificates, and exposing the certificates through the T1C

• resolving the supported signature algorithms which can be used for the selected certificate

• validates the hash received from the consuming application

• signs a digest received from the consuming application

• authenticates the user through a PIN verification flow

• authenticates the user by signing a digest using the authentication certificate

Prerequisites

1. The vendor specific driver is considered installed on OS level.

This means that the smart card will be detected by the Operating System in the context of the certificate manager of keychain.

When the requirement to access smart cards WITHOUT installation of the vendor specific driver is applied, the specific smart card MUST be implemented in a separate Module, or the driver library MUST be localized throughout the PKCS11 module of the T1C.

In the former case, the smart card communication and model is implemented in a separate T1C Module.

In the latter, we require the driver is located somewhere on the OS (from T1C v3.5) or can be shipped/provisioned through the Distribution Server (from DSv4).

2. The smart card driver supports the PKCS#11 standard for Public Key Cryptography API

Vendors provide smart cards and smart card readers. Each smart card must have a Cryptographic Service Provider (CSP) that uses the CryptoAPI interfaces to enable cryptographic operations and the WinSCard APIs to enable communications with smart card hardware.. For the Truststore this MUST be the PKCS#11 API.

Windows Certificate Manager

The following diagram shows the Cryptography architecture that is used by the Windows operating system. The implementation uses CNG (Crypto Next Generation - NCrypt.dll) to interact natively with the underlying system.

scource: Smart Card Architecture

Card behaviour in Windows

The implementation uses CNG (Crypto Next Generation - NCrypt.dll) to interact natively with the underlying system

Mac OSX Keychain

According to Mac the Keychain is the best place to store small secrets like cryptographic keys. So that is why we are using it. The implementation uses CryptoTokenKit to interact natively with the underlying system.

Card behaviour in Mac OSX

Card behaviour in Mac OSX is different from Windows. When a user physically inserts a smart card or token into a USB slot or card reader—the CryptoTokenKit framework exposes the token’s items to your app as standard keychain items. It does this by copying the items to the keychain when the token is inserted, and deleting them from the keychain when the token is removed.

source: using cryptographic assets

How to verify if a Smart Card is available for your OS?

This is quite simple. After installing the driver for the card, insert the card in a card reader connected to or a USB-slot of your computer.

MAC OS

When the framework copies an item from a token to the keychain, it records the associated token’s identifier, or token ID, as part of the keychain item. If you know the token ID, you can use it to very precisely filter the keychain search. Do this by including the kSecAttrTokenID key in the query dictionary. For example, to get a reference to a key that comes from a token with token ID com.example.piv:0123456789, use the search query:

let getquery: [String: Any] = [kSecClass as String: kSecClassKey,
                               kSecAttrTokenID as String: "com.example.piv:0123456789",
                               kSecReturnRef as String: true]

To identify token IDs that are currently available in the system, use an instance of the TKTokenWatcher class. This object has a tokenIDs property that’s a list of all the token IDs present in the system. You can read this at any time:

let watcher = TKTokenWatcher()
print("The following token IDs are present in the system:")
for tokenID in watcher.tokenIDs {
    print(tokenID)
}

Windows