SMARTCARD_EXTENSION 구조체(smclib.h)

아티클
08/07/2023

SMARTCARD_EXTENSION 구조는 스마트 카드 판독기 드라이버와 스마트 카드 드라이버 라이브러리 모두에서 다른 모든 스마트 카드 데이터 구조에 액세스하는 데 사용됩니다.

구문

typedef struct _SMARTCARD_EXTENSION {
  ULONG                     Version;
  VENDOR_ATTR               VendorAttr;
  NTSTATUS(                 *ReaderFunction[16];
  SCARD_CARD_CAPABILITIES   CardCapabilities;
  ULONG                     LastError;
  struct {
    PULONG Information;
    PUCHAR RequestBuffer;
    ULONG  RequestBufferLength;
    PUCHAR ReplyBuffer;
    ULONG  ReplyBufferLength;
  } IoRequest;
  ULONG                     MajorIoControlCode;
  ULONG                     MinorIoControlCode;
  POS_DEP_DATA              OsData;
  SCARD_READER_CAPABILITIES ReaderCapabilities;
  PREADER_EXTENSION         ReaderExtension;
  SMARTCARD_REPLY           SmartcardReply;
  SMARTCARD_REQUEST         SmartcardRequest;
  T0_DATA                   T0;
  T1_DATA                   T1;
  PPERF_INFO                PerfInfo;
  ULONG                     Reserved[25 - sizeof(PPERF_INFO)];
} *PSMARTCARD_EXTENSION, SMARTCARD_EXTENSION;

멤버

Version

이 구조체의 버전을 나타냅니다.

VendorAttr

공급업체 이름, 단위 번호 및 일련 번호와 같은 판독기 드라이버를 식별하는 정보를 포함합니다.

ReaderFunction[16]

구문 블록의 줄을 읽어야 합니다. NTSTATUS (*ReaderFunction[16])(PSMARTCARD_EXTENSION);

판독기용 콜백 함수 배열에 대한 포인터입니다. 공급업체에서 제공하는 판독기 드라이버가 구현할 수 있는 콜백 함수입니다. 판독기 드라이버는 스마트 카드 라이브러리 루틴인 SmartcardDeviceControl에서 이러한 콜백 함수를 사용하여 스마트 카드 디바이스 확장에 포인터를 저장하여 호출할 수 있도록 합니다.

RDF_ATR_PARSE

RDF_CARD_EJECT

RDF_CARD_POWER

RDF_CARD_TRACKING

RDF_IOCTL_VENDOR

RDF_READER_SWALLOW

RDF_SET_PROTOCOL

RDF_TRANSMIT

자세한 내용은 설명 부분을 참조하세요.

CardCapabilities

삽입된 스마트 카드 기능을 포함합니다.

LastError

사용되지 않습니다.

IoRequest

다음 멤버가 있는 구조체:

IoRequest.Information

반환된 바이트 수를 포함합니다.

IoRequest.RequestBuffer

카드 보낼 사용자의 I/O 요청에 있는 데이터에 대한 포인터입니다.

IoRequest.RequestBufferLength

카드 보낼 바이트 수를 나타냅니다.

IoRequest.ReplyBuffer

I/O 요청에 의해 반환되는 데이터를 보유하는 버퍼에 대한 포인터입니다.

IoRequest.ReplyBufferLength

I/O 요청에 의해 반환되는 데이터의 바이트 수를 나타냅니다.

MajorIoControlCode

주요 I/O 제어 코드를 포함합니다.

MinorIoControlCode

부 I/O 컨트롤 코드를 포함합니다.

OsData

운영 체제 및 드라이버 유형과 관련된 정보를 포함합니다.

ReaderCapabilities

키보드 판독기의 기능을 포함합니다.

ReaderExtension

스마트 카드 판독기 관련 데이터를 포함합니다.

SmartcardReply

판독기에서 가져온 데이터를 포함합니다.

SmartcardRequest

현재 명령과 스마트 카드 전송되는 데이터를 포함합니다.

T0

T=0 프로토콜에 사용할 데이터를 포함합니다.

T1

T=1 프로토콜과 함께 사용되는 데이터를 포함합니다.

PerfInfo

Reserved[25 - sizeof(PPERF_INFO)]

시스템에서 사용하도록 예약되었습니다.

설명

이 구조체는 모든 콜백 함수에 전달됩니다.

개별 콜백 함수는 ReaderFunction 배열에 대한 인덱스로 사용해야 하는 일련의 상수 값으로 식별됩니다.

인덱스 Description

RDF_ATR_PARSE 선택 사항입니다. RDF_ATR_PARSE 구문 분석 함수는 드라이버 라이브러리가 스마트 카드 드라이버 라이브러리를 인식하거나 구문 분석할 수 없는 경우 스마트 카드 드라이버 라이브러리에 대한 ATR(응답-재설정)을 구문 분석합니다.

RDF_CARD_EJECT

선택 사항입니다. RDF_CARD_EJECT 콜백 함수

RDF_CARD_EJECT 콜백 함수는 판독기에서 삽입된 스마트 카드 배출합니다.

RDF_CARD_POWER

RDF_CARD_POWER 콜백 함수는 삽입된 스마트 카드 다시 설정하거나 해제합니다. 스마트 카드 판독기 드라이버가 이 콜백 함수를 구현해야 합니다.

입력에서 SmartcardExtension 이 가리키는 구조체에는 다음 멤버 값이 있어야 합니다.

MajorIoControlCode

값은 IOCTL_SMARTCARD_POWER.

IoRequest.ReplyBufferLength

버퍼의 길이를 포함해야 합니다.

MinorIoControlCode

다음 부 코드 중 하나가 있어야 합니다.

SCARD_COLD_RESET: 스마트 카드 콜드 재설정을 수행합니다.
SCARD_WARM_RESET: 스마트 카드 웜 재설정을 수행합니다.
SCARD_POWER_DOWN: 스마트 카드 전원을 끕니다.

출력에서 SmartcardExtension 이 가리키는 구조체에는 다음 값이 있어야 합니다.

IoRequest.ReplyBuffer: 스마트 카드 반환되는 ATR을 받습니다. 또한 라이브러리가 ATR을 구문 분석할 수 있도록 ATR을 SmartcardExtension->CardCapabilities.ATR.Buffer 로 전송해야 합니다.
IoRequest.Information: ATR의 길이를 받습니다.
CardCapabilities.ATR.Length: ATR의 길이를 포함합니다.

RDF_CARD_TRACKING

RDF_CARD_TRACKING 콜백 함수는 카드 삽입되거나 카드 판독기에서 제거될 때마다 추적하는 이벤트 처리기를 설치합니다. 스마트 카드 판독기 드라이버가 이 콜백 함수를 구현해야 합니다.

IOCTL_SMARTCARD_IS_PRESENT 요청을 받으면 드라이버 라이브러리는 스마트 카드 이미 있는지 확인합니다. 스마트 카드 있는 경우 드라이버 라이브러리는 STATUS_SUCCESS 상태 사용하여 요청을 완료합니다. 스마트 카드 없는 경우 드라이버 라이브러리는 판독기 드라이버의 스마트 카드 추적 콜백 함수를 호출하고 판독기 드라이버는 스마트 카드 찾기 시작합니다. 스마트 카드 추적을 시작한 후 드라이버 라이브러리는 요청을 STATUS_PENDING 상태 있는 것으로 표시합니다.

드라이버 라이브러리가 요청을 완료합니다.

WDM 디바이스 드라이버

해당 WDM 드라이버 라이브러리는 SmartcardExtension-OsData-NotificationIrp>>의 요청에 포인터를 추가합니다. 판독기 드라이버는 스마트 카드 삽입 또는 제거되었음을 감지하는 즉시 요청을 완료해야 합니다. 판독기 드라이버는 IoCompleteRequest를 호출하여 요청을 완료합니다. 그 후 판독기 드라이버는 SmartcardExtension -> OsData의 NotificationIrp 멤버를 NULL로 다시 설정하여 판독기 드라이버가 추가 스마트 카드 추적 요청을 수락할 수 있음을 드라이버 라이브러리에 알려야 합니다.

이 호출은 무기한 기간을 가질 수 있고 호출자가 완료되기 전에 요청을 종료할 수 있으므로 이 IRP를 취소 가능한 것으로 표시하는 것이 중요합니다.

MyDriverCardSupervision(
SmartcardExtension, 
OtherParameters)
//
//    This function is called whenever the card status changes
//    For example, the card has been inserted or the card has been removed
//
{
    if (SmartcardExtension->OsData->NotificationOverlappedData != NULL){

        SmartcardCompleteCardTracking(SmartcardExtension);
    }
    //
    // Do additional tasks
    //
}

RDF_IOCTL_VENDOR

RDF_IOCTL_VENDOR 콜백 함수는 공급업체별 IOCTL 작업을 수행합니다. 스마트 카드 판독기 드라이버가 이 콜백 함수를 구현하는 것은 선택 사항입니다.

입력에서 호출자는 함수에 다음 값을 전달해야 합니다.

SmartcardExtension->MajorIoControlCode: 공급업체별 IOCTL 코드를 포함합니다. 공급업체별 IOCTL 코드를 정의하는 방법에 대한 자세한 내용은 Winsmcrd.h 의 매크로 SCARD_CTL_CODE 참조하세요. 코드는 2048에서 4095 사이여야 합니다.
SmartcardExtension->IoRequest.RequestBuffer: 사용자의 입력 버퍼에 대한 포인터입니다.
SmartcardExtension->IoRequest.RequestBufferLength: 사용자 입력 버퍼의 크기(바이트)입니다.
SmartcardExtension->IoRequest.ReplyBuffer: 사용자의 출력 버퍼에 대한 포인터입니다.
SmartcardExtension->IoRequest.ReplyBufferLength: 사용자의 출력 버퍼 크기(바이트)입니다.
SmartcardExtension->IoRequest.Information: 요청에서 제공하는 값입니다. 반환된 바이트 수로 설정해야 합니다.

다른 모든 IOCTL과 마찬가지로 사용자 모드 애플리케이션은 DeviceIoControl 함수를 호출하여 공급업체에서 정의한 IOCTL을 스마트 카드 판독기 디바이스로 디스패치합니다. 그러나 IOCTL이 공급업체에 정의된 경우 애플리케이션은 먼저 "겹침"(즉, 비동기) 액세스를 위해 판독기 디바이스를 열어야 합니다. 또한 애플리케이션은 OVERLAPPED 구조를 정의하고 DeviceIoControl의 마지막 인수에서 시스템에 전달해야 합니다(OVERLAPPED 구조체는 Windows SDK 설명서에도 설명되어 있습니다.). 운영 체제가 드라이버의 I/O 컨트롤 디스패치 루틴을 호출하면 DIOCPARAMETERS 구조체를 드라이버에 전달합니다. DIOCPARAMETERS 구조체의 lpoOverlapped 멤버에는 OVERLAPPED 구조체에 대한 포인터가 포함되어 있습니다.

RDF_READER_SWALLOW RDF_READER_SWALLOW 콜백 함수는 스마트 카드 스마트 카드 판독기에 완전히 삽입될 때 발생하는 기계적 제비 기능을 수행합니다. 스마트 카드 판독기 드라이버가 이 콜백 함수를 구현하는 것은 선택 사항입니다.

RDF_SET_PROTOCOL

RDF_SET_PROTOCOL 콜백 함수는 삽입된 스마트 카드 대한 전송 프로토콜을 선택합니다. 스마트 카드 판독기 드라이버는 이 콜백 함수를 구현해야 합니다.

입력에서 호출자는 다음 값을 함수에 전달해야 합니다.

SmartcardExtension->MajorIoControlCode

IOCTL_SMARTCARD_SET_PROTOCOL 포함합니다.

SmartcardExtension->MinorIoControlCode

호출자가 허용하는 것보다 하나 이상의 프로토콜의 비트 OR을 포함합니다. 드라이버는 삽입된 스마트 카드 지원하는 프로토콜을 선택해야 합니다. T = 1 프로토콜은 T = 0 프로토콜보다 우선적으로 지정하는 것이 좋습니다.

값	의미
SCARD_PROTOCOL_RAW	원시 프로토콜을 선택합니다.
SCARD_PROTOCOL_T0	ISO T = 0 프로토콜을 선택합니다.
SCARD_PROTOCOL_T1	ISO T = 1 프로토콜을 선택합니다.

SmartcardExtension->IoRequest.ReplyBufferLength

회신 버퍼의 길이를 포함합니다.

SmartcardExtension->CardCapabilities.PtsData

PTS 요청을 수행하는 데 필요한 매개 변수를 포함합니다. 자세한 내용은 PTS_DATA.

요청은 다음 값을 반환합니다.

SmartcardExtension->IoRequest.ReplyBuffer: 선택한 프로토콜을 포함합니다.
SmartcardExtension->IoRequest.Information: sizeof(ULONG)로 설정합니다.

호출자는 허용되는 프로토콜의 마스크를 제공할 수 있습니다. 드라이버의 설정 프로토콜 콜백 루틴은 마스크의 프로토콜 중 하나를 선택하고 SmartcardExtension->IoRequest.ReplyBuffer에서 선택한 프로토콜을 반환합니다.

RDF_TRANSMIT

RDF_TRANSMIT 콜백 함수는 데이터 전송을 수행합니다. 스마트 카드 판독기 드라이버는 이 콜백 함수를 구현해야 합니다.

입력에서 호출자는 다음 값을 함수에 전달해야 합니다.

SmartcardExtension->MajorIoControlCode: IOCTL_SMARTCARD_TRANSMIT 포함합니다.
SmartcardExtension->IoRequest.RequestBuffer: SCARD_IO_REQUEST 구조체에 대한 포인터와 카드 전송할 데이터입니다.
SmartcardExtension->IoRequest.RequestBufferLength: 카드 전송할 바이트 수입니다.
SmartcardExtension->IoRequest.ReplyBufferLength: 회신 버퍼의 크기(바이트)입니다.

요청은 다음 값을 반환합니다.

SmartcardExtension->IoRequest.ReplyBuffer: SCARD_IO_REQUEST 구조를 수신하는 버퍼에 대한 포인터와 카드 결과입니다.
SmartcardExtension->IoRequest.Information: 스마트 카드 반환된 실제 바이트 수와 SCARD_IO_REQUEST 구조체의 크기를 받습니다. SCARD_IO_REQUEST 구조체에 대한 정의는 IOCTL_SMARTCARD_TRANSMIT 참조하세요.

이 함수가 호출되면 SmartcardExtension->IoRequest.RequestBuffer 는 SCARD_IO_REQUEST 구조와 전송할 데이터를 가리킵니다.

typedef struct _SCARD_IO_REQUEST{
  DWORD  dwProtocol;   // Protocol identifier
  DWORD  cbPciLength;  // Protocol Control Information Length
} SCARD_IO_REQUEST, *PSCARD_IO_REQUEST, *LPSCARD_IO_REQUEST;

dwProtocol 멤버는 IOCTL_SMARTCARD_SET_PROTOCOL 호출에 의해 반환되는 프로토콜 식별자를 포함해야 합니다.

cbPciLength 멤버는 SCARD_IO_REQUEST 구조체의 크기(바이트)를 포함합니다. 이 구조체의 크기는 일반적으로 8바이트입니다.

SCARD_IO_REQUEST 구조 다음에는 (프로토콜) 데이터를 사용하여 카드 전송합니다. 전송에 사용할 프로토콜에 따라 라이브러리는 여러 지원 기능을 제공합니다. 이러한 지원 함수에 대한 자세한 내용은 SmartcardT0Request(WDM) 및 SmartcardT1Request(WDM)를 참조하세요.

RequestBuffer 및 ReplyBuffer는 동일한 시스템 버퍼를 가리킵니다. 라이브러리 함수 SmartcardxxRequest 및 SmartcardxxReply를 사용하는 경우 입력 버퍼를 덮어쓰지 않습니다. 이러한 함수를 사용하지 않는 경우 전송을 시작하기 전에 RequestBuffer 의 복사본을 만듭니다.

SCARD_IO_REQUEST 구조체를 ReplyBuffer 매개 변수에 복사한 다음 카드 받은 데이터를 복사해야 합니다. 다시 SmartcardxxRequest 및 SmartcardxxReply 함수를 사용하는 경우 라이브러리는 구조체를 복사합니다.

요구 사항

요구 사항	값
헤더	smclib.h(Smclib.h 포함)

다음을 통해 공유

SMARTCARD_EXTENSION 구조체(smclib.h)

구문

멤버

설명

요구 사항

피드백

추가 리소스