Hợp đồng

Tổng quan nhanh

NextPDF Enterprise phơi bày một bộ nhỏ các interface công khai mà các thành phần Enterprise ràng buộc theo để đảo ngược phụ thuộc và có thể kiểm thử. Cái đầu tiên là một hợp đồng TSA-client để yêu cầu các timestamp token RFC 3161. Đây là các mối nối tích hợp. Bản thân chúng không thực hiện thao tác mã hóa nào hay khẳng định bất kỳ sự phù hợp tiêu chuẩn nào.

Tính khả dụng & cấp phép

Năng lực này đi kèm trong NextPDF Enterprise (nextpdf/enterprise) và kích hoạt bằng một license envelope bậc Enterprise. Một triển khai không có quyền đó sẽ không nạp các lớp của năng lực này. So sánh các phiên bản và nhận giấy phép.

Cài đặt

composer require nextpdf/enterprise:^3

Tổng quan khái niệm

TsaClientInterface khai báo một thao tác: getDocumentTimestamp($documentHash) trả về một RFC 3161 TimeStampToken mã hóa DER cho một document hash. Các thành phần Enterprise nhận interface này thay vì một client cụ thể để hành vi đóng dấu thời gian có thể được tiêm và thay thế trong các bài kiểm thử.

TsaClientAdapter là một lớp bọc mỏng thích ứng TSA client của Core với interface này. Client của Core là một lớp final và không thể triển khai trực tiếp một interface của Enterprise, nên adapter làm cầu nối giữa hai thứ mà không thay đổi hành vi. Hãy tiêm TsaClientInterface ở mọi nơi; nối dây TsaClientAdapter (hoặc bản triển khai của riêng bạn) tại composition root.

Module này khẳng định những gì

Module này định nghĩa các hợp đồng tích hợp. Bản thân nó không làm gì.

• TsaClientInterface mô tả cách lấy một timestamp token. Nó không xác thực token, không bảo chứng cho TSA, hay khẳng định rằng token mang lại hiệu lực pháp lý.
• TsaClientAdapter chuyển tiếp các lệnh gọi không thay đổi; nó không thêm hành vi và không thêm bảo đảm nào.

Việc lấy một timestamp token hỗ trợ các quy trình kiểm toán và xác thực dài hạn; nó không phải là một chứng thực pháp lý hay một chứng nhận.

Ranh giới giữa các bậc

Contracts là một bề mặt tích hợp chỉ dành cho Enterprise. TSA client cụ thể nằm trong Core (NextPDF\Security\Timestamp); module này chỉ cung cấp interface hướng-Enterprise và adapter để các thành phần Enterprise vẫn tách rời và có thể kiểm thử.

Vì sao nó hoạt động theo cách này

TsaClient của Core là một lớp final, nên nó không thể triển khai trực tiếp một interface của Enterprise. Enterprise vẫn cần một mối nối đóng dấu thời gian có thể tiêm và giả lập được để đảo ngược phụ thuộc và có các thành phần kiểm thử được. NextPDF giải quyết điều này bằng cách sở hữu interface ở bậc Enterprise và làm cầu nối cho client cụ thể của Core qua một adapter mỏng. Lượt khứ hồi vẫn nằm trong Core; Enterprise có được một hợp đồng ổn định mà không sao chép client hay nới lỏng bảo đảm final. Việc thay thế một bản triển khai giả trong các bài kiểm thử khi đó không đòi hỏi thay đổi mã của Core.

Bối cảnh thiết kế: Dấu thời gian và thời gian tin cậy.

Bề mặt API

Lớp / Interface	Trách nhiệm
TsaClientInterface	Hợp đồng: yêu cầu một timestamp token RFC 3161 mã hóa DER.
TsaClientAdapter	Thích ứng TSA client của Core với TsaClientInterface.

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

use NextPDF\Enterprise\Contracts\TsaClientInterface;

final class MySigner
{
    public function __construct(private TsaClientInterface $tsa) {}
}

Mẫu mã — Sản phẩm

use NextPDF\Enterprise\Contracts\TsaClientAdapter;

// Composition root: bridge the Core client into the Enterprise contract.
$tsa = new TsaClientAdapter($coreTsaClient);
$container->set(TsaClientInterface::class, $tsa);
// Components depend on the interface; the adapter is wired once here.

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

• Adapter chuyển tiếp các ngoại lệ từ client nền không thay đổi; hãy xử lý các lỗi TSA tại điểm gọi.
• Một token được trả về là các byte, không phải một phán quyết; hãy xác thực và xác minh nó ở nơi cần (xem Evidence / Signature).

Hiệu năng

Interface và adapter không thêm chi phí đáng kể nào; chi phí hoàn toàn là lượt khứ hồi TSA nền.

Lưu ý bảo mật

Hãy coi điểm cuối TSA phía sau client cụ thể là một ranh giới tin cậy. Hợp đồng này không xác thực token hay chuỗi chứng chỉ TSA; việc xác minh thuộc về các bề mặt ký và bằng chứng.

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

Chỉ một document hash đi qua hợp đồng này — không có nội dung tài liệu. Các cân nhắc về lưu trú áp dụng cho bản triển khai TSA client cụ thể, không phải cho interface này.

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

Một document hash là an toàn để ghi nhật ký. Đừng ghi nhật ký các byte token thô tới các đích chung; hãy coi chúng là các tạo phẩm nhạy cảm về tính toàn vẹn.

Tính phù hợp

Hành vi	Tham chiếu	Trạng thái
Yêu cầu và ràng buộc timestamp-token	IETF RFC 3161 §2	Chỉ là hình dạng hợp đồng (công việc do client cụ thể thực hiện)

Bảng này ghi lại đặc tả mà hợp đồng được định hình theo. Interface định nghĩa một mối nối; nó không đưa ra tuyên bố phù hợp tiêu chuẩn hay chứng thực nào.

Hành vi ở chế độ FIPS

Module này không thực hiện thao tác mã hóa nào. TSA client cụ thể và module Security chi phối việc chọn thuật toán và hành vi ở chế độ FIPS.

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

Bề mặt hợp đồng là tối thiểu: một hash vào, các byte token ra. Biện pháp giảm thiểu: không có nội dung nào đi qua ranh giới, và các trách nhiệm xác minh được ủy thác tường minh cho các module Evidence và Signature.

Hợp đồng hành vi

• Interface TSA-client khai báo một thao tác: trả về một RFC 3161 TimeStampToken mã hóa DER cho một document hash; các thành phần Enterprise phụ thuộc vào interface, không phải một client cụ thể.
• Adapter là một lớp bọc mỏng làm cầu nối TSA client của Core tới interface này mà không thay đổi hành vi và chuyển tiếp các ngoại lệ từ client nền không thay đổi.
• Interface mô tả cách lấy một token; nó không xác thực token, không bảo chứng cho TSA, hay khẳng định hiệu lực pháp lý.
• Một token được trả về là các byte, không phải một phán quyết — việc xác thực và xác minh thuộc về các bề mặt Evidence và Signature.

Ranh giới công bố

Trang này chỉ ghi lại hành vi có thể quan sát được từ bên ngoài và bề mặt API công khai được hỗ trợ. Các đường dẫn namespace nội bộ, các lớp trợ giúp, các bảng cơ chế, các tên tệp runbook, và các tiền tố ticket nằm ngoài phạm vi.

Phương án dự phòng Core

TSA client cụ thể nằm trong Core; module này chỉ cung cấp interface hướng-Enterprise và adapter để các thành phần Enterprise vẫn tách rời và có thể kiểm thử. Bản thân mối nối hướng-Enterprise không có phương án tương đương ở bậc Core — Core phơi bày client cụ thể, không phải interface này.

Phương án dự phòng Pro

Phương án dự phòng Pro — không có; năng lực này không có phương án tương đương ở bậc Pro. Interface TSA-client hướng-Enterprise và adapter chỉ đi kèm trong gói nextpdf/enterprise.

Lưu ý về ranh giới Enterprise

Interface và adapter được mô tả ở mức hành vi. Adapter chuyển tiếp các lệnh gọi không thay đổi và không thêm hành vi nào; TSA client cụ thể và chi tiết nội bộ của nó là mối bận tâm của Core và nằm ngoài phạm vi của bề mặt tích hợp Enterprise này.

Ranh giới triển khai

Chỉ một document hash đi qua hợp đồng này — không có nội dung tài liệu. Người vận hành nối dây adapter hoặc một bản triển khai tùy chỉnh tại composition root và sở hữu TSA client cụ thể phía sau nó; việc lưu trú, ranh giới tin cậy điểm cuối TSA, và việc xác minh chuỗi chứng chỉ áp dụng cho client cụ thể đó, không phải cho interface này.

Ranh giới tuân thủ pháp lý

Không có hạn chế kiểm soát xuất khẩu nào áp dụng cho bề mặt hợp đồng này. Việc lấy một timestamp token hỗ trợ các quy trình kiểm toán và xác thực dài hạn; nó không phải là một chứng thực pháp lý hay một chứng nhận. Tài liệu này không phải là một ý kiến pháp lý; hãy tham vấn các cố vấn tuân thủ và pháp lý của riêng bạn.

Xem thêm

• Contracts — Deep Reference — toàn bộ bề mặt lớp và phương thức.
• Evidence — nhúng các token RFC 3161 vào các gói.
• Validation — các kiểm tra cấu trúc LTV.
• Specifications: PAdES — bối cảnh dấu thời gian.