TPDFlibPKCS11Client

Sikkerhed og signaturer

Beskrivelse

Indlæser et leverandør-PKCS #11-modul ved kørselstid og eksponerer certifikater og private nøgler, der ikke er registreret hos Windows CSP- eller KSP-udbydereKlienten optæller tilstedeværende tokens, åbner en vedvarende session, autentificerer brugeren, parrer et X.509-certifikat med en signeringsnøgle via binær

CKA_ID og signerer allerede beregnede digests gennem CKM_RSA_PKCS eller CKM_ECDSAEksplicit certifikat-optional opdagelse kan vælge en ML-DSA-privatnøgle efter etiket eller binært ID, validere dens

CKA_PARAMETER_SETCKM_ML_DSA

SignDigest og signere oprindelige beskeder gennem TPDFlibExternalDigestSignEventTPDFlib.OnExternalDigestSign implementerer

Enhed

PDFlibPKCS11

Konstruktion og modullivscyklus

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

ModulePath identificerer en Win32- eller Win64-PKCS #11-DLL, der eksporterer C_GetFunctionListKlienter, der bruger samme sti, deler ét indlæst modul og én balanceret

C_Initialize/C_Finalize-levetidIndlæseren anmoder først om

CKF_OS_LOCKING_OK

UseFunctionList; moduler, der ikke kan levere intern låsning, beskyttes af en delt kaldelås, mens compliant-moduler tillader, at separate klientsessioner kører samtidigtUnloadModule understøtter statisk kædede, indlejrede eller applikationsstyrede udbydere; kalderen skal holde den leverede tabel i live indtil

Opdagelse og tilslutning af tokens

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 optæller tilstedeværende slots med afgrænset retry, når en hot-plug-hændelse ændrer antallet, og TokenCount rapporterer, hvor mange tokens den sidste opdatering fandtVælg et token med

SlotID, TokenLabel, TokenSerial eller en kombination; et tomt valg lykkes kun, når der findes præcis ét tilstedeværende token

TPDFlibPKCS11Token rapporterer slotbeskrivelse, producent, token-etiket, model, serienummer, flag og PIN-længdegrænser

Parametre

CertificateLabel	Valgfrit UTF-8 `CKA_LABEL`-filter til X.509-certifikatobjektet
CertificateID	Valgfrit binært `CKA_ID`-filter gemt i en `AnsiString`
PrivateKeyLabel	Valgfrit UTF-8 `CKA_LABEL`-filter til den private signeringsnøgle
PrivateKeyID	Valgfrit binært `CKA_ID` for den private nøgle; når tomt, genbruges certifikat-ID'et
CertificateOptional	Som standard False; når True, kræves en privatnøgleetiket eller et ID, og opdagelsen accepterer kun ML-DSA-nøgler uden et X.509-certifikat

CKA_SIGN=True

MLDSAParameterSet

CertificateDER, validerer certifikat-DER og afviser RSA/EC-typemismatch; certifikat-optional opdagelse kræver en utvetydig ML-DSA-nøgle og validerer parametersæt 44, 65 eller 87Det opløste ML-DSA-parametersæt eksponeres gennem ResolvedPrivateKeyIDDet opløste certifikat eksponeres gennem

Autentifikation

UserPIN	Write-only-bruger-PIN kodet som UTF-8, kontrolleret mod token-grænser og slettet, når den erstattes eller destrueres
UseProtectedAuthenticationPath	Videregiver en null-PIN, når tokenet annoncerer `CKF_PROTECTED_AUTHENTICATION_PATH`
ReadWriteSession	Tilføjer `CKF_RW_SESSION`; signering behøver normalt kun den standardindstillede read-only-serielle session

Nøgler med CKA_ALWAYS_AUTHENTICATE=True modtager et kontekstspecifikt login efter hver vellykket C_SignInit

ClearPIN overskriver og frigiver den konfigurerede PIN

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 bruger rå CKM_RSA_PKCS med en lokalt konstrueret DER DigestInfo, så tokenet ikke hasher PDF-digesten en anden gang

ECDSA-signaturer bruger rå CKM_ECDSA; token P1363-output returneres uændret for PDF_EXTERNAL_SIGNATURE_ECDSA_P1363 eller konverteres til streng DER for PDF_EXTERNAL_SIGNATURE_ECDSA_DER

SignMLDSA sender den oprindelige besked til enkeltparts CKM_ML_DSA med tomme mekanismeparametre og vælger standardens tomme kontekst; den er uafhængig af SignHash og CMS-digest-callback'en

Digest-længderne SHA-1, SHA-256, SHA-384, SHA-512, SHA3-256, SHA3-384 og SHA3-512 valideres før nogen privatnøgle-operation

En tabt session genåbnes og gentages kun, når C_SignInit fejler, før signering begynder, hvilket undgår duplikerede privatnøgle-operationer efter en tvetydig C_Sign-fejl

Eksempel

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- og fejladfærd

Connected, KeyType, MLDSAParameterSet, AlwaysAuthenticate, FunctionListMajor og FunctionListMinor eksponerer den aktive udbydertilstandMetoderne returnerer

False og sætter både LastReturnValue og LastError, når modulindlæsning, tokenvalg, autentificering, objektgenkendelse, attributgrænser, mekanismekontroller eller signering fejler

Se også

OnExternalDigestSign, SetSignProcessExternalDigestSigner, SetSignProcessDigestAlgorithm, TPDFlibCSCClient

PIN-administration

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

Begge operationer åbner deres egen læse/skrive-session på det konfigurerede token og lader signeringssessionen være urørt; InitializeUserPIN logger ind som sikkerhedsofficer før kald af C_InitPIN, og ChangeUserPIN logger ind som brugeren før kald af C_SetPIN

PIN-buffere tørres efter brug; et modul uden det krævede indgangspunkt rapporterer en fejl i stedet for at fejle lydløst