TPDFlibSignDoc

Security and Signatures

描述

TPDFlibSignDoc 不必把整份 PDF 載入記憶體，即可直接存取文件的簽章欄位

這個類別可開啟檔案、呼叫端自有的串流或 ANSI 位元組字串，列舉 AcroForm 簽章欄位，並讀取既有簽章的原始值，供驗證器重新計算 /ByteRange 摘要

它也負責增量更新的寫入端：Append 開啟新的修訂版，AddSignatureField 註冊新欄位，SetSignatureValue 系列在保留較早修訂版的前提下寫入保留空間

SigningWorkbench 示範從頭到尾驅動這個類別，從欄位列舉到 ByteRange 檢查與憑證擷取

語法

Delphi

TPDFlibSignDoc = Class
  Public
    Destructor Destroy; Override;
    Function Open(Const FileName: WideString; Const Password: WideString; ReadWrite: Boolean): Boolean;
    Function OpenStream(SourceStream: TStream; Const Password: WideString): Boolean;
    Function OpenString(Const SourceData: AnsiString; Const Password: WideString): Boolean;
    Procedure Append;
    Function AppendToFile(Const FileName: WideString): Boolean;
    Function AppendToStream(TargetStream: TStream): Boolean;
    Procedure Close;
    Function AddSignatureField(Const FieldName: WideString; PageNumber: Integer): Integer;
    Function HasSignatureField(Const FieldName: WideString): Boolean;
    Procedure GetSignatureFieldNames(Names: TStrings);
    Function GetSignatureValueObjNum(Const FieldName: WideString): Integer;
    Function GetSignatureValueByName(Const FieldName: WideString; ValueKey: Integer): AnsiString;
    Function GetSignatureTextValueByName(Const FieldName: WideString; ValueKey: Integer): WideString;
    Function GetSignatureDocMDPLevelByName(Const FieldName: WideString): Integer;
    Function GetSignaturePermissionInfoByName(Const FieldName: WideString;
      Out Report: TPDFlibSignaturePermissionReport): Boolean;
    Function GetSignatureSeedValueEx(Const FieldName: WideString;
      Out SeedValue: TPDFSignatureSeedValue): Boolean;
    Function GetSignatureContentsHashHexByName(Const FieldName: WideString): AnsiString;
    Function SetSignatureValue(Const FieldName: WideString; Const NewValue: AnsiString;
      DocMDPLevel: Integer): Boolean;
    Function SetSignatureFieldLock(Const FieldName: WideString;
      Const Action: AnsiString; Const Fields: TArray): Boolean;
    Procedure SetSignatureImage(Const FieldName: WideString; Const ImageData: AnsiString; ImageOptions: Integer);
    Procedure SetSignatureAppearanceText(Const FieldName, Text: WideString; FontSize, FontRed, FontGreen, FontBlue: Double);
    Procedure SetSignatureBounds(Const FieldName: WideString; Left, Top, Width, Height: Double);
    Function GetDocumentBytes: TBytes;
    Function GetDocumentSize: Int64;
    Function ReadDocumentRange(Offset: Int64; Buffer: Pointer; Count: Integer): Integer;
    Function GetDSSValidationMaterial(Const FieldName: WideString;
      Out Certs, CRLs, OCSPs: TStructStrArray; Out UsedVRI: Boolean): Boolean;
    Procedure SetSignatureFlags(NewFlags: Integer);
    Procedure EnsurePAdESExtensions(ESICLevel: Integer);
    Property IsOpen: Boolean Read FIsOpen;
    Property SignatureFieldPosition: Int64 Read FSignatureFieldPosition;
    Property SignatureFieldLength: Integer Read FSignatureFieldLength;
  End;

方法

Open, OpenStream, OpenString開啟檔案、串流或記憶體中的 ANSI 字串，可選擇以讀寫方式；Open 接受密碼與讀寫旗標
Append, AppendToFile, AppendToStream原地開始新的增量修訂版，或把修訂版附加到新檔案或串流
Close釋放底層的智慧讀取器與文件控制代碼
AddSignatureField在指定頁面註冊新簽章欄位並回傳其物件編號，失敗回傳 0
HasSignatureField存在具有該完整限定名稱的簽章欄位時為 True
GetSignatureFieldNames把 AcroForm 中所有簽章欄位名稱填入 TStrings
GetSignatureValueObjNum簽章值字典的物件編號；欄位未簽署時為 0
GetSignatureValueByName由 ValueKey 選擇的原始二進位值：0 = /Contents、1 = /Cert、2 = /Filter、3 = /SubFilter、11 到 14 = /ByteRange 條目 0 到 3（十進位字串）
GetSignatureTextValueByName由 ValueKey 選擇的文字值：0 = /M、1 = /Name、2 = /Reason、3 = /Location、4 = /ContactInfo、5 = /Type
GetSignatureDocMDPLevelByName認證簽章的 DocMDP 轉換層級（P 值），缺席時為 0
GetSignaturePermissionInfoByName把簽章的 DocMDP 與 FieldMDP 限制解析成報告記錄
GetSignatureSeedValueEx讀取限制簽署者可寫入內容的 /SV seed 值字典
GetSignatureContentsHashHexByNameByteRange 覆蓋的已簽署內容的十六進位摘要
SetSignatureValue把完成的簽章寫入保留的 /Contents 空間並記錄 DocMDP 層級
SetSignatureFieldLock寫入帶動作與欄位名稱清單的欄位鎖定字典
SetSignatureImage, SetSignatureAppearanceText, SetSignatureBounds控制可見外觀：繪製的影像、v3.221.0 實作的純文字外觀串流，以及明確的欄位邊界
GetDocumentBytes, GetDocumentSize, ReadDocumentRange直接存取底層位元組，可在外部對整個檔案或 ByteRange 區段做雜湊
GetDSSValidationMaterial回傳欄位的 DSS 憑證、CRL 與 OCSP 回應，並回報是否使用了 VRI 證據
SetSignatureFlags, EnsurePAdESExtensions調整 /SigFlags 並加入 ETSI PAdES 擴充 schema

參數

IsOpen成功開啟後到 Close 之前為 True
SignatureFieldPosition所選簽章欄位內容的檔案偏移
SignatureFieldLength為所選簽章內容保留的位元組長度

備註

由於兩個 ByteRange 區段加起來幾乎涵蓋整個檔案，GetDocumentBytes 會把整個檔案物化到記憶體

若簽署流程不想碰這個底層介面，facade 透過文件記載的 SignProcess 函式暴露等效管線

另請參閱

TPDFlibSignatureVerifier, TPDFlibPFXFile, TPDFlibSigner, NewSignProcessFromFile, GetSignProcessByteRange