FPdfPkcs11 - PDFium Delphi Component

Unit: FPdfPkcs11

PKCS#11-signeringsbackend för PAdES, som löser ett signerarcertifikat och dess privata nyckel från en token och producerar SignerInfo-signaturen inne i tokenen

Syntax

EPdfPkcs11Error = class(Exception);

TPdfPkcs11Options = record
  ModulePath: string;
  SlotId: UInt64;
  UseSpecificSlot: Boolean;
  Pin: string;
  CertificateLabel: string;
  class function Default: TPdfPkcs11Options; static;
end;

TPdfPkcs11SignerProvider = class(TInterfacedObject, IPadesSignerProvider,
  IPdfPkcs11SignerProvider)
  constructor Create(const Options: TPdfPkcs11Options);
  destructor Destroy; override;
  function BackendName: string;
  function Resolve(const Options: TPadesSignerOptions): TPadesResolvedSigner;
  function EnumerateSlots: TPdfPkcs11Slots;
  function EnumerateCertificates(SlotID: UInt64): TPdfPkcs11Certificates;
  procedure CloseProtectedSessions;
end;

function Pkcs11ModuleAvailable(const ModulePath: string): Boolean;
function Pkcs11ModuleVersion(const ModulePath: string): string;
function Pkcs11AbiLayout: string;
function ConfigurePkcs11SignerProvider(
  const Options: TPdfPkcs11Options): IPdfPkcs11SignerProvider;

Description

FPdfPkcs11 är den portabla PAdES-signeringsbackenden och motparten till Windows CNG-backenden. Den löser ett signerarcertifikat och dess privata nyckel från en PKCS#11-token och returnerar därefter en TPadesResolvedSigner vars ICmsSigner producerar SignerInfo-signaturen via tokenen, så att nyckeln aldrig lämnar den

Modulen läses in vid körning efter sökväg - opensc-pkcs11.so, libsofthsm2.so, en vendor-DLL - så inget länkas vid bygget och en saknad modul rapporteras i stället för att vara ödesdiger. Endast C_GetFunctionList slås upp vid namn; alla andra ingångspunkter hämtas ur den funktionstabell den returnerar, vilket är hur standarden avser att en modul ska nås

ConfigurePkcs11SignerProvider bygger en TPdfPkcs11SignerProvider från ett TPdfPkcs11Options-värde och installerar den som aktiv PAdES-signerarbackend och returnerar det IPdfPkcs11SignerProvider-gränssnitt som också bär tokenuppräkningsmetoderna

Pkcs11ModuleAvailable och Pkcs11ModuleVersion rapporterar huruvida en viss modul läses in och exponerar en användbar funktionstabell, så att en applikation kan avgöra vid start om tokensignering är möjlig på den här maskinen. Inlästa moduler cachas efter sökväg, eftersom standarden endast tillåter en initiering per process och modul

Resolve väljer certifikatet via TPadesSignerOptions.CertificateThumbprint när ett anges och annars via CertificateLabel, och lokaliserar därefter det privata nyckelobjekt som bär samma token-identifierare som certifikatet. Certifikatets nyckelalgoritm avgör algoritmfamiljen: en EC-nyckel signerar med ECDSA och dess råa signatur kodas om som den DER SEQUENCE som CMS förväntar sig, medan en RSA-nyckel följer det begärda padding-schemat

EnumerateSlots och EnumerateCertificates betjänar urvalsgränssnitt och låter en applikation lista de slots en modul rapporterar och de certifikat en vald slot håller innan något signeringsalternativ är fastställt

Functions

Function	Description
`Pkcs11ModuleAvailable`	Returnerar True när modulen på den angivna sökvägen läses in och exponerar en användbar funktionstabell
`Pkcs11ModuleVersion`	Returnerar versionssträngen som modulen rapporterar, eller en tom sträng när modulen inte läses in
`Pkcs11AbiLayout`	Returnerar ABI-layouten detta bygge löste ut, som `ulong=<n> attr=<n> pss=<n> table=<n>`
`ConfigurePkcs11SignerProvider`	Bygger en provider från de angivna alternativen, installerar den som PAdES-signerarbackend och returnerar den som `IPdfPkcs11SignerProvider`

Types

Type	Purpose
`EPdfPkcs11Error`	Undantag som kastas när ingen modulsökväg är konfigurerad, modulen inte kan läsas in, ett token-anrop misslyckas eller inget matchande certifikat eller privat nyckel hittas
`TPdfPkcs11Options`	Post som namnger modulen, slotten, PIN:en och certifikatet som providern arbetar med
`TPdfPkcs11SignerProvider`	Providerklass som implementerar `IPadesSignerProvider` och `IPdfPkcs11SignerProvider` ovanpå en PKCS#11-modul

TPdfPkcs11Options fields

Field	Description
`ModulePath`	Sökväg till PKCS#11-modulen; krävs, eftersom vilken modul som betjänar en token är ett driftbeslut och det inte finns någon användbar standard
`SlotId`	Token-slot att öppna, respekteras endast när `UseSpecificSlot` är True
`UseSpecificSlot`	Lämna False för att ta första slot som rapporterar en token närvarande
`Pin`	Användar-PIN; providern rensar sin egen kopia när tokenen har konsumerat den, och anroparen behåller ansvaret för strängens livstid
`CertificateLabel`	Valfri objektetikett för certifikatet att signera med, används endast när `TPadesSignerOptions.CertificateThumbprint` är tom
`Default`	Statisk fabriksmetod som returnerar alternativ med en tom modulsökväg, slot 0, automatiskt urval av slot samt ingen PIN eller etikett

TPdfPkcs11SignerProvider members

Member	Description
`Create`	Konstruerar providern från ett `TPdfPkcs11Options`-värde; själva modulen öppnas vid första användning
`Destroy`	Stänger öppna tokensessioner innan instansen frigörs
`BackendName`	Returnerar backend-namnet, med modulens filnamn tillagt när en modulsökväg är konfigurerad
`Resolve`	Löser `TPadesSignerOptions` till en `TPadesResolvedSigner` som håller tokensigneraren och signerarcertifikatets DER
`EnumerateSlots`	Returnerar varje slot modulen rapporterar som `TPdfPkcs11Slots`, inklusive slots utan token närvarande
`EnumerateCertificates`	Returnerar de certifikat som hålls i en slot som `TPdfPkcs11Certificates`, efter att ha öppnat en session på den slotten
`CloseProtectedSessions`	Loggar ut där en inloggning skedde och ställer den öppna sessionen, vilket frigör tokenen för andra konsumenter

Remarks

Två ABI-detaljer avgör om en modul fungerar alls, och båda skiljer sig åt efter plattform snarare än efter modul
CK_ULONG följer C unsigned long, så den är 4 bytes på Windows (LLP64) och 8 bytes på Linux och macOS (LP64); varje handtag, antal och attributtyp är en CK_ULONG
PKCS#11-headers packar till en byte enbart på Windows. Det är osynligt för strukturer vars samtliga fält är pekarbreda, men det flyttar varje funktionspekare i tabellen, eftersom tabellen öppnar med ett två-byte stort versionsfält
Pkcs11AbiLayout rapporterar layouten detta bygge löste ut, så att ett felmatchande tillstånd kan diagnostiseras i stället för att krascha tyst: Win32 rapporterar ulong=4 attr=12 pss=12 table=2, Win64 rapporterar ulong=4 attr=16 pss=12 table=2, och ett LP64-mål rapporterar ulong=8 attr=24 pss=24 table=8
Enheten kontrollerar också layouten själv när en modul läses in och avvisar modulen i stället för att anropa genom en felmatchande tabell, så att en inkompatibel ABI framträder som en otillgänglig modul
En modul som en annan konsument redan har initierat används som den är, och en session som en annan del av värden redan har loggat in i accepteras likaså
Utan varken tumavtryck eller CertificateLabel vinner det första certifikatet på tokenen, vilket passar en token med ett enda certifikat och ingen produktionsdrift
Den privata nyckeln matchas mot certifikatet via den objektidentifierare tokenen tilldelar båda; när certifikatet saknar en faller sökningen tillbaka på den enda privata nyckel som finns

FPdfPkcs11-enhet