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.
- 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.
- numOfFaceTemplate
- The number of face templates stored in the card. Maximum 2 templates can be stored on a card.
- templateSize
- The size of fingerprint/face template in bytes. Typically, 384 or 552
- 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.
- useAlphanumericID
- If true, cardID should be string.
- cardAuthMode
- Specify the private authentication mode for the card.
- cardAuthModeEx
- Specify the extended private authentication mode for the card.
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.
Parameter |
Type |
Description |
deviceID |
uint32 |
The ID of the device |
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.
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.
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.
Parameter |
Type |
Description |
QRText |
string |
Up to 32 ASCII codes |
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;
bool cipher;
CardByteOrder smartCardByteOrder;
}
- 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.
- cipher
- If true, CardID entry via keypad on XPASS D2 will be accepted.
- smartCardByteOrder
- The byte ordering of the data stored on the SmartCard. The default is MSB.
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;
DESFireOperationMode operationMode;
}
- 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;
}
operationMode
:
enum DESFireOperationMode {
OPERATION_LEGACY = 0;
OPERATION_APPLEVELKEY = 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.
Parameter |
Type |
Description |
deviceID |
uint32 |
The ID of the device |
Parameter |
Type |
Description |
config |
CardConfig |
The card configuration stored on the device |
SetConfig
Change the card configuration of a device.
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.
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;
}
Parameter |
Type |
Description |
deviceID |
uint32 |
The ID of the device |
Parameter |
Type |
Description |
config |
Card1XConfig |
The V1 card configuration of the device |
Set1xConfig
Change the V1 configuration of a device.
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.
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;
bool bypassData;
bool treatAsCSN;
}
- useQRCode
- Enable reading QR codes.
- scanTimeout
- Timeout in seconds for reading a QR code.
- bypassData
- If true, the QR data will be transfered to the device gateway.
- treatAsCSN
- If true, the QR data will be treated as CSN.
Parameter |
Type |
Description |
deviceID |
uint32 |
The ID of the device |
Parameter |
Type |
Description |
config |
QRConfig |
The QR configuration of the device |
SetQRConfig
Change the QR configuration of a device.
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.
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.
Parameter |
Type |
Description |
deviceID |
uint32 |
The ID of the device |
Parameter |
Type |
Description |
blacklist |
BlacklistItem[] |
The blacklist of the device |
AddBlacklist
Add cards to the blacklist of a device.
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.
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.
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.
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.
Parameter |
Type |
Description |
deviceID |
uint32 |
The ID of the device |
DeleteAllBlacklistMulti
Delete all cards from the blacklists of multiple devices.
Parameter |
Type |
Description |
deviceIDs |
uint32[] |
The IDs of the devices |