Card API

Overview

Card type

The supported cards can be categorized into several types.

Type Cards
CSN EM, Mifare, Felica
Wiegand HID Prox, HID iClass
Smartcard Mifare, Mifare DESFire, iClass, iClass SEOS

Refer to the article for more detailed information.

enum Type {
  CARD_TYPE_UNKNOWN = 0x00;
  CARD_TYPE_CSN	= 0x01;
  CARD_TYPE_SECURE = 0x02;
  CARD_TYPE_ACCESS = 0x03;
  CARD_TYPE_QR = 0x06;
  CARD_TYPE_WIEGAND = 0x0A;    
}
CARD_TYPE_CSN
The CSN(Card Serial Number) is an ID written into a card by manufacturer. You cannot change it.
CARD_TYPE_SECURE
With a smartcard, you can write data into it. CARD_TYPE_SECURE cards store user credential information which is used for authentication process. Since access group information is not stored in the cards, the device still needs to store user information.
CARD_TYPE_ACCESS
CARD_TYPE_ACCESS cards stores access group information of users in addition to their credentials. Since all the information for authentication is on a card, the device does not need to store any user information.
CARD_TYPE_QR
X-Station 2 supports QR codes as credentials. See WriteQRCode and QRConfig.
CARD_TYPE_WIEGAND
For Wiegand cards, you have to configure the format to decode the data. See the article for details.

Card data

message CardData {
  Type type;
  CSNCardData CSNCardData; // null if it is a smartcard
  SmartCardData smartCardData; // null if it is a CSN card
}
type
CSNCardData
Valid only with CARD_TYPE_CSN or CARD_TYPE_QR.
smartCardData
Valid only with CARD_TYPE_SECURE or CARD_TYPE_ACCESS.
message CSNCardData {
  Type type;
  int32 size;
  bytes data;
}
type
size
The value is always 32. Note that you cannot write a CSNCard.
data
If the type is CARD_TYPE_SECURE, it consists of 24 byte card ID, 4 byte issue count, and 4 byte timestamp.
message SmartCardData {
  SmartCardHeader header;
  bytes cardID;
  SmartCardCredential credential;
  AccessOnCardData accessOnData;
}
header
cardID
32 byte for CARD_TYPE_ACCESS and 24 byte for CARD_TYPE_SECURE
credential
accessOnData
Valid only with CARD_TYPE_ACCESS cards.
message SmartCardHeader {
  uint32 headerCRC;
  uint32 cardCRC;
  Type type;
  uint32 numOfTemplate;
  uint32 templateSize;
  uint32 issueCount;
  uint32 duressMask;
}
headerCRC/cardCRC
They are calculated automatically in Write. So, you don’t have to fill these values when writing.
type
CARD_TYPE_SECURE or CARD_TYPE_ACCESS
numOfTemplate
The number of fingerprint templates stored in the card. Maximum 4 templates can be stored on a card.
templateSize
The size of fingerprint template in bytes.
issueCount
You can issue a card multiple times. In this case, you can differentiate each issue by this parameter.
duressMask
Specify whether any of the fingerprint templates is of a duress finger. For example, if the first template is of a duress finger, it should be 0x01.
message SmartCardCredential {
  bytes PIN;
  repeated bytes templates;
}
PIN
32 byte hash value for maximum 16 byte PIN. See User.GetPINHash.
templates
Fingerprint templates of the user.
message AccessOnCardData {
  repeated uint32 accessGroupIDs;
  uint32 startTime;
  uint32 endTime;
}
accessGroupIDs
IDs of access groups the user belongs to. See Access.AccessGroup.
startTime/endTime
Same as UserSetting.

Read/Write

Scan

Read a card on a device.

Request
Parameter Type Description
deviceID uint32 The ID of the device
Response
Parameter Type Description
cardData CardData The card information read on the device

Erase

Erase a smartcard on a device. You have to erase a card before rewriting new data onto it.

Request
Parameter Type Description
deviceID uint32 The ID of the device

Write

Write a smartcard on a device. If the card is not empty, you have to erase it first.

Request
Parameter Type Description
deviceID uint32 The ID of the device
smartCardData SmartCardData The smartcard information to be written

WriteQRCode

Convert a QR code into CSNCardData, which can be assigned to user using User.Enroll or User.SetCard.

Request
Parameter Type Description
QRText string Up to 32 ASCII codes
Response
Parameter Type Description
cardData CSNCardData The card data which can be assigned to user

Config

The supported card configurations depend on the device type. See the article.

message CardConfig {
  CardByteOrder byteOrder;
  bool useWiegandFormat;
  CardDataType dataType;
  bool useSecondaryKey;

  MifareConfig mifareConfig;
  IClassConfig iClassConfig;
  DESFireConfig DESFireConfig;
  SEOSConfig SEOSConfig;

  uint32 formatID;
}
byteOrder
The byte ordering of the data stored on the card. The default is MSB.
useWiegandFormat
If true, use the Wiegand format to decode the card ID data.
dataType
The encoding type of the data stored on the card. The default is DATA_BINARY.
useSecondaryKey
If true, try the secondary key when reading or writing with the primary key fails.
mifareConfig
Valid only if the device supports Mifare cards.
iClassConfig
Valid only if the device supports iClass cards.
DESFireConfig
Valid only if the device supports DESFire cards.
SEOSConfig
Valid only if the device supports SEOS cards.
formatID
You can assign an ID for managing multiple card configurations in your application. It is not used by the device.
enum CardByteOrder {
  MSB = 0;
  LSB = 1;
}
enum CardDataType {
  DATA_BINARY = 0;
  DATA_ASCII = 1;
  DATA_UTF16 = 2;
  DATA_BCD = 3;  
}
message MifareConfig {
  bytes primaryKey;
  bytes secondaryKey;
  int32 startBlockIndex;
}
primaryKey
A 6 byte key for encrypting/decrypting data. The default is 0xffffffffffff.
secondaryKey
A 6 byte key. Used only if CardConfig.useSecondaryKey is true.
startBlockIndex
The index of the first data block on the Mifare card.
message IClassConfig {
  bytes primaryKey;
  bytes secondaryKey;
  int32 startBlockIndex;
}
primaryKey
An 8 byte key for encrypting/decrypting data.
secondaryKey
An 8 byte key. Used only if CardConfig.useSecondaryKey is true.
startBlockIndex
The index of the first data block on the iClass card.
message DESFireConfig {
  bytes primaryKey;
  bytes secondaryKey;
  bytes appID;
  uint32 fileID;
  DESFireEncryptionType encryptionType;
}
primaryKey
A 16 byte key for encrypting/decrypting data.
secondaryKey
A 16 byte key. Used only if CardConfig.useSecondaryKey is true.
appID
A 3 byte application ID.
fileID
One byte file ID which is used for storing the card data.
encryptionType
enum DESFireEncryptionType {
  ENC_DES_3DES = 0;
  ENC_AES = 1;
}
message SEOSConfig {
  bytes OIDADF;
  uint32 sizeADF;
  repeated uint32 OIDDataObjectID;
  repeated uint32 sizeDataObject;
  bytes primaryKeyAuth;
  bytes secondaryKeyAuth;
}
OIDADF
13 byte Application Dedicated Files(ADF) address. Read-only.
sizeADF
The size of the ADF.
OIDDataObjectID
Maximum 8 data object ID can be set.
sizeDataObject
The size of each data object.
primaryKeyAuth
A 16 byte key for encrypting/decrypting data.
secondaryKeyAuth
A 16 byte key. Used only if CardConfig.useSecondaryKey is true.

GetConfig

Get the card configuration of a device.

Request
Parameter Type Description
deviceID uint32 The ID of the device
Response
Parameter Type Description
config CardConfig The card configuration stored on the device

SetConfig

Change the card configuration of a device.

Request
Parameter Type Description
deviceID uint32 The ID of the device
config CardConfig The card configuration to be written to the device

SetConfigMulti

Change the card configurations of multiple devices.

Request
Parameter Type Description
deviceIDs uint32[] The IDs of the devices
config CardConfig The card configuration to be written to the devices

Get1xConfig

Some BioStar 2 devices can read Mifare cards issued by BioStar 1 devices. Please check CapabilityInfo.card1xSupported of the device first.

message Card1XConfig {
  bool useCSNOnly;
  bool bioEntryCompatible;

  bool useSecondaryKey;
  bytes primaryKey;
  bytes secondaryKey;

  uint32 CISIndex;
  uint32 numOfTemplate;
  uint32 templateSize;
  repeated uint32 templateStartBlocks;
}
Request
Parameter Type Description
deviceID uint32 The ID of the device
Response
Parameter Type Description
config Card1XConfig The V1 card configuration of the device

Set1xConfig

Change the V1 configuration of a device.

Request
Parameter Type Description
deviceID uint32 The ID of the device
config Card1XConfig The V1 card configuration to be written to the device

Set1xConfigMulti

Change the V1 configurations of multiple devices.

Request
Parameter Type Description
deviceIDs uint32[] The IDs of the devices
config Card1XConfig The V1 card configuration to be written to the devices

GetQRConfig

X-Station 2 supports QR codes as credentials. A QR code can be composed of up to 32 ASCII codes. See WriteQRCode for converting a QR code string into card data.

message QRConfig {
  bool useQRCode;
  uint32 scanTimeout;
}
useQRCode
Enable reading QR codes.
scanTimeout
Timeout in seconds for reading a QR code.
Request
Parameter Type Description
deviceID uint32 The ID of the device
Response
Parameter Type Description
config QRConfig The QR configuration of the device

SetQRConfig

Change the QR configuration of a device.

Request
Parameter Type Description
deviceID uint32 The ID of the device
config QRConfig The QR configuration to be written to the device

SetQRConfigMulti

Change the QR configurations of multiple devices.

Request
Parameter Type Description
deviceIDs uint32[] The IDs of the devices
config QRConfig The QR configuration to be written to the devices

Blacklist

In some cases, you have to disable cards already assigned to users. For example, if a user lost a card, you have to disable it for security. Each device manages a blacklist for this purpose.

message BlacklistItem {
  bytes cardID;
  uint32 issueCount;
}
cardID
32 byte card ID.
issueCount
Valid only for smartcards.

GetBlacklist

Get the blacklist of a device.

Request
Parameter Type Description
deviceID uint32 The ID of the device
Response
Parameter Type Description
blacklist BlacklistItem[] The blacklist of the device

AddBlacklist

Add cards to the blacklist of a device.

Request
Parameter Type Description
deviceID uint32 The ID of the device
cardInfos BlacklistItem[] The cards to be added to the blacklist of the device

AddBlacklistMulti

Add cards to the blacklists of multiple devices.

Request
Parameter Type Description
deviceIDs uint32[] The IDs of the devices
cardInfos BlacklistItem[] The cards to be added to the blacklists of the devices

DeleteBlacklist

Delete cards from the blacklist of a device.

Request
Parameter Type Description
deviceID uint32 The ID of the device
cardInfos BlacklistItem[] The cards to be deleted from the blacklist of the device

DeleteBlacklistMulti

Delete cards from the blacklists of multiple devices.

Request
Parameter Type Description
deviceIDs uint32[] The IDs of the devices
cardInfos BlacklistItem[] The cards to be deleted from the blacklists of the devices

DeleteAllBlacklist

Delete all cards from the blacklist of a device.

Request
Parameter Type Description
deviceID uint32 The ID of the device

DeleteAllBlacklistMulti

Delete all cards from the blacklists of multiple devices.

Request
Parameter Type Description
deviceIDs uint32[] The IDs of the devices