Přehled Minidriveru čipových karet

Článek
2025-04-09

Karetní specifický minidriver je nejnižší logická vrstva v základní vrstvě CSP/KSP. Tento minidriver umožňuje CSP/KSP základní úrovně a aplikacím, pracovat přímo s konkrétním typem karty pomocí SCRM.

Minidriver karty je knihovna DLL, která exportuje konkrétní sadu rozhraní API definovanou v této specifikaci. Každé volání minidriveru karty obsahuje ukazatel na CARD_DATA strukturu, která poskytuje kontextové informace. Tyto kontextové informace poskytují kromě tabulky ukazatelů funkce některé informace o stavu, které slouží k usnadnění komunikace mezi horní vrstvou a minidriverem karty.

Další informace o této kontextové struktuře naleznete v tématu CardAcquireContext.

Soubor hlavičky Cardmod.h C poskytuje další informace, které jsou relevantní pro tuto specifikaci. Tento soubor obsahuje prototypy a struktury funkcí, které určuje rozhraní API minidriveru čipových karet Microsoftu. Toto rozhraní API je k dispozici prostřednictvím sady Microsoft Cryptographic Provider Development Kit (CPDK).

obecné pokyny k návrhu

Minidriver karty by měl být distribuován jako knihovna DLL.
Každá operace specifická pro kartu by měla implementovat jednotlivou atomickou transakci, s výjimkou případů, kdy je uvedeno jinak.
Je třeba implementovat standardizovanou sadu makroúrovňových operací.
Objekty systému souborů logické karty by měly být mapovány na jejich fyzické umístění.
Karty založené na tomto novém modelu by měly být schopné dynamicky zvětšovat všechny soubory uložené na kartě. U karet, které jsou jen pro čtení a nemohou postupovat podle těchto pokynů, by minidriver měl dodržovat konkrétní pokyny pro karty jen pro čtení, které byly podrobně popsány v této specifikaci.
Minidriver importuje definice z CPDK. Hlavičkový soubor minidriveru (Cardmod.h) obsahuje pro tento účel Bcrypt.h . Implementace musí tuto závislost vyřešit prostřednictvím nastavení projektu sady Microsoft Visual Studio pro kompilaci minidriverů.
Požadavky na chráněný proces pro moduly plug-in nebo ovladače
- Aby se modul plug-in LSA nebo ovladač úspěšně načíst jako chráněný proces, musí splňovat následující kritéria:
  - Ověření podpisu
    
    O Chráněný režim vyžaduje, aby všechny moduly plug-in načtené do LSA byly digitálně podepsané podpisem Microsoftu. Nepodepsané zásuvné moduly nebo zásuvné moduly podepsané třetí stranou se v LSA proto nenačtou. Příkladem takových modulů plug-in jsou ovladače čipových karet, kryptografické moduly plug-in, filtry hesel atd.
    
    o Moduly plug-in LSA, které jsou ovladači (například ovladače čipových karet), musí být digitálně podepsané.
    
    PoznámkaProgram kompatibility hardwaru s Windows nabízí jedinou metodu pro digitální podepisování ovladačů pro Windows. Proto je důležité odkazovat na webové stránky pro tyto informace.
- Dodržování pokynů k procesům SDL (Microsoft Security Development Lifecycle).
  - Všechny moduly plug-in musí také vyhovovat příslušným částem tématu Microsoft Security Development Lifecycle (SDL) – Pokyny pro proces. Například viz Žádné sdílené oddíly popsané v procesu SDL v dodatku G.
  - I když jsou moduly plug-in správně podepsané podpisem Microsoftu, může nekompatibilita s procesem SDL způsobit selhání načtení modulů plug-in.

Informace o SDL naleznete v tématu Microsoft Security Development Lifecycle (SDL) – Pokyny k procesu..

A diskuzi o pokynech pro vývojáře najdete v tématu Pokyny pro vývojáře.

Správa transakcí

Minidriver karty by měl považovat za samozřejmé, že volající zpracovává transakce, pokud pro přístup k kartě používá SCRM.
Minidriver karty může předpokládat, že všechny vstupní body kromě CardDeleteContext jsou volány během držení transakce karty. Toto nelze předpokládat v CardDeleteContext, protože karta mohla být odebrána nebo je to voláno jako součást procedury vyčištění.
V jednom procesu může existovat více kontextů. Volání CardDeleteContext v jednom procesu by nemělo bránit fungování druhého kontextu.
Za zpracování stavu ověření karty zodpovídá volající, ne minidriver karty.

Konvence

Řetězce: UNICODE a ANSI

Na úrovni aplikace jsou řetězce obecně zjištěny jako prvky uživatelského rozhraní, a to buď přímo, nebo nepřímo. Proto je obvykle nutné je lokalizovat (přeložit do jazyka uživatele), aby jim bylo možné porozumět. Z tohoto důvodu většina aplikací používá řetězcový typ dvojbajtový (tj. UNICODE), aby vyhověla různým znakovým sadám.

Čipové karty ale pracují s minimálními prostředky a s velmi málo možnostmi, jak pojmenovat adresáře, soubory, uživatele atd. Znaková sada pro řetězce je jednobajtová ANSI, která poskytuje kompaktní reprezentaci řetězcových dat.

Proto se očekává, že řetězcové vyrovnávací paměti pro minidriver karty i z něj budou jednobajtové ANSI a převody na a z tohoto typu znaku je třeba provést mimo minidriver karty.

Zpracování chyb

Aby se zajistilo konzistentní zpracování chyb, reakce na selhání a konzistentní chování minidriverů karet, měly by se dodržovat následující konvence:

Všechny parametry, které jsou NULL nebo neplatné, včetně chybných příznaků, vrátí SCARD_E_INVALID_PARAMETER.
Při zadání nesprávného PIN kódu nebo pokusu s nesprávným klíčem se vrátí SCARD_W_WRONG_CHV.
Pokud dojde k obecné chybě, rozhraní API vrátí SCARD_E_UNEXPECTED.

Kromě toho by chyby vrácené funkcemi, které jsou popsány v následujících částech, měly být z kategorie SCARD_* (winerror.h). Doporučujeme například místo ERROR_INVALID_PARAMETER (0x00000057) používat SCARD_E_INVALID_PARAMETER (0x80100004).

Poznámka Pokud soubor nelze načíst z karty z důvodu vstupně-výstupních chyb nebo jiného neopravitelného problému s daty, který nesouvisí se skutečnou existenci tohoto souboru na kartě, doporučuje Společnost Microsoft vrátit SCARD_E_COMM_DATA_LOST.

Vrácení chybového kódu SCARD_E_FILE_NOT_FOUND jako obecného kódu v těchto situacích poskytuje zavádějící informace při ladění.

Ověřování a autorizace

Počínaje verzí 6 rozšiřuje rozhraní minidriveru koncept KÓDU PIN na více než jen tradiční alfanumerický řetězec. Další informace najdete v části "SECRET_TYPE (výčet)" dále v této specifikaci.

Zpracování přidělení paměti

Všechny prvky rozhraní API v této specifikaci, které interně přidělují vyrovnávací paměti, to činí voláním funkce PFN_CSP_ALLOC. Z tohoto důvodu musí být všechny takové vyrovnávací paměti uvolněny voláním PFN_CSP_FREE.

Přidělení paměti, kterou minidriver karty provádí, by mělo být provedeno pomocí PFN_CSP_ALLOC nebo PFN_CSP_REALLOC.

Cacheování

Vrstva Rozhraní karty v základním CSP/KSP implementuje mezipaměť dat, aby se minimalizovalo množství dat, která se musí zapisovat nebo číst z karty. Mezipaměť dat je také k dispozici pro minidriver karty, který může používat prostřednictvím ukazatelů funkcí ve struktuře CARD_DATA a minidriver karty by měl tyto ukazatele použít ke zvýšení výkonu ukládáním interních datových souborů uložených na kartě do mezipaměti.

Ukládání dat do mezipaměti vyžaduje přístup k zápisu na kartu, aby se zachovaly čítače aktuálnosti mezipaměti na kartě. Minidriver může řídit ukládání dat do mezipaměti, pokud zápis dat na kartu není proveditelný.

Další informace o tom, jak řídit ukládání dat do mezipaměti, naleznete v definici vlastnosti CP_CARD_CACHE_MODE v CardGetProperty dále v této specifikaci.

Povinná kontrola verzí

Všichni minidriveři karet musí implementovat kontroly verzí. Verze struktury CARD_DATA je vyjednávání mezi verzí, kterou volající chce podporovat, a verzí, kterou může minidriver karty skutečně podporovat.

kontroly verzí CARD_DATA

Definujte minimální verzi jako minimální verzi struktury kontextu minidriveru karty (tj. CARD_DATA struktura), která je podporovaná, a definujte aktuální verzi jako úroveň, pro kterou byl tento minidriver navržen a pro kterou je zaručena platnost všech položek struktury sady karta-minidriver po úspěšném návratu z CardAcquireContext. Aktuální verze musí být větší nebo rovna minimální verzi a menší nebo rovna CARD_DATA_CURRENT_VERSION, která je definována v cardmod.h.

Když volající aplikace volá CardAcquireContext, určuje požadovanou verzi, kterou chce načíst. Tato požadovaná verze je nastavena v členu dwVersion ve struktuře CARD_DATA .

Pokud je požadovaná verze menší než minimální verze, kterou minidriver karty podporuje, musí CardAcquireContext vrátit chybu neshody revizí (viz následující ukázkový kód).

Pokud je požadovaná verze rovna nebo větší než minimální verze, měl by minidriver karty nastavit člen dwVersion na nejvyšší verzi, kterou může podporovat a která je menší nebo rovna požadované verzi.

Následující ukázkový kód ukazuje očekávané chování minidriveru karty při kontrole verze. Předpokládá se, že se nachází v těle funkce CardAcquireContext . pCardData je ukazatel na CARD_DATA strukturu předanou do tohoto volání.

#define MINIMUM_VERSION_SUPPORTED (4)
#define CURRENT_VERSION_SUPPORTED (7)

    // The lowest supported version is 4.
    If (pCardData->dwVersion < MINIMUM_VERSION_SUPPORTED)
    {
        dwError = (DWORD) ERROR_REVISION_MISMATCH;
        goto Ret;
    }

    // Set the version to what we support, but don’t exceed the
    // requested version
    pCardData->dwVersion =
       min(pCardData->dwVersion, CURRENT_VERSION_SUPPORTED);

Poznámka Pokud verze, kterou minidriver karty vrátí, není vhodná pro účely volajícího programu, je zodpovědností tohoto programu, aby to správně zpracoval.

Po nastavení dwVersion ve volání CardAcquireContext předpokládejme, že jej volající ani minidrivem karty nezmění, dokud zůstane ve stejném kontextu.

Kontroly verzí jiných struktur

U jiných struktur s verzemi a jiných metod rozhraní API minidriveru karet je zpracování verzí stejné jako u struktury CARD_DATA s jednou výjimkou. Pokud je volána metoda rozhraní API se strukturou, která obsahuje člen dwVersion , který je nastaven na hodnotu 0, musí být považován za hodnotu dwVersion 1.

Funkce CardRSADecrypt a CardSignData mají speciální zpracování čísel verzí pro datové struktury, které jsou předány.

Sdílet prostřednictvím