Overzicht van Smartcard "Minidriver"

Artikel
2025-04-05

De kaartspecifieke minidriver is de laagste logische interfacelaag in de Basis-CSP/KSP. Met deze minidriver kunnen de Base CSP/KSP en toepassingen rechtstreeks communiceren met een specifiek type kaart met behulp van SCRM.

De kaart-minidriver is een DLL die een specifieke set API's exporteert zoals in deze specificatie gedefinieerd. Elke aanroep naar de kaart minidriver bevat een aanwijzer naar een CARD_DATA structuur die contextinformatie biedt. Deze contextinformatie bevat enkele statusinformatie naast een tabel met functiepointers die worden gebruikt om de communicatie tussen de bovenste laag en de kaart minidriver te vergemakkelijken.

Zie CardAcquireContext voor meer informatie over deze contextstructuur.

Het headerbestand Cardmod.h C bevat aanvullende informatie die relevant is voor deze specificatie. Dit bestand bevat de prototypen en structuren van de functie die door microsoft smartcard minidriver-API worden opgegeven. Deze API is beschikbaar via de Microsoft Cryptographic Provider Development Kit (CPDK).

algemene ontwerprichtlijnen

De minidriver voor kaarten moet worden gedistribueerd als een DLL.
Elke kaartspecifieke bewerking moet één atomische transactie implementeren, behalve anders vermeld.
Er moet een gestandaardiseerde set bewerkingen op macroniveau worden geïmplementeerd.
De bestandssysteemobjecten van de logische kaart moeten worden toegewezen aan hun fysieke locaties.
Kaarten die op dit nieuwe model zijn gebaseerd, moeten dynamisch bestanden kunnen vergroten die op de kaart zijn opgeslagen. Voor kaarten die alleen-lezen zijn en deze richtlijn niet kunnen volgen, moet de minidriver de specifieke richtlijnen volgen voor alleen-lezenkaarten die in deze specificatie zijn beschreven.
De minidriver importeert definities van de CPDK. Het minidriver-headerbestand (Cardmod.h) bevat Bcrypt.h voor dit doel. Implementaties moeten deze afhankelijkheid oplossen via projectinstellingen van Microsoft Visual Studio voor het compileren van minidrivers.
Vereisten voor beveiligde processen voor invoegtoepassingen of stuurprogramma's
- Voor een LSA-invoegtoepassing of een stuurprogramma om met succes als beveiligd proces te laden, moet het voldoen aan de volgende criteria:
  - Handtekeningverificatie
    
    o Beveiligde modus vereist dat elke invoegtoepassing die in de LSA is geladen, digitaal moet worden ondertekend met een Microsoft-handtekening. Daarom kunnen alle niet-ondertekende of ondertekende invoegtoepassingen van derden niet worden geladen in LSA. Voorbeelden van dergelijke invoegtoepassingen zijn smartcardstuurprogramma's, crypto-invoegtoepassingen, wachtwoordfilters, enzovoort.
    
    o LSA-invoegtoepassingen die stuurprogramma's (zoals smartcardstuurprogramma's) zijn, moeten digitaal worden ondertekend.
    
    Notitie Het Windows-programma voor hardwarecompatibiliteit biedt de enige methode voor het digitaal ondertekenen van stuurprogramma's voor Windows. Het is dus belangrijk om naar de website te verwijzen voor deze informatie.
- Naleving van SDL-procesrichtlijnen (Microsoft Security Development Lifecycle).
  - Alle invoegtoepassingen moeten ook voldoen aan de toepasselijke gedeelten van het onderwerp Microsoft Security Development Lifecycle (SDL) - Procesrichtlijnen . Zie bijvoorbeeld Geen gedeelde secties, beschreven in het SDL-proces in bijlage G.
  - Zelfs als de invoegtoepassingen correct zijn ondertekend met een Microsoft-handtekening, kan niet-naleving van het SDL-proces leiden tot een fout bij het laden van de invoegtoepassingen.

Zie Microsoft Security Development Lifecycle (SDL) – Procesrichtlijnen voor meer informatie over SDL.

En voor een discussie over richtlijnen voor ontwikkelaars raadpleegt u Richtlijnen voor ontwikkelaars

Transactiebeheer

Een kaartminidriver moet ervan uitgaan dat transacties worden verwerkt door de aanroeper, als deze SCRM gebruikt voor toegang tot de kaart.
De kaart-minidriver kan aannemen dat alle toegangspunten behalve CardDeleteContext worden aangeroepen terwijl de kaarttransactie wordt vastgehouden. Dit kan niet worden aangenomen in CardDeleteContext omdat de kaart mogelijk is verwijderd of wordt aangeroepen als onderdeel van een opschoonprocedure.
Er kunnen meerdere contexten bestaan in één proces. Het aanroepen van CardDeleteContext op het ene proces mag niet voorkomen dat de andere context functioneert.
Het afhandelen van de authenticatiestatus van de kaart is ook de verantwoordelijkheid van de aanroeper, niet de kaartminidriver.

Verdragen

Tekenreeksen: UNICODE en ANSI

Op toepassingsniveau worden tekenreeksen meestal aangetroffen als elementen van de gebruikersinterface, hetzij direct of indirect. Daarom moeten ze meestal worden gelokaliseerd (vertaald in de taal van de gebruiker), zodat ze kunnen worden begrepen. Daarom is het tekenreekstype dat de meeste toepassingen gebruiken double-byte (oftewel UNICODE) om verschillende tekensets te accommoderen.

Smartcards werken echter met minimale resources en met zeer weinig opties voor het noemen van mappen, bestanden, gebruikers enzovoort. De tekenset voor tekenreeksen is ANSI met één byte, wat een compactere weergave van tekenreeksgegevens biedt.

Daarom wordt verwacht dat tekenreeksbuffers van en naar de kaartminidriver ANSI met één byte zijn, en dat conversies naar en van dit tekentype buiten de kaartminidriver worden uitgevoerd.

Foutafhandeling

Om consistente foutafhandeling, reactie op fouten en consistent gedrag voor kaart minidrivers te garanderen, moeten de volgende conventies worden gevolgd:

Alle NULL- en ongeldige parameters, waarbij ook ongeldige vlaggen, retourneren SCARD_E_INVALID_PARAMETER.
Alle onjuiste PIN-codes of pogingen met de verkeerde sleutel resulteren in SCARD_W_WRONG_CHV.
Als er een algemene fout optreedt, retourneren de API's SCARD_E_UNEXPECTED.

Bovendien moeten de fouten die worden geretourneerd door de functies die in de volgende secties worden beschreven, afkomstig zijn van de categorie SCARD_* (winerror.h). U wordt bijvoorbeeld aangeraden SCARD_E_INVALID_PARAMETER (0x80100004) te gebruiken in plaats van ERROR_INVALID_PARAMETER (0x00000057).

Notitie Als een bestand niet kan worden gelezen van een kaart vanwege I/O-fouten, of een ander onherstelbaar gegevensprobleem dat niet gerelateerd is aan het bestaan van dat bestand op de kaart, raadt Microsoft aan om SCARD_E_COMM_DATA_LOST te retourneren.

Het retourneren van SCARD_E_FILE_NOT_FOUND als een paraplufoutcode in dergelijke situaties, biedt misleidende foutopsporingsinformatie.

Verificatie en autorisatie

Vanaf versie 6 breidt de minidriver-interface het concept van een pincode uit tot meer dan een traditionele alfanumerieke tekenreeks. Zie 'SECRET_TYPE (opsomming)' verderop in deze specificatie voor meer informatie.

Geheugentoewijzingen verwerken

Alle API-elementen in deze specificatie die intern geheugenbuffers toewijzen, doen dit door PFN_CSP_ALLOC aan te roepen. Hierdoor moeten dergelijke geheugenbuffers worden vrijgemaakt door PFN_CSP_FREE aan te roepen.

Elke geheugentoewijzing die de minidriver van de kaart uitvoert, moet worden uitgevoerd met behulp van PFN_CSP_ALLOC of PFN_CSP_REALLOC.

Cachebeheer

De kaartinterfacelaag in de basis-CSP/KSP implementeert een gegevenscache om de hoeveelheid gegevens te minimaliseren die naar de kaart moet worden geschreven of gelezen. De gegevenscache wordt ook beschikbaar gesteld voor de kaart minidriver voor gebruik via functiepointers in de CARD_DATA structuur, en de kaart minidriver moet deze aanwijzers gebruiken om de prestaties te verbeteren door de interne gegevensbestanden die op de kaart zijn opgeslagen in de cache op te slaan.

Voor caching van gegevens is schrijftoegang tot de kaart vereist om cache-versheidsmeters op de kaart permanent vast te leggen. De minidriver kan gegevenscache beheren als het schrijven van gegevens naar de kaart niet haalbaar is.

Zie de definitie van de eigenschap CP_CARD_CACHE_MODE in CardGetProperty verderop in deze specificatie voor meer informatie over het beheren van gegevenscache.

Verplichte versiecontrole

Alle kaartminidrivers moeten versiecontroles implementeren. De versie van de CARD_DATA-structuur is een onderhandeling tussen de versie die de beller wil ondersteunen en de versie die de kaart minidriver daadwerkelijk kan ondersteunen.

CARD_DATA versiecontroles

Definieer de minimale versie als de minimale versie van de contextstructuur van de kaartminidriver (dat wil zeggen, de "CARD_DATA"-structuur) die wordt ondersteund en definieer de huidige versie als het niveau waarvoor deze kaartminidriver is ontworpen en waarvoor alle kaartminidriver-setstructuuritems gegarandeerd geldig zijn bij een succesvolle uitvoer van CardAcquireContext. De huidige versie moet groter dan of gelijk zijn aan de minimale versie en kleiner dan of gelijk aan CARD_DATA_CURRENT_VERSION, die is gedefinieerd in Cardmod.h.

Wanneer de aanroepende toepassing CardAcquireContext aanroept, wordt de gewenste versie opgegeven die de toepassing wil laden. Deze aangevraagde versie wordt ingesteld in het dwVersion-lid in de CARD_DATA structuur.

Als de aangevraagde versie kleiner is dan de minimale versie die door de minidriver van de kaart wordt ondersteund, moet CardAcquireContext een fout retourneren die niet overeenkomt met de revisie (zie de volgende voorbeeldcode).

Als de aangevraagde versie minstens zo groot is als de minimale versie, moet de minidriver van de kaart het dwVersion-lid instellen op de hoogste versie die het kan ondersteunen dat kleiner dan of gelijk is aan de aangevraagde versie.

In de volgende voorbeeldcode wordt het verwachte gedrag van de minidriver van de kaart getoond bij het controleren van de versie. Dit wordt verondersteld in de hoofdtekst van de functie CardAcquireContext te staan. pCardData is een aanwijzer naar de CARD_DATA structuur die in deze aanroep is doorgegeven.

#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);

Notitie Als de versie die de minidriver van de kaart retourneert, niet geschikt is voor de aanroepende toepassing, is het de verantwoordelijkheid van de aanroepende toepassing om dit op de juiste manier af te handelen.

Nadat dwVersion is ingesteld in de aanroep naar CardAcquireContext, wordt ervan uitgegaan dat deze niet wordt gewijzigd door de aanroeper of de kaartminidriver terwijl deze zich in dezelfde context bevindt.

Andere structuurversiecontroles

Voor andere versiestructuren en andere API-methoden voor kaart-minidriver is de verwerking van versies hetzelfde als voor de CARD_DATA structuur, met één uitzondering. Als de API-methode wordt aangeroepen met een structuur die een dwVersion-lid bevat dat is ingesteld op 0, moet dit worden behandeld als een dwVersion-waarde van 1.

De functies CardRSADecrypt en CardSignData hebben speciale verwerking voor versienummers voor de gegevensstructuren die worden doorgegeven.

Delen via