TPDFlibPKCS11Client

Sécurité et signatures

Description

Charge un module PKCS #11 de fournisseur à l'exécution et expose les certificats et clés privées qui ne sont pas enregistrés auprès des fournisseurs Windows CSP ou KSPLe client énumère les tokens présents, ouvre une session persistante, authentifie l'utilisateur, apparie un certificat X.509 avec une clé de signature par

CKA_ID binaire et signe des condensats déjà calculés au travers de CKM_RSA_PKCS ou CKM_ECDSALa découverte explicite à certificat facultatif peut sélectionner une clé privée ML-DSA par étiquette ou identifiant binaire, valider son

CKA_PARAMETER_SETCKM_ML_DSA

SignDigest et signer des messages d'origine au travers de TPDFlibExternalDigestSignEventTPDFlib.OnExternalDigestSign implémente

Unité

PDFlibPKCS11

Construction et cycle de vie du module

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

ModulePath identifie une DLL PKCS #11 Win32 ou Win64 exportant C_GetFunctionListLes clients qui utilisent le même chemin partagent un module chargé unique et un cycle de vie

C_Initialize/C_Finalize équilibréLe chargeur demande d'abord

CKF_OS_LOCKING_OK

UseFunctionList ; les modules qui ne peuvent pas fournir de verrouillage interne sont protégés par un verrou d'appel partagé, tandis que les modules conformes permettent à des sessions clientes distinctes de s'exécuter concurremmentUnloadModule prend en charge les fournisseurs liés statiquement, incorporés ou gérés par l'application ; l'appelant doit maintenir la table fournie en vie jusqu'à

Détection et connexion des jetons

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 énumère les slots présents avec des nouvelles tentatives bornées lorsqu'un événement de connexion à chaud change le compte, et TokenCount indique combien de tokens le dernier rafraîchissement a trouvésSélectionnez un token avec

SlotID, TokenLabel, TokenSerial ou une combinaison ; une sélection vide ne réussit que lorsqu'il existe exactement un token présent

TPDFlibPKCS11Token signale la description du slot, le fabricant, l'étiquette du token, le modèle, le numéro de série, les indicateurs et les bornes de longueur du PIN

Paramètres

CertificateLabel	Filtre facultatif `CKA_LABEL` UTF-8 pour l'objet certificat X.509
CertificateID	Filtre facultatif `CKA_ID` binaire stocké dans un `AnsiString`
PrivateKeyLabel	Filtre facultatif `CKA_LABEL` UTF-8 pour la clé privée de signature
PrivateKeyID	`CKA_ID` binaire facultatif de la clé privée ; lorsqu'il est vide, l'identifiant du certificat est réutilisé
CertificateOptional	Vaut False par défaut ; lorsque True, une étiquette ou un identifiant de clé privée est requis et la découverte n'accepte que des clés ML-DSA sans certificat X.509

CKA_SIGN=True

MLDSAParameterSet

CertificateDER, valide le DER du certificat et rejette les incompatibilités de type RSA/EC ; la découverte à certificat facultatif exige une clé ML-DSA non ambiguë et valide le jeu de paramètres 44, 65 ou 87Le jeu de paramètres ML-DSA résolu est exposé via ResolvedPrivateKeyIDLe certificat résolu est exposé via

Authentification

UserPIN	PIN utilisateur en écriture seule encodé en UTF-8, vérifié par rapport aux bornes du token et effacé lors de son remplacement ou de la destruction
UseProtectedAuthenticationPath	Passe un PIN nul lorsque le token annonce `CKF_PROTECTED_AUTHENTICATION_PATH`
ReadWriteSession	Ajoute `CKF_RW_SESSION` ; la signature n'a normalement besoin que de la session série en lecture seule par défaut

Les clés avec CKA_ALWAYS_AUTHENTICATE=True reçoivent une connexion propre au contexte après chaque C_SignInit réussi

ClearPIN écrase et libère le PIN configuré

Signature

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;

Les signatures RSA utilisent CKM_RSA_PKCS brut avec un DigestInfo DER construit localement, de sorte que le token ne hache pas le condensat PDF une seconde foisLes signatures ECDSA utilisent

CKM_ECDSA brut ; la sortie P1363 du token est retournée inchangée pour PDF_EXTERNAL_SIGNATURE_ECDSA_P1363 ou convertie en DER strict pour PDF_EXTERNAL_SIGNATURE_ECDSA_DER

SignMLDSA passe le message original à CKM_ML_DSA mono-partie avec des paramètres de mécanisme vides, en sélectionnant le contexte vide par défaut ; il est indépendant de SignHash et du callback de condensat CMS

Les longueurs d'empreinte SHA-1, SHA-256, SHA-384, SHA-512, SHA3-256, SHA3-384 et SHA3-512 sont validées avant toute opération de clé privée

C_SignInit échoue avant le début de la signature, ce qui évite des opérations de clé privée dupliquées après un échec ambigu de C_Sign

Exemple

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;

État et comportement en cas d'échec

Connected, KeyType, MLDSAParameterSet, AlwaysAuthenticate, FunctionListMajor et FunctionListMinor exposent l'état du fournisseur actifLes méthodes retournent

False et définissent à la fois LastReturnValue et LastError lorsque le chargement du module, la sélection de token, l'authentification, la découverte d'objets, les bornes d'attributs, les contrôles de mécanisme ou la signature échouent

Voir aussi

OnExternalDigestSign, SetSignProcessExternalDigestSigner, SetSignProcessDigestAlgorithm, TPDFlibCSCClient

Administration du PIN

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

Les deux opérations ouvrent leur propre session de lecture/écriture sur le jeton configuré et laissent la session de signature intacte ; InitializeUserPIN se connecte comme officier de sécurité avant d'appeler C_InitPIN, et ChangeUserPIN se connecte comme utilisateur avant d'appeler C_SetPIN

Les tampons de PIN sont effacés après usage ; un module sans le point d'entrée requis signale une erreur au lieu d'échouer silencieusement