структура SMARTCARD_EXTENSION (smclib.h)

Статья
02/07/2025

Структура 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

Указатель на данные в запросе ввода-вывода пользователя, который будет отправлен на карту.

IoRequest.RequestBufferLength

Указывает количество байтов для отправки на карточку.

IoRequest.ReplyBuffer

Указатель на буфер, содержащий данные, возвращаемые запросом ввода-вывода.

IoRequest.ReplyBufferLength

Указывает количество байтов данных, возвращаемых запросом ввода-вывода.

MajorIoControlCode

Содержит основной код элемента управления ввода-вывода.

MinorIoControlCode

Содержит дополнительный код элемента управления ввода-вывода.

OsData

Содержит сведения, относящиеся к операционной системе и типу драйвера.

ReaderCapabilities

Содержит возможности средства чтения с клавиатуры.

ReaderExtension

Содержит данные, относящиеся к средству чтения смарт-карт.

SmartcardReply

Содержит данные, поступающие от средства чтения.

SmartcardRequest

Содержит текущую команду и данные, отправляемые смарт-карте.

T0

Содержит данные для использования с протоколом T=0.

T1

Содержит данные, используемые с протоколом T=1.

PerfInfo

Reserved[25 - sizeof(PPERF_INFO)]

Зарезервировано для использования системы.

Замечания

Эта структура передается всем функциям обратного вызова.

Отдельные функции обратного вызова определяются рядом константных значений, которые следует использовать в качестве индексов в массив ReaderFunction.

Индекс Описание

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 в SmartcardExtension->CardCapabilities.ATR.Buffer , чтобы библиотека может проанализировать ATR.
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, после чего драйвер читателя должен задать элемент NotificationIrp участника SmartcardExtension —> OsData обратно в 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 для конкретного поставщика см. в SCARD_CTL_CODE макроса в Winsmcrd.h. Обратите внимание, что код должен находиться в диапазоне от 2048 до 4095.
SmartcardExtension->IoRequest.RequestBuffer: Указатель на входной буфер пользователя.
SmartcardExtension->IoRequest.RequestBufferLength: Размер входного буфера пользователя в байтах.
SmartcardExtension->IoRequest.ReplyBuffer: Указатель на выходной буфер пользователя.
SmartcardExtension->IoRequest.ReplyBufferLength: Размер в байтах выходного буфера пользователя.
SmartcardExtension->IoRequest.Information: Значение, предоставленное запросом. Необходимо задать число возвращаемых байтов.

Как и во всех остальных ioCTLs, приложение в пользовательском режиме отправляет определяемый поставщиком IOCTL на устройство чтения смарт-карт путем вызова функции deviceIoControl. Однако, если IOCTL определен поставщиком, приложение должно сначала открыть устройство чтения для "перекрывающегося" (то есть асинхронного) доступа. Приложение также должно определить структуру OVERLAPPED и передать ее в систему в последнем аргументе DeviceIoControl (Структура OVERLAPPED также описана в документации по Пакету SDK для Windows). Когда операционная система вызывает подпрограмму диспетчера ввода-вывода драйвера, она передает структуру DIOCPARAMETERS драйверу. Элемент lpoOverlapped в структуре DIOCPARAMETERS содержит указатель на структуру OVERLAPPED.

RDF_READER_SWALLOW Функция обратного вызова RDF_READER_SWALLOW выполняет механический глоток, что происходит, когда смарт-карта полностью вставляется в средство чтения смарт-карт. Это необязательно для драйверов чтения смарт-карт для реализации этой функции обратного вызова.

RDF_SET_PROTOCOL

Функция обратного вызова RDF_SET_PROTOCOL выбирает протокол передачи для вставленной смарт-карты. Драйверы средства чтения смарт-карт должны реализовать эту функцию обратного вызова.

При входе вызывающий объект должен передать следующие значения функции:

SmartcardExtension—>MajorIoControlCode

Содержит IOCTL_SMARTCARD_SET_PROTOCOL.

SmartcardExtension—>MinorIoControlCode

Содержит побитовое ИЛИ одного или нескольких протоколов, чем вызывающий объект принимает. Драйвер должен выбрать протокол, поддерживаемый вставленной смарт-картой. Рекомендуется, чтобы протокол 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 и SmartcardxReply, вы не перезаписываете входной буфер. Если эти функции не используются, создайте копию RequestBuffer перед началом передачи.

Необходимо скопировать структуру SCARD_IO_REQUEST в параметр ReplyBuffer, а затем данные, полученные из карточки. Опять же, если вы используете функции SmartcardxxRequest и функции SmartcardxxReply, библиотека будет копировать структуру.

Требования

Требование	Ценность
заголовка	smclib.h (include Smclib.h)

Поделиться через

структура SMARTCARD_EXTENSION (smclib.h)

Синтаксис

Члены

Замечания

Требования

Обратная связь

Дополнительные ресурсы