Enterprise phiên bản

Contracts — Tài liệu tham chiếu chuyên sâu

Tổng quan nhanh

Module Contracts là điểm nối tích hợp Enterprise cho các client Time Stamp Authority theo RFC 3161.

TsaClientInterface khai báo một thao tác: yêu cầu một TimeStampToken mã hóa DER cho một digest tài liệu đã được tính trước.
TsaClientAdapter bắc cầu client timestamp của Core, một lớp final, sang interface đó mà không thay đổi hành vi.
Các thành phần Enterprise như LtvManager và DocumentTimestamp nhận interface, nên hành vi TSA có thể tiêm và thay thế được trong kiểm thử.
Chỉ một hash tài liệu vượt qua điểm nối; nội dung tài liệu thì không bao giờ.

Để có hướng dẫn quy trình, hãy đọc trang khả năng Contracts trước.

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

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

Bản thân interface không thực hiện công việc nào và không kiểm soát điều gì một cách độc lập. Các bề mặt Enterprise tiêu thụ tự thực thi mã khả năng của riêng chúng, chẳng hạn enterprise.compliance.evidence trên bề mặt bằng chứng tuân thủ.

Bậc	Cung cấp
Core	`TsaClient` cụ thể (`final`) thực hiện các yêu cầu RFC 3161
Pro	Không có thành phần tương đương của module Contracts
Enterprise	Điểm nối `TsaClientInterface` và cầu nối `TsaClientAdapter`

composer require nextpdf/enterprise:^3

Bề mặt Public API

Ký hiệu	Tham số	Hành vi mặc định	Trả về	Ném hoặc thất bại với	Ghi chú
`TsaClientInterface::getDocumentTimestamp()`	`string $documentHash`	Khai báo một yêu cầu timestamp-token cho một digest tài liệu đã tính trước	`string` — TimeStampToken mã hóa DER	Do hiện thực quy định; interface không khai báo exception nào	Thao tác duy nhất; nguồn ghi nhận đầu vào là một digest SHA-256
`TsaClientAdapter::__construct()`	`TsaClient $client`	Lưu client timestamp của Core	`TsaClientAdapter`	Không khai báo gì	`final readonly`; nâng cấp tham số hàm tạo
`TsaClientAdapter::getDocumentTimestamp()`	`string $documentHash`	Chuyển tiếp tới `TsaClient::getDocumentTimestamp()` mà không thay đổi	`string` — TimeStampToken mã hóa DER	`TsaException` từ client Core, chuyển tiếp mà không thay đổi	Không thêm hành vi; không nuốt gì

namespace NextPDF\Enterprise\Contracts;

interface TsaClientInterface
{
    /**
     * Request a timestamp token for a document hash.
     *
     * @param string $documentHash SHA-256 digest of the document content
     *
     * @return string DER-encoded TimeStampToken
     */
    public function getDocumentTimestamp(string $documentHash): string;
}

namespace NextPDF\Enterprise\Contracts;

use NextPDF\Security\Timestamp\TsaClient;

final readonly class TsaClientAdapter implements TsaClientInterface
{
    public function __construct(
        private TsaClient $client,
    )

    public function getDocumentTimestamp(string $documentHash): string
}

Hợp đồng hành vi

TsaClientInterface::getDocumentTimestamp(string $documentHash): string trả về một TimeStampToken RFC 3161 mã hóa DER cho một hash tài liệu. Các quy tắc quan sát được từ bên ngoài:

Interface khai báo một thao tác; nó không xác thực token, không bảo chứng cho TSA, và không khẳng định hiệu lực pháp lý.
TsaClientAdapter chuyển tiếp lệnh gọi tới client timestamp của Core mà không thay đổi — không thêm hành vi, không thêm lần thử lại, không nuốt exception, không thêm bảo đảm nào. Mục đích duy nhất của nó là cho phép một client Core final thỏa mãn một interface hướng tới Enterprise nhằm đảo ngược phụ thuộc và phục vụ kiểm thử.
Chỉ một hash tài liệu vượt qua ranh giới; không có nội dung tài liệu nào được truyền.
Phía sau adapter, client Core từ chối một digest có độ dài không khớp thuật toán imprint đã cấu hình của nó bằng TsaException, fail-closed, trước bất kỳ hoạt động mạng nào. Một imprint bị gán nhãn sai nếu không sẽ tạo ra một token mà không validator tuân thủ nào có thể ràng buộc.
Các bề mặt tiêu thụ: LtvManager nhận một TsaClientInterface tùy chọn và yêu cầu một cái cho PAdES B-LTA. DocumentTimestamp dùng hợp đồng để điền /Contents của một signature dictionary /DocTimeStamp. Bộ thực thi gia hạn lưu trữ LTV (LtvaRenewalExecutor) đấu nối một TsaClientAdapter quanh client Core khi gia hạn các timestamp tài liệu.

Trường hợp biên và chế độ thất bại

Adapter chuyển tiếp exception từ client bên dưới mà không thay đổi; các lỗi TSA phải được xử lý tại điểm gọi.
Digest phải là nhị phân thô theo thuật toán imprint đã cấu hình của client cụ thể (mặc định SHA-256, 32 byte). Một digest mã hóa hex có độ dài sai và bị từ chối trước khi gửi bất kỳ yêu cầu nào.
Một token trả về là byte, không phải một phán quyết; hãy xác thực nó ở nơi cần thiết.
Một hiện thực tùy chỉnh sở hữu bề mặt thất bại của riêng nó. Hợp đồng chỉ cố định hình dạng trả về: một TimeStampToken mã hóa DER.

Hành vi ở chế độ FIPS

Module này không thực hiện thao tác mật mã nào. Việc chọn thuật toán và hành vi ở chế độ FIPS do client TSA cụ thể và module Security quản lý. Xem tài liệu tham chiếu chuyên sâu FIPS 140.

Phù hợp tiêu chuẩn

Hành vi	Tham chiếu
Yêu cầu timestamp-token và ràng buộc	IETF RFC 3161 §2
Một TimeStampReq mang một MessageImprint: một định danh thuật toán hash và hash của dữ liệu cần đóng dấu thời gian	IETF RFC 3161 §2.4.1
messageImprint của token phải bằng giá trị của yêu cầu, với kích thước hash khớp thuật toán đã định danh	IETF RFC 3161 §2.4.2

Hợp đồng được định hình quanh RFC 3161; việc yêu cầu token thực tế và bất kỳ thao tác xác minh nào đều do client cụ thể cùng các bề mặt Evidence/Signature thực hiện. Interface không đưa ra tuyên bố phù hợp tiêu chuẩn hay chứng thực nào. NextPDF không đưa ra tuyên bố chứng nhận nào.

Ghi chú phát triển

Cả hai kiểu đều mang @since 3.0.0; tài liệu tham chiếu này mô tả bề mặt như được xuất xưởng trong nextpdf/enterprise 3.1.0.
Tiêm TsaClientInterface vào các thành phần cần timestamp; đấu nối TsaClientAdapter, hoặc một hiện thực tùy chỉnh, tại composition root. Thay bằng một test double trong kiểm thử đơn vị thay vì một TSA thật.
Người vận hành sở hữu client TSA cụ thể phía sau adapter: nơi lưu trú, ranh giới tin cậy của endpoint TSA, và việc xác minh chuỗi chứng chỉ áp dụng cho client đó, không phải cho interface này.
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 tham chiếu này không phải là một ý kiến pháp lý.
Chi tiết cơ chế nội bộ nằm trong tài liệu nội bộ của kho nguồn và nằm ngoài phạm vi của tài liệu hướng dẫn này.

Ranh giới xuất bản

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