TPDFlibPKCS11Client

Säkerhet och signaturer

Beskrivning

Läser in en leverantörs PKCS #11-modul vid körtid och exponerar certifikat och privata nycklar som inte är registrerade hos Windows CSP- eller KSP-leverantörerKlienten räknar upp befintliga tokens, öppnar en beständig session, autentiserar användaren, parkopplar ett X.509-certifikat med en signeringsnyckel via binär

CKA_ID och signerar redan beräknade sammandrag via CKM_RSA_PKCS eller CKM_ECDSAUttrycklig certifikatvalfri upptäckt kan välja en privat ML-DSA-nyckel via etikett eller binärt ID, validera dess

CKA_PARAMETER_SETCKM_ML_DSA

SignDigest och signera ursprungliga meddelanden via TPDFlibExternalDigestSignEventTPDFlib.OnExternalDigestSign implementerar

Enhet

PDFlibPKCS11

Konstruktion och modullivscykel

Constructor TPDFlibPKCS11Client.Create;
Destructor TPDFlibPKCS11Client.Destroy;
Function TPDFlibPKCS11Client.LoadModule: Boolean;
Procedure TPDFlibPKCS11Client.UnloadModule;
Function TPDFlibPKCS11Client.UseFunctionList(FunctionList: PPLPKCS11FunctionList; AlreadyInitialized: Boolean): Boolean;

ModulePath identifierar en Win32- eller Win64-PKCS #11-DLL som exporterar C_GetFunctionListKlienter som använder samma sökväg delar en inläst modul och en balanserad

C_Initialize/C_Finalize-livscykelInläsaren begär först

CKF_OS_LOCKING_OK

UseFunctionList; moduler som inte kan tillhandahålla intern låsning skyddas av ett gemensamt anropslås, medan överensstämmande moduler tillåter att separata klientsessioner körs samtidigtUnloadModule stöder statiskt länkade, inbäddade eller programhanterade leverantörer; anroparen måste hålla den tillhandahållna tabellen vid liv till

Identifiering och anslutning av token

Function TPDFlibPKCS11Client.RefreshTokens: Boolean;
Function TPDFlibPKCS11Client.GetToken(Index: Integer; Out Token: TPDFlibPKCS11Token): Boolean;
Function TPDFlibPKCS11Client.Connect: Boolean;
Procedure TPDFlibPKCS11Client.Disconnect;
Function TPDFlibPKCS11Client.GetSelectedToken(Out Token: TPDFlibPKCS11Token): Boolean;
Property TPDFlibPKCS11Client.TokenCount: Integer;

RefreshTokens räknar upp befintliga platser med avgränsat återförsök när en hot-plug-händelse ändrar antalet, och TokenCount rapporterar hur många tokens senaste uppdateringen fannVälj en token med

SlotID, TokenLabel, TokenSerial eller en kombination; ett tomt val lyckas endast när exakt en befintlig token finns

TPDFlibPKCS11Token rapporterar platsbeskrivning, tillverkare, tokenetikett, modell, serienummer, flaggor och gränser för PIN-längd

Parametrar

CertificateLabel	Valfritt UTF-8-`CKA_LABEL`-filter för X.509-certifikatobjektet
CertificateID	Valfritt binärt `CKA_ID`-filter lagrat i en `AnsiString`
PrivateKeyLabel	Valfritt UTF-8-`CKA_LABEL`-filter för den privata signeringsnyckeln
PrivateKeyID	Valfritt binärt privat nyckel-`CKA_ID`; när det är tomt återanvänds certifikatets ID
CertificateOptional	Standard är False; när True krävs en etikett eller ett ID för privat nyckel och upptäckten accepterar endast ML-DSA-nycklar utan X.509-certifikat

CKA_SIGN=True

MLDSAParameterSet

CertificateDER, validerar certifikatets DER och avvisar typfelmatchningar mellan RSA och EC; certifikatvalfri upptäckt kräver en entydig ML-DSA-nyckel och validerar parameteruppsättning 44, 65 eller 87Den upplösta ML-DSA-parameteruppsättningen exponeras via ResolvedPrivateKeyIDDet upplösta certifikatet exponeras via

Autentisering

UserPIN	Användar-PIN med endast skrivning, kodad som UTF-8, kontrollerad mot tokengränser och utraderad när den ersätts eller förstörs
UseProtectedAuthenticationPath	Skickar en null-PIN när tokenen annonserar `CKF_PROTECTED_AUTHENTICATION_PATH`
ReadWriteSession	Lägger till `CKF_RW_SESSION`; signering behöver normalt bara den förinställda skrivskyddade seriella sessionen

Nycklar med CKA_ALWAYS_AUTHENTICATE=True får en kontextspecifik inloggning efter varje lyckad C_SignInit

ClearPIN skriver över och släpper den konfigurerade PIN-koden

Signering

Function TPDFlibPKCS11Client.SupportsMechanism(MechanismType: Cardinal): Boolean;
Function TPDFlibPKCS11Client.SupportsAlgorithm(DigestAlgorithm, SignatureAlgorithm: Integer): Boolean;
Function TPDFlibPKCS11Client.SignMLDSA(Const Message: AnsiString; Out Signature: AnsiString): Boolean;
Function TPDFlibPKCS11Client.SignHash(Const Digest: AnsiString; DigestAlgorithm, SignatureAlgorithm: Integer; Out Signature: AnsiString): Boolean;
Function TPDFlibPKCS11Client.SignDigest(Sender: TObject; SignProcessID: Integer; Const Digest: AnsiString; DigestAlgorithm, SignatureAlgorithm: Integer; Var Signature: AnsiString): Boolean;

RSA-signaturer använder rå CKM_RSA_PKCS med en lokalt konstruerad DER-DigestInfo, så tokenen hashar inte PDF-sammandraget en andra gång

ECDSA-signaturer använder rå CKM_ECDSA; tokenens P1363-utdata returneras oförändrad för PDF_EXTERNAL_SIGNATURE_ECDSA_P1363 eller konverteras till strikt DER för PDF_EXTERNAL_SIGNATURE_ECDSA_DER

SignMLDSA skickar det ursprungliga meddelandet till enparts-CKM_ML_DSA med tomma mekanismparametrar och väljer standardtom kontext; den är oberoende av SignHash och CMS-sammandragsåteranropet

Sammandragslängderna för SHA-1, SHA-256, SHA-384, SHA-512, SHA3-256, SHA3-384 och SHA3-512 valideras innan någon operation med privat nyckel utförs

En förlorad session öppnas igen och försöket upprepas endast när C_SignInit misslyckas innan signeringen börjar, vilket undviker dubbla operationer med privat nyckel efter ett tvetydigt C_Sign-fel

Exempel

var
  Token: TPDFlibPKCS11Client;
  ProcessID: Integer;
begin
  Token:= TPDFlibPKCS11Client.Create;
  try
    Token.ModulePath:= 'C:\Program Files\Vendor\pkcs11.dll';
    Token.TokenLabel:= 'Signing token';
    Token.CertificateLabel:= 'Document signer';
    Token.UserPIN:= UserPIN;
    if not Token.Connect then
      raise Exception.Create(String(Token.LastError));

    PDF.OnExternalDigestSign:= Token.SignDigest;
    ProcessID:= PDF.NewSignProcessFromFile(InputFile, '');
    PDF.SetSignProcessField(ProcessID, 'Approval');
    PDF.SetSignProcessDigestAlgorithm(ProcessID, 2);
    PDF.SetSignProcessExternalDigestSigner(ProcessID,
      Token.CertificateDER, PDF_EXTERNAL_SIGNATURE_RSA_PKCS1, 512);
    PDF.EndSignProcessToFile(ProcessID, OutputFile);
  finally
    Token.Free;
  end;
end;

Status och beteende vid fel

Connected, KeyType, MLDSAParameterSet, AlwaysAuthenticate, FunctionListMajor och FunctionListMinor exponerar den aktiva leverantörsstatusenMetoder returnerar

False och sätter både LastReturnValue och LastError när modulinläsning, tokenval, autentisering, objektupptäckt, attributgränser, mekanismskontroller eller signering misslyckas

Se även

OnExternalDigestSign, SetSignProcessExternalDigestSigner, SetSignProcessDigestAlgorithm, TPDFlibCSCClient

PIN-administration

Function TPDFlibPKCS11Client.InitializeUserPIN(Const SecurityOfficerPIN, NewUserPIN: WideString): Boolean;
Function TPDFlibPKCS11Client.ChangeUserPIN(Const OldPIN, NewPIN: WideString): Boolean;

Båda operationerna öppnar sin egen läs-/skrivsession på den konfigurerade tokenen och lämnar signeringssessionen orörd; InitializeUserPIN loggar in som säkerhetsansvarig innan C_InitPIN anropas, ChangeUserPIN loggar in som användaren innan C_SetPIN anropas

PIN-buffertar utraderas efter användning; en modul utan nödvändig ingångspunkt rapporterar ett fel i stället för att misslyckas tyst