Áp dụng chữ ký số PAdES bằng NextPDF Connect (Pro)

Tổng quan nhanh

Áp dụng chữ ký số PDF Advanced Electronic Signatures (PAdES) mức cơ sở cho một PDF bằng NextPDF Connect. Dùng sign_pdf; công cụ này đã được xác minh lại với nhà cung cấp công cụ Pro: nhà cung cấp đó đăng ký new SignPdfTool(), với tên giao thức là sign_pdf. sign_pdf là một công cụ bậc Pro. Khi khởi động, máy chủ kiểm tra công cụ này bằng class_exists() và chỉ đăng ký khi gói Pro đã được cài đặt.

Theo mặc định, công cụ tạo ra PAdES B-B. Công cụ chỉ có thể tạo PAdES B-T (B-B cộng với một signature-time-stamp theo RFC 3161) khi máy chủ đã kết nối nhà cung cấp dấu thời gian với công cụ; yêu cầu không thể trỏ tới một Time Stamp Authority (TSA). Các cấp độ dài hạn (B-LT, B-LTA) và vật liệu xác thực của chúng (DSS, VRI, LTV) không thuộc công cụ này và nằm ngoài phạm vi ở đây.

Lưu ý U-1. NextPDF không khẳng định có bất kỳ chứng nhận ETSI EN 319 142-1 độc lập nào cho PAdES B-T. EN 319 142-1 không nằm trong kho ngữ liệu xác minh. Yêu cầu signature-time-stamp của B-T đã được xác minh dựa trên ETSI EN 319 122-1 §5.3 (cơ sở CAdES mà EN 319 142-1/-2 nhập theo tham chiếu), cùng với RFC 3161, RFC 5652, RFC 5816, và ISO 32000-2 §12.8. Việc hỗ trợ hồ sơ B-T không phải là chứng nhận tuân thủ hay xác nhận hiệu lực pháp lý; một trình xác thực độc lập mới đưa ra kết luận đó.

Cài đặt

composer require nextpdf/server
composer require nextpdf/pro

Gắn kết một transport, rồi xác nhận rằng sign_pdf tồn tại bằng diagnostic.capabilities. Đối với B-T, máy chủ phải khởi tạo công cụ cùng với nhà cung cấp dấu thời gian. Nếu không, yêu cầu pades_b_t: true sẽ thất bại bằng một lỗi có kiểu thay vì âm thầm hạ cấp.

Tổng quan khái niệm

sign_pdf tính một bản tóm tắt theo dải byte trên toàn tệp, loại trừ phần giữ chỗ cho giá trị chữ ký (ISO 32000-2 §12.8.1). Sau đó, công cụ ghi SignedData Cryptographic Message Syntax (CMS) mã hóa theo Distinguished Encoding Rules (DER) vào từ điển chữ ký Contents (ISO 32000-2 §12.8.1). Các thuật toán được hỗ trợ là RSA-SHA256 (mặc định), RSA + SHA-3 (256/384/512), và Ed25519. Đối với các transport không bảo mật đầu cuối, bạn có thể bọc payload private_key gửi đến trong một lớp bọc AES-GCM tùy chọn.

Nâng cấp B-T. Với pades_b_t: true và một nhà cung cấp dấu thời gian do máy chủ kết nối, chữ ký được nâng cấp lên PAdES B-T: giá trị băm theo dải byte được gửi tới một TSA và một TimeStampToken được nhúng vào (ISO 32000-2 §12.8.5). B-T chính xác là B-B cộng với một signature-time-stamp theo RFC 3161 được mang dưới dạng thuộc tính không ký trên SignerInfo của CMS (RFC 5652 §5.3). Các thuộc tính không ký không được chữ ký bao phủ, nên bản tóm tắt B-B đã ký và hiệu lực của nó không thay đổi (RFC 5652 §5.3). Giá trị của thuộc tính là một SignatureTimeStampToken (ETSI EN 319 122-1 §5.3). B-T không thêm từ điển Document Security Store (DSS), không thêm Validation Related Information (VRI), không thêm vật liệu xác thực, và không thêm vòng lặp dấu thời gian lưu trữ. Đó là điểm khác biệt B-LT/B-LTA của Enterprise và nằm ngoài phạm vi của công cụ này.

Lưu ý U-1 (lặp lại ở phần khẳng định B-T). Việc hỗ trợ B-T ở đây không phải là chứng nhận tuân thủ EN 319 142-1 hay hiệu lực pháp lý; một trình xác thực độc lập mới quyết định điều đó. EN 319 142-1 không nằm trong kho ngữ liệu xác minh. B-T dựa trên ETSI EN 319 122-1 §5.3, RFC 3161, RFC 5652, RFC 5816, và ISO 32000-2 §12.8.

Luồng bên dưới cho thấy đường dẫn TSA do máy chủ kiểm soát (yêu cầu không thể trỏ tới một TSA) và nhánh B-T an toàn khi thất bại (không bao giờ âm thầm hạ cấp).

Diagram

Bề mặt API

Công cụ	Bậc	Vai trò	Bậc rủi ro
create_pdf, add_text	Core	Xây dựng nội dung	An toàn / Thận trọng
sign_pdf	Pro	Áp dụng PAdES B-B (hoặc B-T do máy chủ kiểm soát)	Yêu cầu phê duyệt
output_pdf	Core	Kết xuất và trả về PDF	Yêu cầu phê duyệt / Rà soát (base64)

Tên công cụ là tên giao thức trong registry. Danh mục công cụ là danh mục chính thức. Các công cụ có sẵn phụ thuộc vào bậc đã cài đặt; các công cụ cấp độ dài hạn không có trong Pro.

Mẫu mã — bắt đầu nhanh

1. create_pdf → xây dựng nội dung bằng add_text.
2. sign_pdf với certificate (PEM), private_key (PKCS#8 PEM), tùy chọn signer_name, reason, và algorithm. Bỏ qua pades_b_t (hoặc đặt là false) để dùng B-B.
3. output_pdf.

Công cụ trả về lớp bọc kết quả sau:

{
  "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
}

Với chữ ký B-T do máy chủ kiểm soát, hãy gửi pades_b_t: true; level trở thành "PAdES-B-T", và timestamped trở thành true.

Mẫu mã — sản xuất

Hãy ký tại thao tác nội dung cuối cùng. Bất kỳ add_text/add_image nào sau sign_pdf đều làm chữ ký mất hiệu lực. Trên một transport không bảo mật, hãy bọc private_key trong lớp bọc AES-GCM transport_encryption (nonce 12 byte; khóa 16/24/32 byte). Hãy xác minh rằng level kết quả khớp với yêu cầu của bạn. Một yêu cầu pades_b_t: true gửi tới công cụ không có nhà cung cấp sẽ thất bại rõ ràng. Hãy xử lý lỗi đó và đừng âm thầm thử lại dưới dạng B-B.

Trường hợp biên & điểm cần lưu ý

• Chứng chỉ/khóa không khớp. Công cụ từ chối yêu cầu kèm theo lỗi rõ ràng; khóa riêng phải khớp với khóa công khai của chứng chỉ.
• PEM sai định dạng / chứng chỉ hết hạn. Công cụ từ chối yêu cầu; theo mặc định, công cụ không ký bằng chứng chỉ không thể phân tích hoặc đã hết hạn.
• Nội dung sau khi ký. Công cụ từ chối yêu cầu — hãy ký sau cùng.
• Yêu cầu B-T nhưng không có nhà cung cấp. Công cụ trả về một lỗi có kiểu: chữ ký không được tạo ra và không bị âm thầm hạ cấp xuống B-B.
• Chứng chỉ tự ký. Chữ ký được áp dụng, nhưng các trình đọc hiển thị mức tin cậy không xác định. Đó là điều dự kiến, không phải lỗi của công cụ.
• Không có Pro. Khi chỉ có Core, máy chủ không đăng ký sign_pdf.

Hiệu năng

Việc ký thêm bước dựng CMS và, đối với B-T, một lượt đi-về với TSA; ngân sách bao gồm cả hai. Hồ sơ là semantic: một token RFC 3161 về bản chất không thể tái tạo, và bản tóm tắt theo dải byte §12.8.1 loại trừ giá trị chữ ký. Chỉ dùng phép so sánh AST + siêu dữ liệu chữ ký.

Ghi chú bảo mật

Một chữ ký cung cấp tính toàn vẹn và xác thực tương ứng với khóa ký. Bản thân nó không làm cho tài liệu trở nên “bảo mật” hay “có hiệu lực pháp lý”, cũng không bảo đảm tính chống chối bỏ. Những kết quả đó phụ thuộc vào chứng chỉ, điểm neo tin cậy của nó, việc lưu giữ khóa, và chính sách của bên xác minh; tất cả đều nằm ngoài công cụ này. Việc mã hóa payload khóa bằng lớp bọc AES-GCM bảo vệ tính bảo mật khi truyền, chứ không phải tính toàn vẹn. Hãy coi khóa riêng là bí mật, và ưu tiên dùng lớp bọc mã hóa truyền tải trên bất kỳ kênh không bảo mật nào.

Tuân thủ

Tuyên bố	Đặc tả	Điều khoản	reference_id
Bản tóm tắt theo dải byte bao phủ toàn tệp và loại trừ giá trị chữ ký.	ISO 32000-2	§12.8.1
Contents chứa SignedData CMS mã hóa theo DER.	ISO 32000-2	§12.8.1
Đối với dấu thời gian, giá trị băm theo dải byte được gửi tới một TSA và token được đặt vào Contents.	ISO 32000-2	§12.8.5
Dấu thời gian B-T là một thuộc tính không ký trên SignerInfo.	RFC 5652	§5.3
Các thuộc tính không ký không làm thay đổi digest/validity đã ký của B-B.	RFC 5652	§5.3
Giá trị signature-time-stamp là một SignatureTimeStampToken.	ETSI EN 319 122-1	§5.3

NextPDF tạo ra cấu trúc chữ ký. NextPDF không khẳng định bất kỳ chữ ký kết quả nào là tuân thủ hay có hiệu lực pháp lý; một trình xác thực độc lập quyết định điều đó. Công cụ này không tạo ra B-LT/B-LTA.

Bối cảnh thương mại

sign_pdf là một công cụ bậc Pro. Máy chủ chỉ đăng ký công cụ này khi gói Pro được phân giải lúc máy chủ khởi động. Các cấp độ dài hạn của PAdES (B-LT, B-LTA) và vật liệu xác thực của chúng (DSS, VRI, LTV) chỉ có ở Enterprise và không được công cụ này hay công thức này phơi bày.

Lưu trú dữ liệu & biện pháp giảm thiểu PII

Chứng chỉ và khóa riêng đi qua yêu cầu. Hãy dùng lớp bọc AES-GCM transport_encryption trên bất kỳ kênh nào không bảo mật đầu cuối. PDF đã ký và danh tính người ký (signer_name, reason) là nội dung tài liệu, nên hãy giữ chúng trong phạm vi lưu trú dữ liệu của bạn. Bên tích hợp chịu trách nhiệm về lưu trú ở cấp triển khai.

Đo từ xa an toàn & làm sạch nhật ký

Đừng bao giờ ghi nhật ký payload private_key, key/nonce AES-GCM, hay token xác nhận. Hãy ghi nhật ký thuật toán, level kết quả, và signature_count, chứ không phải vật liệu khóa. Công cụ không phát ra byte khóa trong kết quả.

Mô hình mối đe dọa

Các mối đe dọa được xem xét: lộ khóa khi truyền (được giảm thiểu bằng lớp bọc AES-GCM và nhà cung cấp TSA do máy chủ tiêm vào, không thể cấu hình qua yêu cầu); một bên gọi MCP trỏ dấu thời gian tới một điểm cuối tùy ý (được ngăn chặn vì nhà cung cấp do máy chủ tiêm vào, không thể cấu hình qua yêu cầu); và việc giả mạo sau khi ký (bản tóm tắt theo dải byte phát hiện sự sửa đổi). Mô hình mối đe dọa ghi lại các mối đe dọa đã được xem xét và các biện pháp giảm thiểu; mô hình này không khẳng định rằng không tồn tại lỗ hổng.

Hành vi ở chế độ FIPS

Việc lựa chọn thuật toán (RSA-SHA256, RSA + SHA-3, Ed25519) do yêu cầu điều khiển. OpenSSL của máy chủ cung cấp các nguyên hàm mật mã. Trong một triển khai bị ràng buộc bởi FIPS, hãy giới hạn thuật toán ở lớp chính sách và dựa vào mô-đun đã được thẩm định của máy chủ. Bản thân công cụ này không khẳng định đã được thẩm định theo Federal Information Processing Standards (FIPS).

Khả dụng theo transport

Transport	Khả dụng	Ghi chú
MCP (stdio)	Có (Pro)	Hãy dùng lớp bọc khóa AES-GCM trên stdio.
REST	Có (Pro)	Ưu tiên TLS cùng với lớp bọc khóa.
gRPC	Có (Pro)	Ưu tiên TLS cùng với lớp bọc khóa.

Bậc rủi ro HITL

sign_pdf ở mức Yêu cầu phê duyệt vì đây là thao tác phá hủy, không thể đảo ngược; công cụ phát ra gợi ý phá hủy. Cổng xác nhận áp dụng như đối với bất kỳ công cụ Yêu cầu phê duyệt nào. output_pdf xuất ra một tệp cũng ở mức Yêu cầu phê duyệt; chế độ base64 ở mức Rà soát (Bậc rủi ro HITL).

Lớp bọc JSON của cổng xác nhận

sign_pdf mà không có token hợp lệ sẽ trả về lớp bọc thử thách:

{
  "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>"
}

Hãy gọi lại với _confirmation_token được đặt thành token → { "allowed": true }. Luồng đầy đủ: output-approval.

Xem thêm

• Trích xuất nội dung văn bản
• Kiểm tra khả năng tiếp cận
• Bậc rủi ro HITL
• Danh mục công cụ