Bảo mật và vận hành compat-legacy

Tổng quan nhanh

Bộ adapter sử dụng mô hình bảo mật của engine NextPDF và bổ sung một vài biện pháp tăng cường bảo mật có chủ đích so với TCPDF 6.2.13 legacy. Trang này nêu chính xác những gì có sẵn và những gì không, không nói quá. Hãy đọc kỹ phần ký; phạm vi của phần đó được chủ ý giới hạn hẹp.

Các hành vi legacy đã được tăng cường bảo mật

Bộ adapter thay đổi ba hành vi vốn có của TCPDF 6.2.13 vì lý do an toàn. Các hành vi này không thể cấu hình trở lại dạng không an toàn:

Vấn đề	TCPDF 6.2.13 legacy	Adapter
Xử lý lỗi	Error() gọi die() và kết thúc tiến trình	Error() ném RuntimeException; bên gọi có thể quan sát và bắt lỗi này, tiến trình không bị kết thúc âm thầm.
Thực thi HTML	Một lối thoát có thể chạy PHP từ markup	Hằng số K_TCPDF_CALLS_IN_HTML được cố định ở giá trị false; markup không thể kích hoạt thực thi PHP.
Xuất trực tiếp	Output() xuất ra bộ đệm đầu ra đang hoạt động	Đầu ra đi qua một cầu nối điểm đến an toàn và không làm nhiễm bộ đệm đầu ra do bên gọi kiểm soát.

Thay đổi về xử lý lỗi đảm bảo bạn có thể quan sát lỗi thay vì mất tiến trình vì bị kết thúc. Open Worldwide Application Security Project (OWASP) Application Security Verification Standard (ASVS) 5.0 §16.5.3 nêu rằng ứng dụng nên xử lý lỗi một cách nhẹ nhàng và an toàn, đồng thời ngăn các tình huống fail-open. Thay đổi ném-thay-vì-die áp dụng nguyên tắc đó. Việc tăng cường bảo mật cho HTML loại bỏ một điểm có thể bị lợi dụng để thực thi mã. Hãy xem mã legacy phụ thuộc vào hành vi cũ là lỗi cần sửa trong quá trình /integrations/tcpdf-compat/migration/. Bản tóm tắt điều khoản đã ghim nằm trong phần front-matter citations của trang.

Mã hóa

Bộ adapter cung cấp phương thức SetProtection() của TCPDF và ủy quyền cho standard security handler của engine NextPDF.

• Standard handler dùng AES-256. Tham số $mode legacy được chấp nhận để tương thích với chữ ký phương thức và bị bỏ qua; không có cách nào chọn thuật toán mã hóa yếu hơn qua phương thức này. Khi strict mode được bật, một giá trị $mode khác mặc định sẽ ném lỗi để buộc quá trình migration phải ghi nhận điều đó (được kiểm chứng trong tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php).
• Nếu không cung cấp owner password, bộ adapter sẽ tạo một owner password ngẫu nhiên đủ mạnh về mặt mật mã thay vì tái sử dụng user password. Điều này ngăn những người có quyền truy cập cấp user giành quyền kiểm soát tài liệu cấp owner.
• Mã hóa dựa trên chứng chỉ (public-key) không được thực hiện qua SetProtection(); bộ adapter bỏ qua tham số $pubkeys của phương thức đó. Hãy dùng điểm truy cập mã hóa public-key hiện đại được cung cấp trên bộ adapter (setPublicKeyEncryption()), phương thức này ủy quyền cho engine.

Hành vi mã hóa phản ánh standard security handler được mô tả trong ISO 32000-2 §7. Điều khoản đó định nghĩa các mục của encryption dictionary và AES-256 standard handler mà engine sử dụng. Tài liệu này không khẳng định đầu ra là “an toàn theo mặc định” hay “chống giả mạo”. Tài liệu chỉ nêu thuật toán mã hóa được dùng và hành vi owner-password do mã nguồn triển khai. Bản tóm tắt điều khoản đã ghim nằm trong phần front-matter citations của trang.

examples/security-encryption.php

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF();
$pdf->AddPage();
$pdf->SetFont('helvetica', '', 12);
$pdf->Cell(0, 10, 'Encrypted document');

// User password set; owner password auto-generated (strong, random).
$pdf->SetProtection([], 'user-secret');

$pdf->Output(__DIR__ . '/encrypted.pdf', 'F');

Chữ ký số — tuyên bố phạm vi

Hãy đọc phần này theo đúng nghĩa đen. Nó cố ý thận trọng.

• Các phương thức legacy setSignature() và addEmptySignatureAppearance() của TCPDF chưa được triển khai trong bộ adapter trên engine core. Ở chế độ mặc định, chúng không làm gì cả. Ở strict mode, chúng ném TcpdfNotImplementedException.
• Ký số không phải là một khả năng của bản phân phối core thông qua bộ adapter này. Hỗ trợ chữ ký baseline yêu cầu một phiên bản NextPDF thương mại.
• Nếu có phiên bản thương mại, bộ adapter sẽ cung cấp một điểm truy cập chữ ký hiện đại (setSignatureV2()) ủy quyền cho engine. Profile mặc định của điểm truy cập này là profile baseline (B-B).
• Tài liệu này không khẳng định rằng bất kỳ phiên bản nào tạo ra các profile chữ ký có dấu thời gian, có xác thực dài hạn, hoặc lưu trữ dài hạn thông qua bộ adapter này. Cụ thể, tài liệu không khẳng định hành vi B-T, B-LT, hay B-LTA. Đặc tả baseline của PDF Advanced Electronic Signatures (PAdES) §6.1 định nghĩa bốn cấp baseline riêng biệt: B-B, B-T, B-LT, và B-LTA. Mỗi cấp có các yêu cầu riêng. B-B là cấp baseline, còn các cấp cao hơn (dấu thời gian, dài hạn, lưu trữ) là những profile riêng biệt và đòi hỏi nhiều hơn. Chỉ baseline B-B nằm trong phạm vi tài liệu của lớp tương thích này. Các cấp cao hơn rõ ràng nằm ngoài phạm vi và không được khẳng định cho bất kỳ phiên bản nào ở đây. Bản tóm tắt điều khoản đã ghim nằm trong phần front-matter citations của trang.
• Tài liệu này không đưa ra bất kỳ khẳng định nào về chữ ký “đã chứng nhận”, “được bảo đảm”, “có giá trị pháp lý”, hay “đạt chuẩn eIDAS” ở bất cứ đâu. Tính đúng đắn của việc ký, chính sách trust-anchor, và giá trị pháp lý thuộc trách nhiệm của phiên bản ký và Public Key Infrastructure (PKI) của bên gọi, không thuộc trách nhiệm của lớp tương thích này.

Nếu quá trình migration của bạn cần ký, hãy xem đó là một luồng công việc riêng: áp dụng application programming interface (API) chữ ký hiện đại trên một phiên bản thương mại và kiểm chứng chữ ký thu được bằng một trình kiểm tra độc lập. Đừng dựa vào lệnh gọi setSignature() của TCPDF; trong bộ adapter này, lệnh gọi đó không làm gì cả.

Phương thức legacy setTimeStamp() được chấp nhận để tương thích với chữ ký phương thức và phát ra một thông báo; phương thức này không tạo ra chữ ký có dấu thời gian thông qua bộ adapter này.

PDF/A và tính tuân thủ

Cờ pdfa của constructor được chấp nhận để tương thích với chữ ký phương thức. Tính tuân thủ lưu trữ PDF/A yêu cầu một phiên bản NextPDF thương mại. Bộ adapter cung cấp enablePdfA(), phương thức này ủy quyền cho engine, và engine trả về một lỗi cấu hình có thể xử lý được khi thiếu phiên bản cần thiết. Bộ adapter không âm thầm tạo ra một tệp không tuân thủ trong khi vẫn tuyên bố đó là PDF/A.

Đầu ra luôn là PDF 2.0 (ISO 32000-2). ISO 32000-2 §7.5.2 quy định rằng một conforming writer xác định phiên bản tài liệu là 2.0 và không hạ xuống phiên bản cũ hơn khi lưu. Do đó, setPDFVersion() không thể hạ xuống một phiên bản cũ hơn (xem /integrations/tcpdf-compat/method-coverage/ §4). Bản tóm tắt điều khoản đã ghim nằm trong phần front-matter citations của trang.

Hướng dẫn vận hành

• Không có việc kết thúc tiến trình. Vì Error() ném lỗi thay vì die(), hãy bọc các điểm vào render trong try/catch và ánh xạ lỗi vào hợp đồng lỗi của ứng dụng. Đừng cho rằng một lần render thất bại sẽ kết thúc request.
• An toàn cho bộ đệm đầu ra. Output() với S trả về các byte; với F ghi một tệp; với E trả về một thân Multipurpose Internet Mail Extensions (MIME) ở dạng base64; với I/D, dữ liệu đi qua đường xuất của engine. Hãy ưu tiên S hoặc F trong các worker và trình xử lý Hypertext Transfer Protocol (HTTP) để bạn tự kiểm soát phản hồi; xem /integrations/tcpdf-compat/production-usage/.
• Strict mode không phải là một thiết lập dùng cho production. Hãy giữ nó cho một tác vụ continuous integration (CI) hoặc audit. Một ngoại lệ trên đường render production còn tệ hơn một tham số bị suy giảm âm thầm.
• Vệ sinh hằng số. Hãy định nghĩa các hằng số PDF_* / K_* trước lần khởi tạo adapter đầu tiên. Hai cờ đã được tăng cường bảo mật (K_TCPDF_CALLS_IN_HTML, K_TCPDF_THROW_EXCEPTION_ERROR) không thể nới lỏng; đừng cố nới chúng.
• Owner password ngẫu nhiên. Nếu bạn dựa vào một owner password mang tính tất định, hãy đặt nó một cách rõ ràng. Nếu không, một password ngẫu nhiên đủ mạnh sẽ được tạo cho mỗi tài liệu và không thể khôi phục.

Ghi chú về mô hình mối đe dọa

• Đối với các phương thức image, bộ adapter từ chối một đường dẫn stream-wrapper trước khi đọc bất kỳ tệp nào từ hệ thống tệp. Việc phát hiện kiểu ảnh (TcpdfImages::getImageFileType) coi bất kỳ đường dẫn scheme:// nào, bao gồm phar://, php://, và các PHP stream wrapper khác, là một wrapper và bỏ qua bước thăm dò file_get_contents / getimagesize, lùi về suy luận chỉ dựa trên phần mở rộng. Điều này đóng một vector deserialization metadata của phar trên mục tiêu backport PHP 7.4; chính engine từ chối nhúng đường dẫn wrapper.
• Bộ adapter không bổ sung bước kiểm tra hợp lệ hay làm sạch đường dẫn cho các đường dẫn tệp được truyền vào các phương thức image hoặc output ngoài những gì engine thực hiện. Hãy coi các đường dẫn và URL do bên gọi cung cấp là không đáng tin tại ranh giới ứng dụng của bạn.
• HTML được truyền vào các phương thức HTML sẽ do engine kết xuất, không phải bởi một trình phân tích HTML của TCPDF. Điểm legacy có thể bị lợi dụng để thực thi PHP đã bị đóng, nhưng bạn vẫn nên coi HTML do bên gọi cung cấp là đầu vào không đáng tin.
• Mã hóa bảo vệ tính bí mật của tài liệu khi lưu trữ dưới standard handler. Đây không phải là thứ thay thế cho bảo mật đường truyền hay kiểm soát truy cập trong ứng dụng của bạn.

Xem thêm

• /integrations/tcpdf-compat/method-coverage/ — hành vi chính xác của SetProtection(), setSignature()
• /integrations/tcpdf-compat/configuration/ — hai cờ đã được tăng cường bảo mật, không thể cấu hình được
• /integrations/tcpdf-compat/production-usage/ — worker, bộ đệm, xử lý lỗi
• docs/TCPDF_COVERAGE.md — ma trận coverage có thẩm quyền
• Tệp NOTICE của package — tuyên bố triển khai độc lập