TPDFlibPKCS11Client

Sicurezza e firme

Descrizione

Carica a runtime un modulo PKCS #11 del fornitore ed espone certificati e chiavi private non registrati presso i provider Windows CSP o KSPIl client enumera i token presenti, apre una sessione persistente, autentica l'utente, abbina un certificato X.509 a una chiave di firma tramite

CKA_ID binario e firma digest già calcolati attraverso CKM_RSA_PKCS oppure CKM_ECDSAL'individuazione facoltativa senza certificato può selezionare una chiave privata ML-DSA per etichetta o ID binario, validarne il

CKA_PARAMETER_SETCKM_ML_DSA

SignDigest e firmare messaggi originali attraverso TPDFlibExternalDigestSignEventTPDFlib.OnExternalDigestSign implementa

Unità

PDFlibPKCS11

Costruzione e ciclo di vita del modulo

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

ModulePath identifica una DLL PKCS #11 Win32 oppure Win64 che esporta C_GetFunctionListI client che usano lo stesso percorso condividono un unico modulo caricato e un'unica durata bilanciata

C_Initialize/C_FinalizeIl loader richiede prima

CKF_OS_LOCKING_OK

UseFunctionList; i moduli che non possono fornire il locking interno sono protetti da un lock di chiamata condiviso, mentre i moduli conformi consentono a sessioni client separate di girare in concorrenzaUnloadModule supporta provider collegati staticamente, incorporati oppure gestiti dall'applicazione; il chiamante deve mantenere viva la tabella fornita finché

Individuazione e connessione del 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 enumera gli slot presenti con tentativi limitati quando un evento hot-plug cambia il conteggio, e TokenCount riporta quanti token l'ultimo refresh ha trovatoSelezionare un token con

SlotID, TokenLabel, TokenSerial oppure una combinazione; una selezione vuota riesce solo quando esiste esattamente un token presente

TPDFlibPKCS11Token riporta la descrizione dello slot, il produttore, l'etichetta del token, il modello, il numero di serie, i flag e i limiti di lunghezza del PIN

Parametri

CertificateLabel	Filtro facoltativo `CKA_LABEL` UTF-8 per l'oggetto certificato X.509
CertificateID	Filtro facoltativo `CKA_ID` binario memorizzato in una `AnsiString`
PrivateKeyLabel	Filtro facoltativo `CKA_LABEL` UTF-8 per la chiave privata di firma
PrivateKeyID	`CKA_ID` binario facoltativo della chiave privata; quando vuoto, viene riutilizzato l'ID del certificato
CertificateOptional	Valore predefinito False; quando True, è richiesta un'etichetta oppure un ID della chiave privata e l'individuazione accetta solo chiavi ML-DSA senza certificato X.509

CKA_SIGN=True

MLDSAParameterSet

CertificateDER, valida il DER del certificato e rifiuta le mancate corrispondenze di tipo RSA/EC; l'individuazione senza certificato richiede una chiave ML-DSA non ambigua e valida il set di parametri 44, 65 oppure 87Il set di parametri ML-DSA risolto è esposto tramite ResolvedPrivateKeyIDIl certificato risolto è esposto tramite

Autenticazione

UserPIN	PIN utente di sola scrittura codificato in UTF-8, controllato rispetto ai limiti del token e azzerato quando viene sostituito o distrutto
UseProtectedAuthenticationPath	Passa un PIN null quando il token dichiara `CKF_PROTECTED_AUTHENTICATION_PATH`
ReadWriteSession	Aggiunge `CKF_RW_SESSION`; la firma di norma richiede solo la sessione seriale di sola lettura predefinita

Le chiavi con CKA_ALWAYS_AUTHENTICATE=True ricevono un login specifico del contesto dopo ogni C_SignInit riuscito

ClearPIN sovrascrive e rilascia il PIN configurato

Firma

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;

Le firme RSA usano CKM_RSA_PKCS raw con un DigestInfo DER costruito localmente, così il token non esegue una seconda volta l'hashing del digest PDFLe firme ECDSA usano

CKM_ECDSA raw; l'output P1363 del token viene restituito invariato per PDF_EXTERNAL_SIGNATURE_ECDSA_P1363 oppure convertito in DER rigoroso per PDF_EXTERNAL_SIGNATURE_ECDSA_DER

SignMLDSA passa il messaggio originale a CKM_ML_DSA a parte singola con parametri di meccanismo vuoti, selezionando il contesto vuoto predefinito; è indipendente da SignHash e dal callback di digest CMS

Le lunghezze di digest SHA-1, SHA-256, SHA-384, SHA-512, SHA3-256, SHA3-384 e SHA3-512 vengono validate prima di qualsiasi operazione con chiave privata

C_SignInit fallisce prima dell'inizio della firma, evitando operazioni duplicate con la chiave privata dopo un fallimento ambiguo di C_Sign

Esempio

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;

Stato e comportamento in caso di errore

Connected, KeyType, MLDSAParameterSet, AlwaysAuthenticate, FunctionListMajor e FunctionListMinor espongono lo stato attivo del providerI metodi restituiscono

False e impostano sia LastReturnValue sia LastError quando il caricamento del modulo, la selezione del token, l'autenticazione, l'individuazione degli oggetti, i limiti degli attributi, i controlli dei meccanismi oppure la firma falliscono

Vedere anche

OnExternalDigestSign, SetSignProcessExternalDigestSigner, SetSignProcessDigestAlgorithm, TPDFlibCSCClient

Amministrazione del PIN

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

Entrambe le operazioni aprono la propria sessione di lettura/scrittura sul token configurato e lasciano intatta la sessione di firma; InitializeUserPIN accede come ufficiale di sicurezza prima di chiamare C_InitPIN, e ChangeUserPIN accede come utente prima di chiamare C_SetPIN

I buffer del PIN vengono cancellati dopo l'uso; un modulo senza il punto d'ingresso richiesto segnala un errore invece di fallire in silenzio