TPDFlibPKCS11Client

Zabezpieczenia i podpisy

Opis

Wczytuje moduł PKCS #11 dostawcy w czasie działania i udostępnia certyfikaty oraz klucze prywatne niezarejestrowane u dostawców Windows CSP albo KSPKlient wylicza obecne tokeny, otwiera trwałą sesję, uwierzytelnia użytkownika, paruje certyfikat X.509 z kluczem podpisującym po binarnym

CKA_ID i podpisuje już wyliczone skróty przez CKM_RSA_PKCS albo CKM_ECDSAOdkrywanie z opcjonalnym certyfikatem może wybrać klucz prywatny ML-DSA po etykiecie albo binarnym ID, zwalidować jego

CKA_PARAMETER_SETCKM_ML_DSA

SignDigest i podpisywać pierwotne komunikaty przez TPDFlibExternalDigestSignEventTPDFlib.OnExternalDigestSign implementuje

Jednostka

PDFlibPKCS11

Konstrukcja i cykl życia modułu

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

ModulePath identyfikuje bibliotekę DLL PKCS #11 dla Win32 albo Win64 eksportującą C_GetFunctionListKlienci używający tej samej ścieżki współdzielą jeden wczytany moduł i jeden zrównoważony cykl życia

C_Initialize/C_FinalizeWczytywacz najpierw żąda

CKF_OS_LOCKING_OK

UseFunctionList; moduły, które nie mogą zapewnić wewnętrznej blokady, są chronione współdzieloną blokadą wywołań, podczas gdy zgodne moduły pozwalają równolegle działać osobnym sesjom klientówUnloadModule obsługuje dostawców linkowanych statycznie, osadzonych albo zarządzanych przez aplikację; wywołujący musi utrzymać przekazaną tabelę przy życiu do

Wykrywanie i łączenie tokenów

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 wylicza obecne sloty z ograniczoną liczbą ponowień, gdy zdarzenie wymiany na gorąco zmieni ich liczbę, a TokenCount raportuje, ile tokenów znalazło ostatnie odświeżenieWybierz token przez

SlotID, TokenLabel, TokenSerial albo ich kombinację; pusty wybór kończy się sukcesem tylko wtedy, gdy istnieje dokładnie jeden obecny token

TPDFlibPKCS11Token raportuje opis slotu, producenta, etykietę tokenu, model, numer seryjny, flagi i granice długości PIN

Parametry

CertificateLabel	Opcjonalny filtr `CKA_LABEL` w UTF-8 dla obiektu certyfikatu X.509
CertificateID	Opcjonalny binarny filtr `CKA_ID` przechowywany w `AnsiString`
PrivateKeyLabel	Opcjonalny filtr `CKA_LABEL` w UTF-8 dla prywatnego klucza podpisującego
PrivateKeyID	Opcjonalny binarny `CKA_ID` klucza prywatnego; gdy pusty, ponownie używane jest ID certyfikatu
CertificateOptional	Domyślnie False; przy True wymagana jest etykieta albo ID klucza prywatnego, a odkrywanie przyjmuje tylko klucze ML-DSA bez certyfikatu X.509

CKA_SIGN=True

MLDSAParameterSet

CertificateDER, waliduje DER certyfikatu i odrzuca niedopasowania typów RSA/EC; odkrywanie z opcjonalnym certyfikatem wymaga jednoznacznego klucza ML-DSA i waliduje zestaw parametrów 44, 65 albo 87Rozstrzygnięty zestaw parametrów ML-DSA jest ujawniany przez ResolvedPrivateKeyIDRozstrzygnięty certyfikat jest ujawniany przez

Uwierzytelnianie

UserPIN	PIN użytkownika tylko do zapisu, kodowany w UTF-8, sprawdzany względem granic tokenu i wymazywany przy zastąpieniu albo zniszczeniu
UseProtectedAuthenticationPath	Przekazuje pusty PIN, gdy token zgłasza `CKF_PROTECTED_AUTHENTICATION_PATH`
ReadWriteSession	Dodaje `CKF_RW_SESSION`; podpisywanie normalnie potrzebuje tylko domyślnej sesji tylko do odczytu

Klucze z CKA_ALWAYS_AUTHENTICATE=True otrzymują logowanie kontekstowe po każdym udanym C_SignInit

ClearPIN nadpisuje i zwalnia skonfigurowany PIN

Podpisywanie

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;

Podpisy RSA używają surowego CKM_RSA_PKCS z lokalnie skonstruowanym DER DigestInfo, więc token nie haszuje skrótu PDF drugi raz

Podpisy ECDSA używają surowego CKM_ECDSA; wyjście P1363 tokenu jest zwracane bez zmian dla PDF_EXTERNAL_SIGNATURE_ECDSA_P1363 albo konwertowane na ścisły DER dla PDF_EXTERNAL_SIGNATURE_ECDSA_DER

SignMLDSA przekazuje pierwotną wiadomość do jednoczęściowego CKM_ML_DSA z pustymi parametrami mechanizmu, wybierając domyślny pusty kontekst; jest niezależny od SignHash i zwrotnego wywołania skrótu CMS

Długości skrótów SHA-1, SHA-256, SHA-384, SHA-512, SHA3-256, SHA3-384 i SHA3-512 są walidowane przed jakąkolwiek operacją klucza prywatnego

Utracona sesja jest ponownie otwierana i ponawiana tylko, gdy C_SignInit zawiedzie przed rozpoczęciem podpisywania, co unika zduplikowanych operacji klucza prywatnego po niejasnym niepowodzeniu C_Sign

Przykład

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;

Stan i zachowanie w przypadku błędu

Connected, KeyType, MLDSAParameterSet, AlwaysAuthenticate, FunctionListMajor i FunctionListMinor ujawniają stan aktywnego dostawcyMetody zwracają

False i ustawiają zarówno LastReturnValue, jak i LastError, gdy wczytywanie modułu, wybór tokenu, uwierzytelnianie, odkrywanie obiektów, granice atrybutów, sprawdzanie mechanizmów albo podpisywanie zawiedzie

Zobacz również

OnExternalDigestSign, SetSignProcessExternalDigestSigner, SetSignProcessDigestAlgorithm, TPDFlibCSCClient

Zarządzanie kodem PIN

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

Obie operacje otwierają własną sesję odczytu/zapisu na skonfigurowanym tokenie i zostawiają sesję podpisującą nietkniętą; InitializeUserPIN loguje się jako oficer bezpieczeństwa przed wywołaniem C_InitPIN, a ChangeUserPIN jako użytkownik przed wywołaniem C_SetPIN

Bufory PIN są wycierane po użyciu; moduł bez wymaganego punktu wejścia raportuje błąd zamiast zawieść po cichu