跳到內容
NextPDF

透過 NextPDF Connect（Pro）套用 PAdES 數位簽章

快速概覽

標題為「快速概覽」的區段

透過 NextPDF Connect 對 PDF 套用 PAdES 基準數位簽章。此工具為 sign_pdf，已依 Pro 工具提供者重新驗證：該提供者會註冊 new SignPdfTool()，其協定名稱為 sign_pdf。**sign_pdf 是 Pro 級工具。**伺服器啟動時會以 class_exists() 探測它，且只有在已安裝 Pro 套件時才會註冊。

此工具預設會產生 PAdES B-B。只有在主機已將時間戳記提供者接入此工具時，它才能產生 PAdES B-T（B-B 加上一個 RFC 3161 signature-time-stamp）；請求無法指定 TSA。長期保存等級（B-LT、B-LTA）及其驗證材料（DSS、VRI、LTV）並非此工具的一部分，也不在本頁範圍內。

U-1 注意事項。 NextPDF 並未主張任何獨立的 ETSI EN 319 142-1 PAdES B-T 認證。EN 319 142-1 不在驗證語料庫中。B-T 的 signature-time-stamp 需求是對照 ETSI EN 319 122-1 §5.3（EN 319 142-1/-2 以引用方式匯入的 CAdES 基礎依據），連同 RFC 3161、RFC 5652、RFC 5816 以及 ISO 32000-2 §12.8 加以驗證。對 B-T 設定檔的支援並非一致性或法律效力認證；該判定由獨立驗證器作出。

安裝

標題為「安裝」的區段
Terminal window
composer require nextpdf/server
composer require nextpdf/pro

綁定一種傳輸。以 diagnostic.capabilities 確認 sign_pdf 存在。若需 B-T，主機必須以時間戳記提供者來建構此工具。若沒有提供者，pades_b_t: true 的請求會以具型別錯誤失敗，而非默默降級。

概念總覽

標題為「概念總覽」的區段

sign_pdf 會計算檔案的位元組範圍摘要，並排除簽章值的預留位置（ISO 32000-2 §12.8.1）。接著，它會將 DER 編碼的 CMS SignedData 寫入簽章字典 Contents（ISO 32000-2 §12.8.1）。支援的演算法包括：RSA-SHA256（預設）、RSA + SHA-3（256/384/512）以及 Ed25519。對於並非端對端機密的傳輸，可選的 AES-GCM 封裝可包覆傳入的 private_key 酬載。

B-T 升級。 在 pades_b_t: true 且主機已接入時間戳記提供者時，簽章會升級為 PAdES B-T：位元組範圍雜湊會送往 TSA，並嵌入一個 TimeStampToken（ISO 32000-2 §12.8.5）。PAdES B-T 是在 B-B 上加入 一個作為未簽署屬性夾帶於 CMS SignerInfo 的 RFC 3161 signature-time-stamp（RFC 5652 §5.3）。未簽署屬性不受簽章涵蓋，因此 B-B 已簽署摘要及其有效性維持不變（RFC 5652 §5.3）。該屬性值為 SignatureTimeStampToken（ETSI EN 319 122-1 §5.3）。B-T 不會新增 DSS 字典、不會新增 VRI、不會新增驗證材料，也沒有封存時間戳記迴圈；這些都屬於 B-LT/B-LTA Enterprise 增量，不在此工具的範圍內。

U-1 注意事項（在 B-T 主張處重述）。 此處的 B-T 支援並非 EN 319 142-1 一致性或法律效力認證；由獨立驗證器決定。EN 319 142-1 不在驗證語料庫中。B-T 的依據是 ETSI EN 319 122-1 §5.3、RFC 3161、RFC 5652、RFC 5816 以及 ISO 32000-2 §12.8。

此工具流程——包含由主機把關的 TSA 介面（請求無法指定 TSA），以及失敗即關閉的 B-T 分支（絕不默默降級）——如下所示。

Host-wired RFC 3161 TSAPro SignPdfToolNextPDF Connect serverHost-wired RFC 3161 TSAPro SignPdfToolNextPDF Connect serveralt[host wired a TSA provider][no provider wired]alt[pades_b_t == true]MCP callercreate_pdf then add_text — build content1sign_pdf — certificate, private_key, pades_b_t?2dispatch — Pro tool, class_exists-probed at boot3Byte-range digest, build CMS SignedData — B-B4byte-range hash — request-unconfigurable endpoint5TimeStampToken6Embed token in unsignedAttrs — B-T7Typed error — NOT downgraded to B-B8signed PDF — level B-B or B-T9output_pdf — Approval Required gate10result — pdf, level, timestamped11MCP caller
Diagram

API 介面

標題為「API 介面」的區段
工具級別角色風險等級
create_pdf、add_textCore建立內容安全 / 注意
sign_pdfPro套用 PAdES B-B（或主機把關的 B-T）需要核可
output_pdfCore轉譯並回傳 PDF需要核可 / 審查（base64）

工具名稱就是註冊表中的協定名稱；工具型錄 是正式型錄。可用工具取決於已安裝的級別，而 Pro 中沒有長期保存等級工具。

程式碼範例——快速上手

標題為「程式碼範例——快速上手」的區段
  1. create_pdf → 以 add_text 建立內容。
  2. sign_pdf，搭配 certificate（PEM）、private_key（PKCS#8 PEM）、可選的 signer_name、reason 以及 algorithm。 若要 B-B，請省略 pades_b_t（或將其設為 false）。
  3. output_pdf。

此工具會回傳以下結果封裝：

{
  "pdf": "<base64 of the signed PDF>",
  "signature_count": 1,
  "is_complete": true,
  "algorithm": "RSA_SHA256",
  "oid": "<algorithm OID>",
  "digest": "<digest algorithm>",
  "level": "PAdES-B-B",
  "timestamped": false
}

若要主機把關的 B-T 簽章，請傳送 pades_b_t: true；level 會變成 "PAdES-B-T"，而 timestamped 也會變成 true。

程式碼範例——正式環境

標題為「程式碼範例——正式環境」的區段

把簽署視為最後一個內容操作。在 sign_pdf 之後的任何 add_text/add_image 都會使簽章失效。在非機密傳輸上，請以 AES-GCM transport_encryption 封裝包覆 private_key（12 位元組 nonce；16/24/32 位元組金鑰）。確認結果的 level 與你所請求的相符。若對沒有提供者的工具發出 pades_b_t: true 的請求，會明確失敗：請處理該錯誤，且不要默默以 B-B 重試。

邊界情況與陷阱

標題為「邊界情況與陷阱」的區段
  • 憑證/金鑰不相符。 會以清楚的錯誤拒絕；私密金鑰必須與憑證的公開金鑰相符。
  • 格式錯誤的 PEM / 已過期的憑證。 會被拒絕；此工具預設不會以無法解析或已過期的憑證簽署。
  • 簽署後新增內容。 會被拒絕——請在最後一步才簽署。
  • 已請求 B-T，但沒有提供者。 會回傳具型別錯誤：簽章不會產生，也不會默默降級為 B-B。
  • 自我簽署的憑證。 簽章會套用，但閱讀器會顯示信任來源未知——這是預期行為，而非工具瑕疵。
  • 未安裝 Pro。 僅有 Core 時，sign_pdf 不會被註冊。

效能

標題為「效能」的區段

簽署會增加 CMS 建構成本；B-T 還會增加一次 TSA 來回；預算已涵蓋這些成本。此設定檔屬於 semantic：RFC 3161 權杖本質上不可重現，而 §12.8.1 位元組範圍摘要會排除簽章值，因此只有 AST 加上簽章中繼資料的比較才是如實的比較方式。

安全注意事項

標題為「安全注意事項」的區段

簽章提供以簽署金鑰為基準的完整性與身分驗證。它本身並不會讓文件「安全」、「具法律效力」，也不會保證不可否認性——那取決於憑證、其信任錨點、金鑰保管，以及驗證者的政策，這些全都在此工具之外。金鑰酬載的加密（AES-GCM 封裝）保護的是傳輸中的機密性，而非完整性。請將私密金鑰視為機密，並在任何非機密通道上優先使用傳輸加密封裝。

一致性

標題為「一致性」的區段
陳述規範條款reference_id
位元組範圍摘要涵蓋整個檔案，並排除簽章值。ISO 32000-2§12.8.1
Contents 持有 DER 編碼的 CMS SignedData。ISO 32000-2§12.8.1
對於時間戳記，位元組範圍雜湊會送往 TSA，且權杖會放入 Contents。ISO 32000-2§12.8.5
B-T 時間戳記是 SignerInfo 上的未簽署屬性。RFC 5652§5.3
未簽署屬性不會改變 B-B 已簽署的 digest/validity。RFC 5652§5.3
signature-time-stamp 值為 SignatureTimeStampToken。ETSI EN 319 122-1§5.3

NextPDF 會產生簽章結構。它並未主張任何最終簽章具有一致性或法律效力；這由獨立驗證器決定。此工具不會產生 B-LT/B-LTA。

商業脈絡

標題為「商業脈絡」的區段

sign_pdf 是 Pro 級工具，只有在伺服器啟動時能解析 Pro 套件時才會註冊。PAdES 長期保存等級（B-LT、B-LTA）及其驗證材料（DSS、VRI、LTV）為 Enterprise 專屬，不會由此工具或本食譜公開。

資料落地與 PII 緩解

標題為「資料落地與 PII 緩解」的區段

憑證與私密金鑰會隨請求一起傳輸。在任何並非端對端機密的通道上，請使用 AES-GCM transport_encryption 封裝。已簽署的 PDF 與簽署者身分（signer_name、reason）屬於文件內容，因此請將它們保留在你的資料落地邊界內。部署層級的落地由整合者負責。

安全遙測與日誌清理

標題為「安全遙測與日誌清理」的區段

絕不要記錄 private_key 酬載、AES-GCM key/nonce，或確認權杖。記錄演算法、最終的 level 以及 signature_count，而非金鑰材料。此工具不會在其結果中輸出金鑰位元組。

威脅模型

標題為「威脅模型」的區段

考量的威脅包括：傳輸中的金鑰外洩（由 AES-GCM 封裝以及主機注入、請求無法設定的 TSA 提供者緩解）；MCP 呼叫者把時間戳記指向任意端點（已防止——提供者由主機注入，無法透過請求設定）；以及簽署後的竄改（位元組範圍摘要可偵測修改）。威脅模型記錄已考量的威脅與緩解措施；它並不主張不存在漏洞。

FIPS 模式行為

標題為「FIPS 模式行為」的區段

演算法選擇（RSA-SHA256、RSA + SHA-3、Ed25519）由請求驅動；密碼學原語由主機的 OpenSSL 提供。在受 FIPS 限制的部署中，請在政策層限制演算法，並倚賴主機已驗證的模組。此工具本身並不主張 FIPS 驗證。

傳輸可用性

標題為「傳輸可用性」的區段
傳輸可用附註
MCP（stdio）是（Pro）在 stdio 上使用 AES-GCM 金鑰封裝。
REST是（Pro）優先使用 TLS 加上金鑰封裝。
gRPC是（Pro）優先使用 TLS 加上金鑰封裝。

HITL 風險等級

標題為「HITL 風險等級」的區段

sign_pdf 屬於「需要核可」（一項破壞性、不可逆的操作——此工具會公告破壞性提示）。確認關卡的套用方式與任何「需要核可」工具相同。output_pdf 輸出至檔案同樣屬於「需要核可」；base64 模式則為「審查」（HITL 風險等級）。

確認關卡 JSON 封裝

標題為「確認關卡 JSON 封裝」的區段

沒有有效權杖的 sign_pdf 會回傳挑戰封裝：

{
  "allowed": false,
  "challenge": "⚠️ CONFIRMATION REQUIRED\n\nOperation: sign_pdf\nDescription: <tool description>\n\nTo proceed, call sign_pdf again with parameter _confirmation_token: \"confirm_<single-use-hex>\"\nExpires in 300 seconds.",
  "token": "confirm_<single-use-hex>"
}

將 _confirmation_token 設為該權杖並重新呼叫 → { "allowed": true }。完整流程：輸出核可。

另見

標題為「另見」的區段