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_CONFIG_CARD = 0x0B;
  CARD_TYPE_CUSTOM_SMART = 0x0D;
}

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_TYPE_CONFIG_CARD: Card type used when supporting HID config cards.
CARD_TYPE_CUSTOM_SMART: This is the card type used for Custom smart cards.

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;
  MIFARE_ENCRYPTION mifareEncryption;
}

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.
mifareEncryption: Set the encryption type of MIFARE.

enum CardByteOrder {
  MSB = 0;
  LSB = 1;
}

enum CardDataType {
  DATA_BINARY = 0;
  DATA_ASCII = 1;
  DATA_UTF16 = 2;
  DATA_BCD = 3;  
}

enum MIFARE_ENCRYPTION {
  MIFARE_ENCRYPTION_CRYPTO1 = 0;
  MIFARE_ENCRYPTION_AES128 = 1;
}

MIFARE_ENCRYPTION_CRYPTO1: Set the encryption type of MIFARE to crypto1. The key size can be set up to 6 bytes.
MIFARE_ENCRYPTION_AES128: Set the encryption type of MIFARE to AES128. The key size can be set up to 16 bytes.

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;

  bool useVisualQRCode;
  MotionSensitivity motionSensitivity;
  uint32 visualQRScanTimeout;
  bool useVisualQRDetectGuideline;
}

enum MotionSensitivity {
  LOW = 0;
  NORMAL = 1;
  HIGH = 2;
}

useQRCode: Enable reading QR codes.
scanTimeout: Timeout in seconds for reading a QR code. The default is 4 seconds, and you can set the time between 4 and 10 seconds.
bypassData: If true, the QR data will be transfered to the device gateway. (At a later date)
treatAsCSN: If true, the QR data will be treated as CSN.
[+ 1.9.0] useVisualQRCode: Enable reading QR codes via visual camera.

Device Type	Supported Version
XS2	V1.2.0 or later
BS3	V1.1.0 or later

[+ 1.9.0] motionSensitivity: Set the sensitivity of motion sensor for visual barcode.
[+ 1.9.0] visualQRScanTimeout: Timeout in seconds for reading a QR code via visual camera. The default is 10 seconds, and you can set the time between 3 and 20 seconds.
[+ 1.9.0] useVisualQRDetectGuideline: XPass Q2 A QR code detection outline will appear on the screen.

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;
  bool useSecondaryKey;
  CustomMifareCard mifare;
  CustomDESFireCard desfire;
  CardByteOrder smartCardByteOrder;
  uint32 formatID;
  MIFARE_ENCRYPTION mifareEncryption;
}

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.
mifareEncryption: Set the encryption type of MIFARE.

message CustomMifareCard {
  bytes primaryKey;
  bytes secondaryKey;
  uint32 startBlockIndex;
  uint32 dataSize;
  uint32 skipBytes;
}

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;
  bytes secondaryKey;
  bytes appID;
  uint32 fileID;
  DESFireEncryptionType encryptionType;
  DESFireOperationMode operationMode;
  uint32 dataSize;
  uint32 skipBytes;
  DESFireAppLevelKey desfireAppKey;
}

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;
  bytes fileReadKey;
  bytes fileWriteKey;
  uint32 fileReadKeyNumber;
  uint32 fileWriteKeyNumber;
}

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

FacilityCodeConfig

[+ 1.8.0] Set the facility code on the DoorInterface device.

message FacilityCodeConfig {
  repeated FacilityCode facilityCodes;
}

facilityCodes: Specify up to 16 facility codes.

message FacilityCode {
  bytes code;
}

code: Specifies a facility code of up to 4 bytes in size.

enum Enum {
  FACILITY_CODE_SIZE = 4;
  MAX_FACILITY_CODE = 16;
}

GetFacilityCodeConfig

Get the facility code configuration of a device.

Request

Parameter	Type	Description
deviceID	uint32	The ID of the device

Response

Parameter	Type	Description
config	FacilityCodeConfig	The facility code configuration of the device

SetFacilityCodeConfig

Change the facility code configuration of a device.

Request

Parameter	Type	Description
deviceID	uint32	The ID of the device
config	FacilityCodeConfig	The facility code configuration to be written to the device

SetFacilityCodeConfigMulti

Change the facility code configurations of multiple devices.

Request

Parameter	Type	Description
deviceIDs	uint32[]	The IDs of the devices
config	FacilityCodeConfig	The facility code configuration to be written to the devices

LockOverride

[+ 1.9.0] Normally, when a door is locked, authentication attempts will not open the door.
V1.9.0 provides a method for emergency door opening in the event of a fire or other disaster.
If a card used for emergency door opening is set to Lock Override and placed on the device, and the door is locked, the door will be opened using the card authentication set to Lock Override. If the door is not locked, normal authentication for the card will be performed (if the card has been pre-assigned to a general user).
Emergency door opening is also valid even if a card registered with Lock Override is blacklisted. Furthermore, even if the slave device does not support Lock Override, emergency door opening using Lock Override is possible if the master device supports it. Lock override has the following constraints:

Up to eight Lock Override credentials can be assigned to a user.
Up to 1000 Lock Override credentials can be set on a device.

Currently, the following authentication methods can be used with Lock Override:

CSN card
SC card

message LockOverride {
  bytes cardID = 1;
  uint32 issueCount = 2;

  Type type = 3;
  uint32 size = 4;
  string userID = 5;
}

cardID: 32 byte card ID.
issueCount: Valid only for smartcards.
type
size: The value is always 32. Note that you cannot write a CSNCard.
userID: If the card has already been assigned to a user, you can set that user’s user ID.
If you are not assigning the card to a user and intend to use it only for emergency opening, leave this information blank. In this case, if the door is not locked, card authentication will not be performed as normal authentication, and the door will not be opened.

GetLockOverride

Get lock overrides of a device.

Request

Parameter	Type	Description
deviceID	uint32	The ID of the device
lockOverrides	LockOverride[]	Lock overrides search filter

Response

Parameter	Type	Description
lockOverrides	LockOverride[]	Lock overrides of the device

GetAllLockOverride

Get all lock overrides of a device.

Request

Parameter	Type	Description
deviceID	uint32	The ID of the device

Response

Parameter	Type	Description
lockOverrides	LockOverride[]	Lock overrides of the device

SetLockOverride

Set lock overrides on a device.

Request

Parameter	Type	Description
deviceID	uint32	The ID of the device
lockOverrides	LockOverride[]	Lock overrides to set on the device

SetLockOverrideMulti

Set lock overrides on multiple devices.

Request

Parameter	Type	Description
deviceIDs	uint32[]	The IDs of the devices
lockOverrides	LockOverride[]	Lock overrides to set on multiple devices

DeleteLockOverride

Delete lock overrides on a device.

Request

Parameter	Type	Description
deviceID	uint32	The ID of the device
lockOverrides	LockOverride[]	Lock overrides delete filter

DeleteLockOverrideMulti

Delete lock overrides on multiple devices.

Request

Parameter	Type	Description
deviceIDs	uint32[]	The IDs of the devices
lockOverrides	LockOverride[]	Lock overrides delete filter

DeleteAllLockOverride

Delete all lock overrides on a device.

Request

Parameter	Type	Description
deviceID	uint32	The ID of the device

DeleteAllLockOverrideMulti

Delete all lock overrides on multiple devices.

Request

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