슈프리마 스마트 카드 발급 안내

이 문서는 서드파티 업체가 슈프리마의 BioStar 플랫폼과 호환되는 스마트 카드를 발급하기 위한 기술 가이드입니다.

카드 데이터 구조: SCC(Secure Credential Card)와 AOC(Access on Card) 발급에 필요한 데이터 구조
구조체 명세: 카드 발급 시 준수해야 하는 필드별 상세 요구사항
데이터 무결성: CRC 검증을 통한 카드 데이터 품질 보장 방법
구현 참조: 각 구조체 간의 관계와 올바른 데이터 설정 방법

이 문서에 따라 발급된 스마트 카드는 슈프리마의 모든 BioStar 호환 장치에서 정상 동작합니다.

알아두기

스마트 카드를 발급하기 전에 아래 사항을 확인하세요.

호환 장치: BioStar 지원 모든 슈프리마 장치
카드 유형: SCC(Secure Credential Card), AOC(Access on Card)

구조체 관계도

SmartCard API 구조체 관계도

이미지의 구조체를 클릭하면 해당 구조체의 상세 정보로 이동합니다.

구조 계층

BS2SmartCardData

Smart Card1656 bytes

SmartCard의 모든 데이터를 포함하는 복합 구조체입니다.

BS2SmartCardDatacomposite struct1656 bytes
SmartCard 전체 데이터 컨테이너

BS2SmartCardHeaderstruct16 bytes
SmartCard 헤더 구조체

체크섬 영역
체크섬 영역은 카드 데이터의 무결성을 검증하는 데 사용합니다. 자세한 내용은 다음 문서를 참고하세요.

hdrCRCuint16_t2 bytes
카드 헤더 체크섬 값입니다. (cardCRC - reserved)

cardCRCuint16_t2 bytes
카드 데이터 체크섬 값입니다. (BS2SmartCardHeader.cardType - BS2SmartCardData.accessOnData)

카드 메타데이터
카드 유형 및 템플릿 정보

cardTypeBS2_CARD_TYPE1 byte
카드 유형의 코드 값입니다.
가능한 값
값 설명
0x02
Secure Credential Card (SCC)
0x03
Access on Card (AOC)

값	설명
0x02	Secure Credential Card (SCC)
0x03	Access on Card (AOC)

numOfTemplateuint8_t1 byte
지문 템플릿의 개수입니다. Access on Card (AOC) 카드 구조상 템플릿은 BS2SmartCardCredentials에 저장됩니다. 지문 또는 얼굴을 선택적으로 저장해야 합니다. 지문과 얼굴이 함께 저장되지 않으므로 AOC 카드에 지문 템플릿을 저장하려면, numOfFaceTemplate은 반드시 0으로 설정되어야 합니다.
- 최대 4개의 지문 템플릿을 지원합니다. 지문 템플릿 데이터 영역에 대한 자세한 내용은 다음 문서를 참고하세요.

templateSizeuint16_t2 bytes
지문 템플릿의 크기입니다. 일반적인 지문 템플릿의 크기는 384바이트로 고정되어 있습니다. BioStar 2에서 스마트 카드를 사용하려면 기본값은 300바이트이며, 필요에 따라 변경할 수 있지만 템플릿의 크기가 너무 작게 설정되면 지문 매칭에 문제가 발생할 수 있으므로 300바이트 이상으로 설정하는 것을 권장합니다.
- 300바이트로 설정 시 384바이트 크기의 배열에 300바이트를 복사하고 나머지 84바이트는 0으로 패딩해야 합니다.
- MIFARE 1K Classic 카드에 2개의 지문을 저장하려면 각 템플릿을 300바이트로 설정해야 합니다.

issueCountuint16_t2 bytes
스마트 카드 발급 회차입니다. 카드 ID와 발급 회차를 조합하여 블랙리스트를 관리하므로 발급 회차를 정확히 관리해야 합니다. 카드 재발급 시 발급 회차를 1씩 증가시켜야 합니다.

duressMaskuint8_t1 byte
협박 지문 유무 마스크 값입니다.

numOfFaceTemplateuint8_t1 byte
얼굴 템플릿 수를 나타냅니다. 지문과 얼굴이 갖는 기본 템플릿(지문:384, 얼굴:552)의 크기가 다르지만, 이 경우에도 변함없이 BS2SmartCardCredentials의 templateData의 전체 크기를 고려하여 저장하면 됩니다. AOC 카드 구조 상 템플릿은 BS2SmartCardCredentials에 저장됩니다. 그리고 여기에는 지문 또는 얼굴을 선택적으로 저장해야 합니다. 지문과 얼굴이 함께 저장되지 않으므로 AOC 카드에 얼굴 템플릿을 저장하려면, numOfTemplate은 반드시 0으로 설정되어야 합니다.
- 최대 1개의 얼굴 템플릿을 지원합니다.

reserveduint8_t[1]1 byte
예약된 공간입니다.

인증 설정
카드 인증 모드 및 옵션

cardAuthModeuint8_t1 byte

개인 인증 모드로 장치에 설정된 인증 모드가 아닌 카드에 저장된 인증 모드를 사용하게 됩니다.

Visual Face 기반은 cardAuthModeEx를 사용하세요.

가능한 값

값	설명
2	카드 인증만 사용
3	카드와 지문 인증 사용
4	카드와 PIN 인증 사용
5	카드 인증 후 지문이나 PIN 인증 사용
6	카드, 지문, PIN 인증 사용
254	사용할 수 없음
255	정의되지 않음(시스템에 정의된 모드로 동작)

cardAuthModeExuint8_t1 byte

SDK v2.7.1 or later Visual Face 기반 카드 인증 모드 설정값입니다. 개인 인증 모드로 장치에 설정된 인증 모드가 아닌 카드에 저장된 인증 모드를 사용하게 됩니다.

슈프리마 장치는 FaceStation F2, BioStation 3, BioEntry W3 모델에서 지원합니다.
모든 장치에 일관되게 적용하려면 cardAuthMode, cardAuthModeEx 모두를 설정해야 합니다. 지원하는 장치를 확인하세요.

가능한 값

값	설명
21	카드
22	카드 + 얼굴
23	카드 + 지문
24	카드 + PIN
26	카드 + 얼굴 또는 PIN
27	카드 + 지문 또는 PIN
28	카드 + 얼굴 또는 지문 또는 PIN
30	카드 + 얼굴 + PIN
32	카드 + 지문 + PIN
33	카드 + 얼굴 또는 지문 + PIN
254	사용할 수 없음
255	정의되지 않음(시스템 정의 모드)

useAlphanumericIDuint8_t1 byte
영숫자(Alphanumeric) ID를 사용할지 결정하는 플래그(flag)입니다.

cardIDuint8_t[BS2_CARD_DATA_SIZE]32 bytes
단말기에서 사용할 카드 식별자입니다. Access on Card(AOC)는 배열의 32byte를 Card ID로 사용하고, Secure Credential Card(SCC)는 배열의 24byte를 Card ID로 사용합니다. Secure Credential Card(SCC)는 32byte를 Card ID(24 bytes)로, issueCount(4byte) 그리고 Time Stamp(4byte)로 채워져야 합니다. 또한, BS2UserBlob 구조체의 cardObjs array가 SC Card로 채워야 하며, SC Card 발급 시마다 cardObjs를 업데이트해야 합니다.

cardID: Access on Card (AOC)bytes[0-31]32 bytes
AOC: 전체 32바이트 사용

cardID: Secure Credential Card (SCC)bytes[0-31]32 bytes
SCC: 카드 ID(32바이트)

cardID (SCC)bytes[0-23]24 bytes
SCC: 카드 ID(24바이트)

issueCount (SCC)bytes[24-27]4 bytes
SCC: 발급 횟수

timeStamp (SCC)bytes[28-31]4 bytes
SCC: 발급 시간

BS2SmartCardCredentialsstruct1568 bytes
PIN 코드나 생체 인증 템플릿이 저장되어 있는 인증 데이터 영역입니다.

pinuint8_t[BS2_PIN_HASH_SIZE]32 bytes
PIN 코드 해시값입니다. PIN 코드를 직접 해시하지 말고 BioStar 2 SDK의 해시 함수를 사용하여 장치와 동일한 해시 알고리즘으로 생성해야 합니다.
- PIN 코드는 서드파티 툴에서 사용할 수 없습니다.

templateDatauint8_t[S2_SMART_CARD_MAX_TEMPLATE_COUNT * BS2_FINGER_TEMPLATE_SIZE]1536 bytes
지문 또는 얼굴 템플릿 데이터 영역으로 최대 4개의 지문 템플릿, 최대 1개의 얼굴 템플릿을 저장할 수 있습니다.

지문 템플릿
최대 4개의 지문 템플릿을 저장할 수 있습니다.

Template 1uint8_t[384]384 bytes
첫 번째 지문 템플릿

Template 2uint8_t[384]384 bytes
두 번째 지문 템플릿

Template 3uint8_t[384]384 bytes
세 번째 지문 템플릿

Template 4uint8_t[384]384 bytes
네 번째 지문 템플릿

얼굴 템플릿
최대 1개의 얼굴 템플릿을 552 사이즈로 저장할 수 있습니다.

Template 1uint8_t[552]552 bytes
얼굴 템플릿

BS2AccessOnCardDatastruct40 bytes
AOC 카드에서 사용하는 영역으로 출입 그룹 정보를 가지고 있습니다.

accessGroupIDuint16_t[BS2_SMART_CARD_MAX_ACCESS_GROUP_COUNT]32 bytes
출입 그룹 ID 리스트입니다. 각 그룹은 1부터 65535까지의 ID를 가질 수 있으며, 최대 16개의 그룹을 지원합니다.

Group ID 1uint16_t2 bytes
첫 번째 출입 그룹

Group ID 2uint16_t2 bytes
두 번째 출입 그룹

...uint16_t2 bytes
...

Group ID 16uint16_t2 bytes
마지막 출입 그룹

시간 제한
출입 가능 시간 범위입니다.

startTimeBS2_DATETIME4 bytes
사용자 인증이 가능한 시작 시간이며, 0일 경우 제한이 없습니다. Unix timestamp 형식으로 초 단위입니다.

endTimeBS2_DATETIME4 bytes
사용자 인증이 가능한 마지막 시간이며, 0일 경우 제한이 없습니다. Unix timestamp 형식으로 초 단위입니다.

CRC 계산 및 검증

SmartCard 데이터의 무결성을 보장하기 위해 헤더와 카드 데이터에 각각 CRC-16 CCITT 체크섬(hdrCRC, cardCRC)을 사용합니다.

hdrCRC, cardCRC란?

hdrCRC: BS2SmartCardHeader의 cardCRC부터 reserved까지(총 14바이트)에 대해 CRC-16 CCITT(다항식 0x1021, 초기값 0xFFFF)로 계산한 값입니다.
cardCRC: cardType부터 BS2SmartCardData.accessOnData까지(헤더를 제외한 카드 데이터 전체)에 대해 CRC-16 CCITT(다항식 0x1021, 초기값 0xFFFF)로 계산한 값입니다.

CRC 계산 방법

BioStar 2 SDK에서는 BS2_ComputeCRC16CCITT 함수를 제공합니다. 아래는 사용 예시입니다.

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는 cardType부터 accessOnData까지 계산합니다.
hdrCRC는 cardCRC부터 reserved까지 계산합니다.
반드시 cardCRC를 먼저 계산한 후 헤더에 설정하고, 그 다음 hdrCRC를 계산해야 합니다.

검증 방법

카드 데이터를 읽을 때 무결성을 검증하려면 다음과 같이 수행하세요.

카드에서 읽은 데이터로 CRC 재계산
저장된 CRC 값과 계산된 CRC 값 비교

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

CRC 계산 시 주의사항

계산 순서: 반드시 cardCRC를 먼저 계산한 후 헤더에 설정하고, 그 다음 hdrCRC를 계산해야 합니다.
구조체 정렬: CRC 계산 범위가 정확히 일치해야 하며, 구조체 패딩이나 정렬에 주의하세요.
초기값: CRC-16 CCITT는 0x1021 다항식, 초기값 0xFFFF를 사용합니다.
SDK 함수: BS2_ComputeCRC16CCITT 함수는 BioStar 2 SDK에서 제공됩니다.
데이터 순서: 입력 데이터는 바이트 단위 Little Endian으로 처리됩니다.

구조체 관계도​

구조 계층​

BS2SmartCardData​

가능한 값

가능한 값

가능한 값

CRC 계산 및 검증​

hdrCRC, cardCRC란?​

CRC 계산 방법​

검증 방법​

구조체 관계도

구조 계층

BS2SmartCardData

CRC 계산 및 검증

hdrCRC, cardCRC란?

CRC 계산 방법

검증 방법