TPDFlibSigner

Security and Signatures

描述

TPDFlibSigner 是獨立的簽署引擎，把 TPDFlibSignDoc 目標與 TPDFlibPFXFile 身分配對，把完成的簽章當作新的增量修訂版寫入

從檔案、串流或字串開啟 PDF，用某個 open 方法綁定身分，選擇目標欄位，設定簽章，最後以 AppendToFile、AppendToStream 或 ApplySignature 收尾

這個類別涵蓋完整的簽署功能集：摘要選擇、內容保留與估算、撤銷資訊、承諾類型、簽章政策、法律聲明、DocMDP 認證層級、欄位鎖定、文件時間戳記，以及固定長度的直通簽章

facade 透過文件記載的 SignProcess 函式暴露同一條管線；當簽署工作流程必須嵌進更大的自訂修訂版寫入器時，可直接使用這個類別

語法

Delphi

TPDFlibSigner = Class
  Public
    Constructor Create;
    Destructor Destroy; Override;
    Function OpenPDF(Const FileName: WideString; Const Password: WideString): TPDFlibSignerResult;
    Function OpenPDFStream(SourceStream: TStream; Const Password: WideString): TPDFlibSignerResult;
    Function OpenPDFString(Const SourceString: AnsiString; Const Password: WideString): TPDFlibSignerResult;
    Function OpenPFX(Const FileName: WideString; Const Password: AnsiString; UseMachineKeyset: Boolean): TPDFlibSignerResult;
    Function OpenCertStore(Const StoreName, CertName: WideString; UseMachineStore: Boolean): TPDFlibSignerResult;
    Function OpenCertContext(CertContext: Pointer): TPDFlibSignerResult;
    Function OpenEd25519(Const CertificateDER, PrivateKeyDER: AnsiString): TPDFlibSignerResult;
    Function OpenEd25519FromFile(Const CertificateFile, PrivateKeyFile: WideString): TPDFlibSignerResult;
    Function OpenCNGKey(Const CertificateDER: AnsiString;
      Const ProviderName, KeyName: WideString; UseMachineKey, AllowUI: Boolean): TPDFlibSignerResult;
    Function OpenCNGKeyHandle(Const CertificateDER: AnsiString; KeyHandle: TPLIntPtr; AllowUI: Boolean): TPDFlibSignerResult;
    Function OpenExternalDigestSigner(Const CertificateDER: AnsiString;
      Signer: TPDFlibExternalDigestSignEvent; Sender: TObject;
      SignProcessID, SignatureAlgorithm, SignatureReserveBytes: Integer): TPDFlibSignerResult;
    Procedure SetPrivateKeyUI(AllowUI: Boolean);
    Procedure SetRSAPSSPadding(Enable: Boolean);
    Procedure SetLegalAttestation(Const Value: WideString);
    Procedure SelectField(Const FieldName: WideString; FieldPage: Integer);
    Procedure SetSignatureProperty(SignatureProperty: TPDFlibSignatureProperty; Const NewValue: AnsiString);
    Procedure SetAppearanceText(Const Text: WideString; FontSize, FontRed, FontGreen, FontBlue: Double);
    Procedure SetSignatureBounds(Left, Top, Width, Height: Double);
    Procedure SetPassthrough(SignatureLength: Integer);
    Procedure SetDocTimeStamp(SignatureLength: Integer);
    Procedure SetDigestAlgorithm(Algorithm: TPDFlibDigestAlgorithm);
    Procedure SetContentsReserveBytes(ExtraBytes: Integer);
    Procedure SetContentsEstimate(ChainBytes, CRLBytes, OCSPBytes, TimeStampBytes, SafetyMarginPercent: Integer);
    Procedure SetRevocationInfo(Const RevocationInfoDER: AnsiString);
    Procedure SetCommitmentType(CommitmentType: Integer);
    Procedure SetDocMDP(Level: Integer);
    Function SetFieldLock(Const Action: AnsiString; Const Fields: TArray): Boolean;
    Procedure SetSignaturePolicy(Const PolicyOID: AnsiString; Const PolicyHashBytes: AnsiString; HashAlgorithm: TPDFlibDigestAlgorithm);
    Function AppendToFile(Const FileName: WideString): Boolean;
    Function AppendToStream(TargetStream: TStream): Boolean;
    Function ApplySignature: Boolean;
    Function GetByteRange(Index: Integer): Int64;
    Function GetEstimatedContentsBytes: Integer;
    Procedure SetInPlace;
    Property IsDocTimeStamp: Boolean Read FIsDocTimeStamp;
  End;

方法

OpenPDF, OpenPDFStream, OpenPDFString從檔案、串流或 ANSI 字串開啟要簽署的文件
OpenPFX, OpenCertStore, OpenCertContext綁定 PFX 檔、以顯示名稱選擇的系統存放區憑證，或外部憑證內容
OpenEd25519, OpenEd25519FromFile從記憶體或檔案綁定 Ed25519 金鑰對
OpenCNGKey, OpenCNGKeyHandle以提供者與金鑰名稱，或以金鑰控制代碼綁定 CNG 金鑰
OpenExternalDigestSigner把摘要簽章委派給外部回呼
SelectField以完整限定名稱與頁面選擇簽章欄位
SetSignatureProperty設定 spReason、spLocation、spContactInfo、spFieldImage、spSubFilter 與 spFieldImageOptions 之一
SetAppearanceText保存附加時寫入欄位外觀的自動產生可見文字區塊
SetSignatureBounds把欄位放到明確座標
SetPassthrough為外部署名產生恰好指定長度的直通簽章
SetDocTimeStamp把簽章切換成文件時間戳記
SetDigestAlgorithm選擇簽章所用的摘要
SetContentsReserveBytes, SetContentsEstimate保留額外位元組，或依憑證鏈、CRL、OCSP 與時間戳記估算加安全餘量決定保留大小
SetRevocationInfo以 DER 形式嵌入預先收集的撤銷資料
SetCommitmentType, SetSignaturePolicy, SetLegalAttestation宣告簽署意圖、政策與法律聲明
SetDocMDP啟用 DocMDP 層級 1、2 或 3 的認證簽章；必須在 SelectField 之前呼叫
SetFieldLock寫入帶動作與欄位名稱清單的欄位鎖定字典
AppendToFile, AppendToStream把已簽署修訂版寫入新檔案或串流
ApplySignature把簽章套用到原地文件
GetByteRange, GetEstimatedContentsBytes修訂版建構後回讀 ByteRange 條目與估算的內容大小
SetInPlace把修訂版標記為對已開啟文件的原地更新

參數

IsDocTimeStamp簽署器正在產生文件時間戳記時為 True

備註

所有 open 方法都回傳 TPDFlibSignerResult

DocMDP 層級對應 ISO 32000 轉換 P 值：1 不得變更、2 可填表、3 可加註解；非零時會設定 AcroForm /SigFlags 的 AppendOnly 位元，讓檢視器強制執行認證

另請參閱

TPDFlibSignDoc, TPDFlibPFXFile, TPDFlibSignerResult, NewSignProcessFromFile, SetSignProcessDocMDP