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;
  oneof templateCount {
    uint32 numOfTemplate;
    uint32 numOfFaceTemplate;   // Only for FaceStation F2 and BioStation 3
  }
  uint32 templateSize;
  uint32 issueCount;
  uint32 duressMask;
  uint32 cardAuthMode;
  bool useAlphanumericID;
  uint32 cardAuthModeEx;    // Only for FaceStation F2 and BioStation 3
}
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.

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;

  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.

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;
  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.
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

CustomConfig

[+ 1.7] Supports reading of smart card data by arbitrarily specifying its location and size. Please check DeviceCapability.customSmartCardSupported of the device first.

message CustomConfig {
  CardDataType dataType = 1;
  bool useSecondaryKey = 2;
  CustomMifareCard mifare = 3;
  CustomDESFireCard desfire = 4;
  CardByteOrder smartCardByteOrder = 5;
  uint32 formatID = 6;
}
dataType
Type of card data.
useSecondaryKey
Decides whether to use the secondary encryption key.
mifare
Set the Mifare custom card information.
desfire
Set the DESFire custom card information.
smartCardByteOrder
The output method can be selected from MSB or LSB.
formatID
This is an identifier that can be used when the BioStar 2 application needs to manage the card configuration as a database.
message CustomMifareCard {
  bytes primaryKey = 1;
  bytes secondaryKey = 2;
  uint32 startBlockIndex = 3;
  uint32 dataSize = 4;
  uint32 skipBytes = 5;
}
primaryKey
Primary encryption key to access the Mifare card information.
secondaryKey
Secondary encryption key to access the Mifare card information.
startBlockIndex
Start block index on the Mifare data storage.
dataSize
The size in bytes of the card data.
skipBytes
This is where the card data appears. This is the starting point to read card data. It is 0 when reading from the starting point, and indicates the number of bytes skipped after the first.
message CustomDESFireCard {
  bytes primaryKey = 1;
  bytes secondaryKey = 2;
  bytes appID = 3;
  uint32 fileID = 4;
  DESFireEncryptionType encryptionType = 5;
  DESFireOperationMode operationMode = 6;
  uint32 dataSize = 7;
  uint32 skipBytes = 8;
  DESFireAppLevelKey desfireAppKey = 9;
}
primaryKey
Primary encryption key to access the DESFire card information. (General settings)
secondaryKey
Secondary encryption key to access the DESFire card information. (General settings)
appID
Application Id that is stored inside the DESFire card for user authentication.
fileID
File ID that is stored inside the DESFire card, which will be used by the application to read and write data.
encryptionType
Type of data encryption.
operationMode
Operation mode.
dataSize
The size in bytes of the card data.
skipBytes
This is where the card data appears. This is the starting point to read card data. It is 0 when reading from the starting point, and indicates the number of bytes skipped after the first.
desfireAppKey
Indicates key information to access DESFire card information. (Advanced settings)
message DESFireAppLevelKey {
  bytes appMasterKey = 1;
  bytes fileReadKey = 2;
  bytes fileWriteKey = 3;
  uint32 fileReadKeyNumber = 4;
  uint32 fileWriteKeyNumber = 5;
}
appMasterKey
Application master key of DESFire.
fileReadKey
The key used to read the file.
fileWriteKey
The key used to write the file.
fileReadKeyNumber
The index of the key for reading the file.
fileWriteKeyNumber
The index of the key for writing the file.
desfireAppKey
A structure containing DesFire key information.

GetCustomConfig

Get the custom card configuration of a device.

Request
Parameter Type Description
deviceID uint32 The ID of the device
Response
Parameter Type Description
config CustomConfig The custom smart card configuration of the device

SetCustomConfig

Change the custom smart card configuration of a device.

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

SetCustomConfigMulti

Change the custom smart card configurations of multiple devices.

Request
Parameter Type Description
deviceIDs uint32[] The IDs of the devices
config CustomConfig The custom smart card 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

Updated: