Cấu hình TSA

Tổng quan nhanh

NextPDF chỉ liên hệ một Cơ quan Dấu thời gian (TSA) khi bạn ký ở mức PAdES B-T trở lên. Ở mức B-B không có dấu thời gian và không có lệnh gọi mạng, nên trang này không áp dụng cho một chữ ký B-B.

Để B-T hoạt động ngay từ đầu, NextPDF đi kèm một TSA mặc định tích hợp sẵn. Mặc định đó là một tiện ích: nó cho phép một chữ ký có dấu thời gian thành công mà không cần cấu hình thêm. Nó không được tin cậy công khai và không đủ điều kiện theo eIDAS, nên nó không phù hợp cho việc sử dụng trong môi trường sản xuất hay cho mục đích tuân thủ nếu không có một lựa chọn có chủ đích. Trang này giải thích chính xác mặc định là gì, cách trỏ NextPDF đến TSA của riêng bạn, cách tắt việc đóng dấu thời gian, và hai lộ trình nâng cấp.

Ba thuộc tính sau đây là độc lập và không được nhầm lẫn với nhau:

tự lưu trữ — ai vận hành máy chủ và chứng chỉ của nó dẫn về root nào;
tin cậy công khai — liệu hệ sinh thái xác thực mà các bên đối tác tin cậy của bạn sử dụng (kho tin cậy hoặc danh sách tin cậy của họ) đã tin cậy sẵn root đó mà không cần thiết lập thủ công, thay vì yêu cầu cài đặt một root riêng bằng tay hay không. Điều này liên quan đến các trust anchor của bên đối tác tin cậy, chứ không phải bất kỳ một chương trình cụ thể nào như Web PKI;
đủ điều kiện theo eIDAS — liệu dấu thời gian có mang hiệu lực pháp lý đủ điều kiện trong EU hay không.

Mặc định đi kèm chỉ là tự lưu trữ. Một TSA được tin cậy công khai bổ sung thuộc tính thứ hai. Một TSA đủ điều kiện theo eIDAS bổ sung thêm địa vị pháp lý đủ điều kiện, được xác thực thông qua EU Trusted Lists, và có thể được vận hành bởi một QTSP bên thứ ba. Ba thuộc tính này là độc lập — thuộc tính này không hàm ý thuộc tính kia.

TSA mặc định tích hợp sẵn

Endpoint mặc định là https://timestamp.pateon.com.tw, máy chủ đóng dấu thời gian RFC 3161 của riêng NextPDF. Nó là tự lưu trữ: chứng chỉ đơn vị đóng dấu thời gian của nó dẫn về một PATEON root riêng, chứ không phải về một chương trình tin cậy công khai. Vì vậy, một bên đối tác tin cậy không thể xác thực một dấu thời gian do mặc định phát hành trừ khi nó đã cài đặt và tin cậy PATEON root đó ngoài luồng.

Bởi vì một token RFC 3161 không mang bất kỳ bằng chứng bên ngoài nào cho thấy thời gian được khẳng định là đúng, sự tin cậy đối với bất kỳ dấu thời gian nào như vậy hoàn toàn dựa vào việc tin cậy TSA phát hành (ISO/IEC 18014-2 §7.3). Đối với mặc định đi kèm, trust anchor đó là riêng, đó là lý do mặc định là một mặc định tiện ích và phát triển, không phải một mặc định đạt chuẩn tuân thủ.

Khi endpoint mặc định đang được sử dụng và framework của bạn có một logger được cấu hình, NextPDF phát ra một cảnh báo một lần lúc tiến trình khởi động, lưu ý rằng mặc định không được tin cậy công khai và trỏ đến phần cấu hình này. Cảnh báo này mang tính thông tin; việc ký vẫn thành công.

Ghi đè mặc định

Đặt endpoint TSA trong cấu hình của bộ điều hợp framework của bạn. Khóa chính xác khác nhau tùy bộ điều hợp (xem bảng cấu hình theo từng framework): trong Laravel đó là biến môi trường NEXTPDF_TSA_URL, trong Symfony là nút bundle nextpdf.tsa.url, và trong CodeIgniter là khóa env nextPdf.tsa.url.

TSA hiệu lực được phân giải theo thứ tự ưu tiên này, cao nhất trước:

Một TsaClient tường minh mà bạn tự dựng và tự tiêm vào — cái này luôn thắng.
URL được cấu hình trong bộ điều hợp của bạn — được dùng khi bạn không tiêm một client.
Mặc định tích hợp sẵn — chỉ được dùng khi cả hai cái trên đều không được đặt.

# Laravel (.env): use your own publicly-trusted TSA instead of the shipped default.
NEXTPDF_TSA_URL=http://timestamp.digicert.com

Tắt dấu thời gian

Để nguyên url TSA của bộ điều hợp ở giá trị mặc định (chưa cấu hình) thì giữ lại endpoint mặc định tích hợp sẵn. Đặt url đó thành một giá trị rỗng thì khác: nó tắt việc đóng dấu thời gian. Khi không có TSA nào được cấu hình, một chữ ký được yêu cầu ở mức B-T trở lên sẽ fail-closed kèm lỗi “TSA required” thay vì âm thầm hạ xuống B-B.

# Laravel (.env):
# NEXTPDF_TSA_URL unset -> use the built-in default (timestamp succeeds against pateon).
# NEXTPDF_TSA_URL empty -> no TSA; a B-T+ request fails closed.
NEXTPDF_TSA_URL=

Chọn thuật toán băm cho messageImprint

Một yêu cầu dấu thời gian RFC 3161 mang theo một messageImprint — một băm của dữ liệu đang được đóng dấu thời gian — và NextPDF dùng SHA-256 cho imprint đó theo mặc định. Mặc định này là một lựa chọn có chủ đích, có khả năng tương tác; bạn hiếm khi cần thay đổi nó.

Khi bạn tự dựng một TsaClient bằng tay, bạn có thể chọn một thuật toán băm imprint khác thông qua tham số hàm dựng imprintHashAlgorithm, tham số này nhận một case TsaImprintHashAlgorithm: Sha256 (mặc định), Sha384, Sha512, Sha3_256, Sha3_384, hoặc Sha3_512. Mặc định giữ cho mọi yêu cầu được phát ra giống hệt từng byte so với các bản phát hành trước đó, nên việc nâng cấp không thay đổi gì trừ khi bạn chủ động chọn tham gia.

use NextPDF\Security\Timestamp\TsaClient;
use NextPDF\Security\Timestamp\TsaImprintHashAlgorithm;

// Default — SHA-256 imprint, unchanged from earlier releases:
$tsa = new TsaClient('https://timestamp.example.com/tsa');

// Opt in to a stronger imprint digest:
$tsa = new TsaClient(
    'https://timestamp.example.com/tsa',
    imprintHashAlgorithm: TsaImprintHashAlgorithm::Sha512,
);

Có hai ràng buộc đáng biết trước khi bạn rời khỏi mặc định:

Hệ sinh thái hiện chỉ hỗ trợ SHA-256. Một imprint không phải SHA-256 vẫn tương tác được với bộ xác minh token của Core, nhưng cổng chứng minh PAdES B-T của nextpdf-server và bản đồ băm xác thực của Premium hiện chỉ nhận diện các imprint SHA-256. Do đó, một dấu thời gian chữ ký được dựng bằng một thuật toán băm imprint khác sẽ chưa chứng minh được B-T trên các bề mặt đó. Hãy giữ mặc định trừ khi mọi bên tiêu thụ dấu thời gian của bạn được biết là chấp nhận thuật toán băm mà bạn chọn.
Các giá trị băm tính sẵn phải khớp với thuật toán. getDocumentTimestamp() nhận một băm tài liệu đã được tính sẵn; nó fail-closed, trước bất kỳ lệnh gọi mạng nào, khi độ dài của băm đó không khớp với thuật toán imprint đã cấu hình, thay vì gửi đi một yêu cầu không khớp.

Các lộ trình nâng cấp

Đối với bất cứ thứ gì vượt ra ngoài phạm vi phát triển hay sử dụng nội bộ, hãy thay thế mặc định bằng một trong hai lựa chọn mạnh hơn.

TSA được tin cậy công khai

Trỏ url TSA của bộ điều hợp đến một TSA có chứng chỉ dẫn về một public root mà các bên đối tác tin cậy của bạn đã tin cậy sẵn — ví dụ http://timestamp.digicert.com. Không cần phân phối một root riêng nào. Một TSA đạt chuẩn sản xuất thường sẽ tuyên bố tuân thủ một chính sách đóng dấu thời gian như ETSI EN 319 421 §5 và tuân theo hồ sơ giao thức RFC 3161 được mô tả trong ETSI EN 319 422 §7; hãy xác nhận điều này dựa trên chính sách đã công bố của nhà vận hành thay vì giả định nó chỉ từ việc được tin cậy công khai.

TSA đủ điều kiện theo eIDAS

Đối với những dấu thời gian phải mang hiệu lực pháp lý đủ điều kiện trong Liên minh Châu Âu, hãy dùng một dịch vụ đóng dấu thời gian đủ điều kiện từ một nhà cung cấp dịch vụ tin cậy đủ điều kiện (QTSP) được liệt kê trên một EU Trusted List. Một dấu thời gian điện tử đủ điều kiện ràng buộc thời gian với dữ liệu sao cho ngăn ngừa hợp lý mọi thay đổi không thể phát hiện, dựa trên một nguồn thời gian chính xác liên kết với Coordinated Universal Time, và được bảo vệ bằng một chữ ký điện tử nâng cao hoặc con dấu điện tử nâng cao của QTSP, hoặc bằng một phương pháp tương đương (Regulation (EU) 910/2014, Art 42). Đây là lựa chọn mạnh nhất và là lựa chọn nên chọn khi một quy định nêu rõ ràng dấu thời gian đủ điều kiện.

Cấu hình theo từng framework

Mặc định nằm trong cấu hình của từng bộ điều hợp framework, chứ không nằm trong engine lõi. Lõi không bao giờ tự nghĩ ra một URL: một TsaClient mà bạn dựng bằng tay đòi hỏi một endpoint tường minh và sẽ ném lỗi nếu nó rỗng. Các mức dài hạn (B-LT và B-LTA) tái sử dụng cùng một TSA đã được cấu hình như B-T.

Tích hợp	Mặc định nằm ở đâu	Cách ghi đè
Laravel	`config/nextpdf.php` -> `tsa.url`	đặt `NEXTPDF_TSA_URL` trong `.env`
Symfony	cấu hình bundle `nextpdf.tsa.url`	đặt nút đó, hoặc ràng buộc nó với một biến env
CodeIgniter	`Config\NextPdf::$tsa['url']`	ghi đè qua khóa env `nextPdf.tsa.url`
Plain core	không có mặc định ngầm	dựng một `TsaClient` với một URL tường minh + một client PSR-18 đã được tăng cường

Trong mọi bộ điều hợp, B-B không bao giờ dựng một TSA client, nên một chữ ký không có dấu thời gian không bị ảnh hưởng bởi bất kỳ cấu hình nào trong số này.

Mô hình tin cậy và các tiêu chuẩn

Giá trị của một dấu thời gian là chuỗi tin cậy đứng sau nó, chứ không phải bản thân các byte. Token RFC 3161 chỉ khẳng định một thời gian; liệu khẳng định đó có đáng tin hay không là một thuộc tính của TSA đã ký nó (RFC 3161 §2; ISO/IEC 18014-2 §7.3). Khi bạn giữ lại mặc định đi kèm, bạn đang chọn một trust anchor tự lưu trữ, riêng — phù hợp cho phát triển và các luồng công việc nội bộ nơi mọi bên đối tác tin cậy đều có thể cài đặt PATEON root, nhưng không phù hợp cho các tài liệu được bên thứ ba xác thực. Đối với những tài liệu đó, hãy chuyển sang một TSA được tin cậy công khai, hoặc sang một TSA đủ điều kiện theo eIDAS khi cần hiệu lực pháp lý đủ điều kiện.

Nếu bạn tự vận hành mặc định, bạn có thể ghim khóa công khai của TSA trong client PSR-18 do chính bạn tiêm vào. Không ghim mặc định đi kèm trong mã dùng chung: một lần xoay khóa ở phía nhà vận hành khi đó sẽ làm hỏng mọi người dùng mặc định cùng một lúc. Sự tin cậy đối với một dấu thời gian là chuỗi chứng chỉ và PATEON root, chứ không phải một bản ghim ở tầng truyền tải.