PDFium Delphi Component 文件

FPdfCryptoWin 單元

單元: FPdfCryptoWin
用於 PAdES 簽署、分離式 CMS 驗證與僅快取系統憑證信任評估的 Windows 密碼學 API 後端

Syntax

function WinCryptoAvailable: Boolean;
function WinCmsVerificationAvailable: Boolean;
function VerifyWinDetachedCms(const CmsDer: TBytes; Segment1: Pointer; Segment1Length: Cardinal; Segment2: Pointer; Segment2Length: Cardinal): TWinCmsVerifyResult;
function VerifyWinDetachedCmsEx(const CmsDer: TBytes; Segment1: Pointer; Segment1Length: Cardinal; Segment2: Pointer; Segment2Length: Cardinal; const Options: TWinCmsVerifyOptions): TWinCmsVerifyResult;
function VerifyWinAttachedCmsEx(const CmsDer: TBytes; const Options: TWinCmsVerifyOptions): TWinCmsVerifyResult;
function ResolveWinSigner(const Options: TPadesSignerOptions): TPadesResolvedSigner;
function TestBuildWinCmsTrust(SignerCert: Pointer;
  const Options: TWinCmsVerifyOptions; GetChain, VerifyPolicy,
  FreeChain: Pointer): TWinCmsVerifyResult; // PDFIUMPAS_CRYPTO_TESTS only

Description

FPdfCryptoWin 是 FPdfCrypto 使用的 Windows 專屬密碼學後端。它透過 CryptoAPI 開啟目前使用者與本機電腦的憑證存放區,找出符合要求指紋的憑證,取得相關聯的 NCRYPT 私鑰控制代碼,並傳回 TPadesResolvedSigner,其 ICmsSigner 透過 CNG 簽署

WinCryptoAvailable 執行輕量檢查,確認 Crypt32 / ncrypt 繫結可解析,讓呼叫端能在啟動時判斷這台機器是否可進行 PAdES 簽署

VerifyWinDetachedCms 針對兩個呼叫端擁有的位元組區段驗證分離式 CMS 值,傳回簽署者憑證,並以僅快取的 Windows 基礎政策評估其鏈,而不執行網路擷取

擴充驗證函式接受 TWinCmsVerifyOptions,讓呼叫端能啟用線上憑證擷取、要求撤銷檢查、設定擷取逾時,並觀察驗證檢查點

簽章有效性與憑證信任是獨立的結果,因此來自不受信任或自我簽署憑證的真實簽章,仍可與遭竄改的內容區分

Functions

FunctionDescription
WinCryptoAvailable當 Windows Crypt32 與 ncrypt 繫結可在執行階段解析時傳回 True
WinCmsVerificationAvailable當分離式 CMS 驗證與憑證鏈政策 API 可用時傳回 True
VerifyWinDetachedCms驗證兩個分離內容區段上的 CMS 簽署屬性與簽章,並分別回報目前僅快取的系統信任
VerifyWinDetachedCmsEx以明確的線上擷取、撤銷、逾時與檢查點選項驗證分離式 CMS 內容
VerifyWinAttachedCmsEx驗證附加式 CMS 值,並使用提供的選項評估其簽署者憑證
ResolveWinSigner使用 Windows 憑證存放區與 CNG 私鑰,將指紋解析為簽署器、憑證 DER 與鏈
TestBuildWinCmsTrust只在 PDFIUMPAS_CRYPTO_TESTS 條件下編譯的測試掛鉤:把 CNG 鏈政策函式指標換成呼叫端提供的測試替身,在簽章狀態預先設為有效的情況下執行信任建置,然後還原指標,讓密碼學單元測試無需真實憑證鏈即可演練 BuildWinCmsTrust

驗證類型

Type成員與用途
TWinCmsVerifyStatuswcvsUnavailable、wcvsValid、wcvsInvalid、wcvsUnsupported 或 wcvsIndeterminate
TWinCmsVerifyStagewcvstCryptographicSignature、wcvstChainBuild、wcvstOnlineRetrieval 或 wcvstRevocationCheck
TWinCmsVerifyCheckpoint接收每個 TWinCmsVerifyStage 的物件方法回呼
TWinCmsVerifyOptionsOnlineRetrieval、CheckRevocation、CollectChainCertificates、UrlRetrievalTimeoutMs、OnCheckpoint 與靜態 Default 工廠
TWinCmsVerifyResultTPdfCmsVerifyResult 的別名,包含 SignatureStatus、TrustStatus、RevocationStatus、SignatureError、TrustError、SignerCertificate、ChainCertificates、RevocationReason 與 RevocationError

撤銷結果

啟用 CheckRevocation 時,後端會建立一條獨立的撤銷鏈,並填入 RevocationStatus、RevocationReason 與 RevocationError。撤銷失敗不會覆寫簽章結果,也不會覆寫獨立評估的 TrustStatus 與 TrustError

對格式良好的原生鏈而言,已確認的撤銷會產生 wcvsInvalid 搭配 pcrrCertificateRevoked。沒有已確認撤銷時,不受信任的鏈會產生 wcvsIndeterminate 搭配 pcrrChainUntrusted;不完整的原生結構與其他未解決的撤銷檢查則維持 wcvsIndeterminate 搭配 pcrrUnknown

有效的結果需要:鏈受信任、鏈沒有錯誤、至少有一張憑證需要撤銷檢查,且每張這類憑證都取得成功的原生撤銷結果。只有終端憑證被明確標記為自我簽署或受信任的 CA 錨點時,才豁免於這項涵蓋要求;只到根憑證的鏈或缺少個別憑證證據時,結果仍是不確定

RevocationError 保留 CERT_REVOCATION_INFO.dwRevocationResult 的原始 DWORD,或在撤銷鏈呼叫失敗時保留當下的 GetLastError 值。零表示沒有可用的原生診斷,包括鏈狀態已確立撤銷卻沒有對應提供者代碼的情況。彙總的 CERT_TRUST_STATUS.dwErrorStatus 位元用於分類,不會被複製到這個欄位充當捏造的原生錯誤

請在該值的 Windows 提供者或 API 脈絡下解讀原始值;它不保證是 HRESULT。離線、過期或未知的撤銷證據無法辨識 CRL 過期、CRL 損毀或 CRL 簽章錯誤,因此本後端不推測這些細部原因

在 OnlineRetrieval = False 時,鏈建置與撤銷檢查都只使用快取擷取。啟用線上擷取後,Windows 鏈引擎才能在設定的擷取逾時內取得所需的支援證據

Remarks

See Also

FPdfCrypto, FPdfCms