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 配列のインデックスとして使用する必要がある一連の定数値によって識別されます。

インデックス説明

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

呼び出し元が受け入れる 1 つ以上のプロトコルのビットごとの OR を含みます。ドライバーは、挿入されたスマートカードがサポートするプロトコルを選択する必要があります。 T = 0 プロトコルよりも T = 1 プロトコルが優先されることをお勧めします。

値	意味
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) に設定します。

呼び出し元は、許容されるプロトコルのマスクを指定できます。ドライバーのセットプロトコルコールバックルーチンは、マスク内のプロトコルの 1 つを選択し、 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 関数を使用すると、ライブラリによって構造がコピーされます。

要件

要件	値
Header	smclib.h (Smclib.h を含む)

次の方法で共有

SMARTCARD_EXTENSION 構造体 (smclib.h)

構文

メンバー

注釈

要件

フィードバック

その他のリソース