Skip to main content

How to Issue Suprema Smart Cards

This document provides a technical guide for third-party vendors to issue smart cards compatible with Suprema's BioStar platform.

  • Card data structure: Data structure required for the issuance of SCC (Secure Credential Card) and AOC (Access on Card)

  • Structure specification: Detailed requirements for each field that must be complied with during card issuance

  • Data integrity: Method for ensuring the quality of card data through CRC validation

  • Implementation reference: Relationships between structures and how to correctly set data

Smart cards issued according to this document operate normally on all BioStar compatible devices from Suprema.

Info

Check the following before issuing smart cards.

  • Compatible devices: All Suprema devices supported by BioStar

  • Card types: SCC (Secure Credential Card), AOC (Access on Card)

Structure Relationship Diagram​

BS2SmartCardDataBS2SmartCardHeaderBS2SmartCardCredentialsBS2AccessOnCardData

SmartCard API structure relationship diagram

Clicking on the structure in the image will take you to the details of that structure.

Structure Hierarchy​

BS2SmartCardData​

Smart Card1656 bytes

Composite structure containing all data of SmartCard.

  • BS2SmartCardDatacomposite struct1656 bytes

    Container for all SmartCard data

    • BS2SmartCardHeaderstruct16 bytes

      SmartCard header structure

      • Checksum Area

        The checksum area is used to validate the integrity of card data. For more information, refer to the following.

        • hdrCRCuint16_t2 bytes

          Checksum value of the card header. (cardCRC - reserved)

        • cardCRCuint16_t2 bytes

          Checksum value of card data. (BS2SmartCardHeader.cardType - BS2SmartCardData.accessOnData)

      • Card Metadata

        Card type and template information

        • cardTypeBS2_CARD_TYPE1 byte

          Code value of card type.

          Available values
          ValueDescription
          0x02

          Secure Credential Card (SCC)

          0x03

          Access on Card (AOC)

        • numOfTemplateuint8_t1 byte

          Number of fingerprint templates. For Access on Card (AOC), templates are stored in BS2SmartCardCredentials. Fingerprints or faces must be stored selectively. Since fingerprints and faces are not stored together, if you want to store a fingerprint template in AOC, numOfFaceTemplate must be set to 0.

          • Supports up to 4 fingerprint templates. For more information on fingerprint template data area, refer to the following.

        • templateSizeuint16_t2 bytes

          Size of the fingerprint template. The typical size of a fingerprint template is fixed at 384 bytes. The default for using smart cards in BioStar 2 is 300 bytes, which can be changed as needed, but set the size above 300 bytes to avoid issues with fingerprint matching.

          • When set to 300 bytes, copy 300 bytes into an array of size 384 bytes, and pad the remaining 84 bytes with 0.

          • To store 2 fingerprints in a MIFARE 1K Classic card, set each template to 300 bytes.

        • issueCountuint16_t2 bytes

          Issue number of the smart card. Manage the blacklist by combining card ID and issue number, so manage the issue number accurately. When reissuing the card, increment the issue number by 1.

        • duressMaskuint8_t1 byte

          Mask for whether there is a duress fingerprint.

        • numOfFaceTemplateuint8_t1 byte

          Indicates the number of face templates. Although the basic template sizes for fingerprints and faces (fingerprint: 384, face: 552) differ, save considering the total size of BS2SmartCardCredentials's templateData. Since fingerprints and faces are not stored together, if you want to store a face template in an AOC card, numOfTemplate must be set to 0.

          • Supports up to 1 face template.

        • reserveduint8_t[1]1 byte

          Reserved.

      • Authentication Settings

        Card authentication modes and options

        • cardAuthModeuint8_t1 byte

          Uses the authentication mode stored on the card instead of the one set on the device.

          • Visual Face base uses cardAuthModeEx.

          Available values
          ValueDescription
          2

          Card authentication only

          3

          Card and fingerprint authentication

          4

          Card and PIN authentication

          5

          Fingerprint or PIN authentication after card authentication

          6

          Card, fingerprint, and PIN authentication

          254

          Not usable

          255

          Undefined (operates in a mode defined by the system)

        • cardAuthModeExuint8_t1 byte

          SDK v2.7.1 or later Setting value for card authentication mode based on Visual Face. Uses the authentication mode stored on the card instead of the one set on the device.

          • Suprema devices are supported on FaceStation F2, BioStation 3, BioEntry W3.

          • To apply consistently across all devices, set both cardAuthMode and cardAuthModeEx. Check supported devices.

          Available values
          ValueDescription
          21

          Card

          22

          Card + Face

          23

          Card + Fingerprint

          24

          Card + PIN

          26

          Card + Face or PIN

          27

          Card + Fingerprint or PIN

          28

          Card + Face or Fingerprint or PIN

          30

          Card + Face + PIN

          32

          Card + Fingerprint + PIN

          33

          Card + Face or Fingerprint + PIN

          254

          Not usable

          255

          Undefined (system-defined mode)

        • useAlphanumericIDuint8_t1 byte

          Flag indicating whether to use Alphanumeric ID.

    • cardIDuint8_t[BS2_CARD_DATA_SIZE]32 bytes

      Card identifier used by the terminal. Access on Card (AOC) uses the entire 32 bytes of the array as Card ID, while Secure Credential Card (SCC) uses 24 bytes of the array as Card ID. Secure Credential Card (SCC) must fill 32 bytes with Card ID (24 bytes), issueCount (4 bytes), and Time Stamp (4 bytes). Fill the cardObjs array of the BS2UserBlob structure with SC Card, and cardObjs must be updated every time the SC Card is issued.

      • cardID: Access on Card (AOC)bytes[0-31]32 bytes

        AOC: Uses the entire 32 bytes.

      • cardID: Secure Credential Card (SCC)bytes[0-31]32 bytes

        SCC: Card ID (32 bytes)

        • cardID (SCC)bytes[0-23]24 bytes

          SCC: Card ID (24 bytes)

        • issueCount (SCC)bytes[24-27]4 bytes

          SCC: Issue count

        • timeStamp (SCC)bytes[28-31]4 bytes

          SCC: Issue time

    • BS2SmartCardCredentialsstruct1568 bytes

      Authentication data area where PIN codes or biometric authentication templates are stored.

      • pinuint8_t[BS2_PIN_HASH_SIZE]32 bytes

        PIN code hash value. Use the hash function of the BioStar 2 SDK to generate it with the same hash algorithm as the device.

        • PIN codes cannot be used in third-party tools.

      • templateDatauint8_t[S2_SMART_CARD_MAX_TEMPLATE_COUNT * BS2_FINGER_TEMPLATE_SIZE]1536 bytes

        Fingerprint or face template data area. Store up to 4 fingerprint templates and 1 face template.

        • Fingerprint Templates

          Supports up to 4 fingerprint templates.

          • Template 1uint8_t[384]384 bytes

            First fingerprint template

          • Template 2uint8_t[384]384 bytes

            Second fingerprint template

          • Template 3uint8_t[384]384 bytes

            Third fingerprint template

          • Template 4uint8_t[384]384 bytes

            Fourth fingerprint template

        • Face Template

          Supports up to 1 face template with size 552.

          • Template 1uint8_t[552]552 bytes

            Face template

    • BS2AccessOnCardDatastruct40 bytes

      Area used in AOC cards that contains access group information.

      • accessGroupIDuint16_t[BS2_SMART_CARD_MAX_ACCESS_GROUP_COUNT]32 bytes

        List of access group IDs. Each group has IDs ranging from 1 to 65535, supporting up to 16 groups.

        • Group ID 1uint16_t2 bytes

          First access group

        • Group ID 2uint16_t2 bytes

          Second access group

        • ...uint16_t2 bytes

          ...

        • Group ID 16uint16_t2 bytes

          Last access group

      • Time Restrictions

        Time range for access permissions.

        • startTimeBS2_DATETIME4 bytes

          Start time for user authentication, with 0 indicating no restriction. In Unix timestamp format, measured in seconds.

        • endTimeBS2_DATETIME4 bytes

          End time for user authentication, with 0 indicating no restriction. In Unix timestamp format, measured in seconds.

CRC Calculation and Validation​

CRC-16 CCITT checksums (hdrCRC, cardCRC) are used for the header and card data respectively, to ensure the integrity of SmartCard data.

What are hdrCRC and cardCRC?​

  • hdrCRC: The value calculated using CRC-16 CCITT (polynomial 0x1021, initial value 0xFFFF) for the cardCRC to reserved (14 bytes total) of BS2SmartCardHeader.

  • cardCRC: The value calculated using CRC-16 CCITT (polynomial 0x1021, initial value 0xFFFF) for card data from cardType to BS2SmartCardData.accessOnData (total card data excluding the header).

How to Calculate CRC​

The BioStar 2 SDK provides the BS2_ComputeCRC16CCITT function. Below is an example of its use.

Calculate checksum
// Calculate card data checksum (cardCRC)
uint16_t cardCRC = 0xFFFF;
int result = BS2_ComputeCRC16CCITT((uint8_t*)&card.header.cardType, sizeof(BS2SmartCardData) - offsetof(BS2SmartCardHeader, cardType), &cardCRC);

// Calculate header checksum (hdrCRC)
card.header.cardCRC = cardCRC;  // Set the cardCRC value first
uint16_t hdrCRC = 0xFFFF;
result = BS2_ComputeCRC16CCITT((uint8_t*)&card.header.cardCRC, sizeof(BS2SmartCardHeader) - offsetof(BS2SmartCardHeader, cardCRC), &hdrCRC);

  • cardCRC is calculated from cardType to accessOnData.

  • hdrCRC is calculated from cardCRC to reserved.

  • Always calculate cardCRC first, set it in the header, then calculate hdrCRC.

How to Validate​

To validate the integrity of card data when reading, do the following:

  1. Recalculate CRC using data read from the card.

  2. Compare the stored CRC value with the calculated CRC value.

CRC Validation
// CRC validation example
BS2SmartCardData readCard;  // Data read from card

// 1. cardCRC validation
uint16_t calculatedCardCRC = 0xFFFF;
BS2_ComputeCRC16CCITT((uint8_t*)&readCard.header.cardType, sizeof(BS2SmartCardData) - offsetof(BS2SmartCardHeader, cardType), &calculatedCardCRC);

if (readCard.header.cardCRC != calculatedCardCRC) {
    // Card data corruption
    return ERROR_CARD_DATA_CORRUPTED;
}

// 2. hdrCRC validation
uint16_t calculatedHdrCRC = 0xFFFF;
BS2_ComputeCRC16CCITT((uint8_t*)&readCard.header.cardCRC, sizeof(BS2SmartCardHeader) - offsetof(BS2SmartCardHeader, cardCRC), &calculatedHdrCRC);

if (readCard.header.hdrCRC != calculatedHdrCRC) {
    // Header data corruption
    return ERROR_HEADER_DATA_CORRUPTED;
}

Cautions for CRC Calculation

  • Calculation Order: Calculate cardCRC first, set it in the header, and then calculate hdrCRC.

  • Structure Alignment: Ensure the CRC calculation range matches precisely, and be cautious of structure padding and alignment.

  • Initial Value: CRC-16 CCITT uses polynomial 0x1021 and initial value 0xFFFF.

  • SDK Function: The BS2_ComputeCRC16CCITT function is provided in the BioStar 2 SDK.

  • Data Order: Input data is processed in little-endian byte order.