HWToken Drivers

HWToken Library documentation

Client configuration is platform independent but HWToken libraries are platform specific – see Platforms list for each library. Please, be aware – KeyShield client HW Token library is not an operating system device driver. It is an abstraction layer to allow to work with all the different readers and tokens in a unified way. This also improves security – once Authentec library is chosen for example, no other device can be used to provide the token ID.

Library parameters:

Each library supports 3 token ID format modes. Format mode is activated by adding format=keyword to the Library Parameters field within the client configuration form: format=hex – token ID is converted to uppercase hexadecimal representation (e.g. 000000000079AF72). This is the default format for all drivers. format=estellar – this encoding is compatible with token ID encoding used by Czech provider of attendance system. Estellar setting generates token ID strings identical to the IDs of the attendance system which allows to share issued tokens list by both systems. format=raw – the token ID is provided exactly as read by the reader. No further cutting, padding nor formatting is applied. encryption=bcrypt – the token ID is hashed (irreversibly converted) when passed to KeyShield SSO client in order to protected real ID of user tokens against unauthorized use or access. See Encryption for more details basic – All advanced drivers can be switched to basic mode. Token presence in the vicinity of the reader and token being put away are not detected. The reader works in the exactly same way like the Authentec family readers

Authentec family readers

HW Token Library: dev_authentec Platforms: Windows basic class – it sends token ID only once when the token is detected. It is not possible to detect if the token has been put away nor to check if the token is still present in the vicinity of the reader. Authentec family of readers is originally designed as a HW emulator of keyboard. Authentec KeyShield driver is provided and licensed to allow dev_authentec library to read token ID via WINUSB API and to avoid any keystrokes being generated. Please contact your reseller for more information about supported readers. Both 125kHz and 13,6MHz versions are available. Downloads: 125 kHz reader: Authentec driver 13,6 MHz reader: TDPfire driver Please note: the reader is automatically detected as a keyboard (there is one keyboard listed more in the keyboard devices list). The driver must be installed in order to avoid this – the reader is listed as a generic USB device after the successful installation of the driver.

pcProx readers

HW Token Library: dev_pcprox Platforms: Windows Driver for pcProx readers uses pcProx SDK – it doesn’t need any OS driver installation and it works with most pcProx readers 125Khz RFID, 13.56MHz DESFIRE/MIFARE and dual readers. advanced class – it sends token ID when the token is detected. It also detects if the token has been put away and it allows to check if the token is still present in the vicinity of the reader. This allows full control of locking/unlocking – KeyShield client locks the workstation when the token is put away of the reader. tested with: pcProx® Plus RDR-80581AKU – dual reader pcProx® RDR-7581AKU – 13.56MHz MIFARE reader pcProx® RDR-6E82AKU – 125Khz RFID reader use pcproxcfg configuration utility and configuration files to configure reader to work correctly with KeyShield SSO pcproxcfg package and pcProx configuration utility

SCARD API Contact & contactless readers, Gemalto Gemplus reader

HW Token Library: dev_scard Platforms: Windows Driver for contact and contactless 13.56MHz readers using windows SCARD API advanced/active class – uses windows SCARD API to detect card present/removed events and read card ID using PC/SC specific APDU FF CA 00 00 00 which should work for most contactless MIFARE cards Contactless smart cards will work with any contactless reader as the communication protocol is standardized. Contact smart cards should work with most smart card readers as the main differences are inside the cards. Cards differ by chip used and applications loaded on the chip. Cards from different manufacturers support different commands and steps to read the card ID/serial number are not standardized across all cards. For example Gemalto Gemplus (contact) smart card (AID A000000018434D00) – should work with most smart card readers tested with HP USB SmartCard CCID Keyboard Model No. KUS1206, Dell Smart Card Reader Keyboard Model No. SK3106, OmniKey 5321 reader Note: SCARD API is only general interface for communication with reader device. It is sending commands and receiving responses from reader or driver. Communication protocol differs depending on the card used and/or applications running on the card. For some classes of cards such as MIFARE it’s possible to use a single command to read card unique ID, but for most contact cards commands are different for each manufacturer. Library parameters: aid=a000000151000000,a000000018434d00 – comma separated list of Application Identifiers (AID) that are used with contact smart card. AIDs are selected in order provided when trying to read card ID. Some readers don’t require AID to be selected explicitly when the default Application support reading card ID. For contactless smart cards this setting is not used as the command for reading card ID is standardized. You can use scard_scan utility to detect AIDs available on a given type of smart card. Default AIDs are: a000000151000000 … crypto manager AID a000000018434d00 … Gemplus security domain AID

Gigatek Promag PCR300* reader

HW Token Library: dev_serial Platforms: Windows Driver for Gigatek Promag PCR300A (125Khz RFID) may also work with Promag PCR300M (13.56MHz MIFARE) advanced/passive class – doesn’t support card presence detection, it sends the id only once when the card is detected. It supports card put away detection.

Silicon Labs CP210x (Cygnal integrated)

HW Token Library: dev_oksmart3 Platforms: Windows basic reader class – it sends token ID only once when the token is detected. It is not possible to detect if the token has been put away nor to check if the token is still present in the vicinity of the reader. Use Windows Driver for Silicon Labs CP2010x, if it’s not recognized by Windows automatically. Library parameters: port=Silicon – must be set to make the reader work properly

Reader simulator (for testing)

HW Token Library: dev_test Reader simulator is used for testing hwtoken function without real card/token reader. Will read dev_test.cfg from the same directory where dev_test.dll is located (KeyShield SSO client installation directory). dev_test.cfg is a simple text file containing usernames for four simulated users – each username on a separate line. When initialized, dev_test creates a dialog box with four buttons with card id/username (depending on contents of dev_test.cfg) and Remove button for simulating card removal. Pressing user 1-4 button will simulate card Card IDs for users 1 – 4 are fixed 00FC9C3141100000, 00FC9B4152200000, 00FC9D5163300000 and 00FC9E7744400000. example dev_test.cfg Library parameters: basic – turns off card remove events for basic reader (such as Authentec RFID) emulation minimized – show the dialog minimized

Encryption

KeyShield LDAP connector allows you to define 2 multi value attributes for keeping Permanent and Temporary token IDs. KeyShield allows to assign virtually unlimited number of tokens resp. token IDs for each user. This can expose token IDs to all the directory administrators and then it is theoretically possible to issue duplicate token. KeyShield offers unique protection mechanism to avoid this risk – token ID is encrypted (hashed) on the KeyShield client side once it is read by the reader. Because of the algorithm used, b-crypt, it is not then possible to find the original chip ID. We also provide a comfortable conversion utility which allows to hash already stored IDs or to hash_and_import a csv file with a list of users and their tokens Work factor and salt parameters influence how the hashed number is generated. Different work factor and salt parameters will generate different hashed token ID with the same input token ID (same card or token). Attention – because of this, you must configure salt and work factor parameters only once and not change them later. Changing the salt or work factor will change hashed token IDs sent by the client and they won’t match token IDs stored in LDAP. The salt parameter should be unique to your installation. You can use for example online service at https://www.random.org/bytes/ to generate 16 truly random bytes (just remove the spaces between bytes). Salt serves as another layer of protection, it ensures that hashed IDs are unique to your KeyShield SSO installation. Default work factor was carefully chosen as a compromise between good security and hashing speed. You should test the client with default work factor on slowest workstation/notebook you have and only if the delay between presenting a token and authentication is too long you should try to lower the work factor number. Library parameters: encryption=bcrypt – used hash algorithm see https://en.wikipedia.org/wiki/Bcrypt salt= – (optional) Salt must be a 16-bit hexadecimal number without spaces and colons (eg. 79f6bc73a8d8a06198e472a0f70f0f52).If it’s not specified, default salt will be used. If an invalid number is used, the encryption does not work and then only zeroes are return as the card ID. (eg.: format=raw encryption=bcrypt salt=aaBBccDd00110011aaBBccDd00110011) workfactor= – (optional) (optional) Number between 1-30. Work factor (security factor), allows you to determine how expensive the hash function will be. Work factor value determines how slow the hash function will be, means different work factor will generate different hash values in a different time span. If it’s not specified, default work factor 12 will be used. The default is fast enough to not be noticed and will still be strong enough. Using a high work factor makes it incredibly difficult to execute a brute-force attack, but can put unnecessary load on the system. (eg.: format=estellar encryption=bcrypt salt=79f6bc73a8d8a06198e472a0f70f0f52 workfactor=12)