Timestamp Authority (TSA)

★ Pro — Commercial License Required

Tích hợp TSA RFC 3161 yêu cầu package Pro.

TCPDF-Next Pro đi kèm client RFC 3161 Timestamp Authority (TsaClient) cấp production và helper DocumentTimestamp nhúng chữ ký /DocTimeStamp cho workflow PAdES B-LTA.

TsaClient

Sử dụng cơ bản

use Yeeefang\TcpdfNext\Pro\Tsa\TsaClient;

$tsa = new TsaClient(url: 'https://freetsa.org/tsr');

$token = $tsa->timestamp($pdfHash);

Với xác thực

Một số server TSA công ty yêu cầu thông tin đăng nhập:

$tsa = new TsaClient(
    url:      'https://tsa.corporate.example/rfc3161',
    username: 'api-user',
    password: 'api-secret',
);

Xây dựng RFC 3161 TimeStampReq

Client xây dựng cấu trúc ASN.1 TimeStampReq tuân thủ chuẩn cho mỗi yêu cầu:

1. MessageImprint -- Digest SHA-256 của dữ liệu cần timestamp.
2. Nonce -- Giá trị 64-bit ngẫu nhiên mật mã để ngăn tấn công replay.
3. CertReq -- Đặt true để TSA bao gồm chứng chỉ ký trong response.

// Hash phải là nhị phân thô (32 byte cho SHA-256)
$hash = hash('sha256', $documentBytes, binary: true);

$token = $tsa->timestamp($hash, algorithm: 'sha256');

Xác minh Nonce

Sau khi nhận TimeStampResp, client tự động:

1. Parse TSTInfo từ response.
2. Trích xuất nonce từ TSTInfo.
3. So sánh với nonce đã gửi trong yêu cầu.
4. Throw TsaNonceMismatchException nếu khác nhau.

try {
    $token = $tsa->timestamp($hash);
} catch (\Yeeefang\TcpdfNext\Pro\Tsa\TsaNonceMismatchException $e) {
    // Nonce không khớp -- có thể bị tấn công MITM hoặc replay
    log_security_event($e->getMessage());
}

Xác thực PKIStatus

Client xác thực trường PKIStatus trong mỗi response:

Code	Ý nghĩa	Hành vi Client
0	granted	Token được chấp nhận
1	grantedWithMods	Token được chấp nhận với cảnh báo ghi log
2	rejection	Throw TsaRejectedException
3	waiting	Không hỗ trợ; throw exception
4	revocationWarning	Token được chấp nhận với cảnh báo ghi log
5	revocationNotification	Throw TsaCertRevokedException

DNS Pinning (Bảo vệ SSRF)

Để ngăn Server-Side Request Forgery, bạn có thể pin hostname TSA đến địa chỉ IP cụ thể. Client dùng CURLOPT_RESOLVE để bỏ qua phân giải DNS hoàn toàn:

$tsa = new TsaClient(
    url: 'https://tsa.corporate.example/rfc3161',
);

// Pin hostname đến IP đã biết -- DNS không bao giờ được truy vấn
$tsa->pinDns('tsa.corporate.example', '203.0.113.42', port: 443);

Điều này quan trọng trong môi trường mà URL TSA đến từ input người dùng hoặc cấu hình bên ngoài và không được phân giải đến địa chỉ mạng nội bộ.

mTLS (Mutual TLS)

Server TSA công ty thường yêu cầu xác thực chứng chỉ client. Truyền chứng chỉ client và private key:

$tsa = new TsaClient(
    url: 'https://tsa.bank.example/timestamp',
);

$tsa->clientCertificate(
    certPath: '/etc/pki/tsa-client.pem',
    keyPath:  '/etc/pki/tsa-client.key',
    keyPassword: 'client-key-pass',
);

Handle cURL nội bộ được cấu hình với CURLOPT_SSLCERT, CURLOPT_SSLKEY và CURLOPT_SSLCERTPASSWD.

DocumentTimestamp (B-LTA)

DocumentTimestamp thêm chữ ký /DocTimeStamp vào PDF, là bước cuối cùng trong workflow PAdES B-LTA. Timestamp này bao phủ toàn bộ document bao gồm mọi chữ ký trước đó và DSS (Document Security Store).

use Yeeefang\TcpdfNext\Pro\Tsa\DocumentTimestamp;
use Yeeefang\TcpdfNext\Pro\Tsa\TsaClient;

$tsa = new TsaClient(url: 'https://freetsa.org/tsr');

$stamper = new DocumentTimestamp(
    tsaClient: $tsa,
    hashAlgorithm: 'sha256',
);

// Áp dụng document timestamp (incremental save)
$stamper->apply($document);

Tóm tắt Workflow B-LTA

1. Ký document           (PAdES B-B)
2. Thêm signature timestamp (PAdES B-T)
3. Nhúng DSS (OCSP + CRL) (PAdES B-LT)
4. Thêm /DocTimeStamp      (PAdES B-LTA)  <-- DocumentTimestamp

Server TSA phổ biến

Nhà cung cấp	URL	Xác thực	Ghi chú
FreeTSA	https://freetsa.org/tsr	Không	Miễn phí; phù hợp cho testing
Sectigo	https://timestamp.sectigo.com	Không	Cấp production; tier miễn phí
DigiCert	https://timestamp.digicert.com	Không	Đáng tin cậy rộng rãi
GlobalSign	https://timestamp.globalsign.com/tsa/r6advanced1	Không	SHA-256 mặc định
Tùy chỉnh / Doanh nghiệp	Tùy	Basic, mTLS, Bearer	Dùng pinDns() + clientCertificate()

TIP

Cho document PAdES B-LTA production, dùng nhà cung cấp TSA có root certificate trong Adobe Approved Trust List (AATL). Điều này đảm bảo timestamp được Adobe Acrobat nhận diện mà không cần cấu hình trust thủ công.