Bảo mật: mã hóa, chính sách mật mã và bề mặt chữ ký

Tổng quan nhanh

Mô-đun bảo mật Core áp dụng mã hóa tài liệu bằng 256-bit Advanced Encryption Standard (AES-256), định tuyến mọi lựa chọn thuật toán qua hợp đồng chính sách mật mã, đồng thời cung cấp các điểm tích hợp cho dịch vụ quản lý khóa do bản triển khai quản lý. Mức bảo vệ thực tế của tài liệu phụ thuộc vào cách xử lý khóa, độ mạnh mật khẩu, trình đọc tiêu thụ và môi trường triển khai. Trang này nêu rõ các ranh giới đó.

Cài đặt

composer require nextpdf/core:^3

Tổng quan khái niệm

Mô-đun bảo mật có ba bề mặt. Bề mặt mã hóa dùng điểm vào tài liệu setEncryption() để cấu hình trình xử lý bảo mật chuẩn AES-256. Cổng chính sách mật mã dùng CryptoPolicyInterface để quyết định bản triển khai cho phép những hàm băm, chữ ký, mật mã và độ mạnh khóa nào. Bề mặt ký được nhắc đến ở đây nhưng được ghi riêng; xem Ký.

Mã hóa dùng AES-256 như được định nghĩa trong ISO 32000-2:2020 §7.6. Đường mặc định là trình xử lý bảo mật chuẩn V=5 / R=6 với bộ lọc mật mã AESV3. Khóa tệp dài 32 byte (256 bit), phù hợp với Federal Information Processing Standards (FIPS) 197. Một đường tùy chọn bổ sung mã hóa xác thực ISO/TS 32003:2023 V=6 / R=7 AES-256 ở Galois/Counter Mode (AES-256-GCM). Trang chuyên sâu ghi lại cả hai đường: Mã hóa.

Cổng chính sách mật mã là một vị từ từ chối-hoặc-cho-phép. Core tham vấn CryptoPolicyInterface trước mọi bước ký, mã hóa hoặc băm. Nếu không đặt chính sách nào, Core cho phép mọi thuật toán. Giá trị mặc định mở này phù hợp cho phát triển, không phù hợp cho sản xuất. Một bản triển khai chịu quản lý phải đặt chính sách rõ ràng. Contracts / Security Policy ghi lại bề mặt hợp đồng.

Cờ quyền là nguồn tuyên bố quá mức phổ biến nhất, nên trang này nêu rõ giới hạn của chúng. Mặt nạ bit quyền được lưu trong mục /Perms đã mã hóa và trong giá trị /P. Một trình đọc tuân thủ được kỳ vọng sẽ tôn trọng các hạn chế đó. Các cờ này không được mật mã thực thi. Một bộ xử lý bỏ qua các bit vẫn có thể đọc, sao chép hoặc sửa đổi nội dung sau khi có khóa giải mã. Hãy nêu giới hạn này cho mọi bên dựa vào cờ quyền.

Tích hợp quản lý khóa và Public-Key Cryptography Standards #11 (PKCS#11) là các điểm hợp đồng. Core đi kèm một đường khóa cục bộ. Đối tượng giá trị KeyMaterial bọc một khóa 256-bit đã được kiểm tra độ dài và chống tiết lộ trong đầu ra chuỗi lẫn đầu ra gỡ lỗi. Đường lưu giữ khóa hardware security module (HSM)/PKCS#11 là một khả năng Enterprise được kiểm soát sau cùng các hợp đồng đó; trang này nêu tên điểm tích hợp nhưng không ghi lại phần triển khai Enterprise.

Bề mặt API

Kiểu	Loại	Thành viên chính	Độ ổn định	Từ phiên bản
`Document::setEncryption()`	phương thức (mối quan tâm `HasSecurity`)	`userPassword`, `ownerPassword`, `permissions`	ổn định	1.0.0
`Document::useAesGcm()`	phương thức (mối quan tâm `HasSecurity`)	`?bool $enabled` — tùy chọn ISO/TS 32003 V=6/R=7	ổn định	2.18.0
`Aes256Encryptor`	lớp	`encrypt()`, `decrypt()`, `buildEncryptionDictionary()`, `verifyUserPassword()`, `verifyOwnerPassword()`, `validatePerms()`	ổn định	1.0.0
`Aes256GcmEncryptor`	lớp	`encrypt()`, `decrypt()`, `encryptStream()`, `assertWithinSafetyBound()`, `invocationCount()`	ổn định	2.18.0
`KeyMaterial`	final readonly class	`generate()`, `exposeKey()`, `fingerprint()`	ổn định	2.18.0
`CryptoPolicyInterface`	interface	`isHashAlgorithmAllowed()`, `isSignatureAlgorithmAllowed()`, `isEncryptionAlgorithmAllowed()`, `isKeyStrengthAllowed()`, `getPreferredHashAlgorithm()`, `getName()`	ổn định	1.9.0
`Config::withCryptoPolicy()`	phương thức	`CryptoPolicyInterface $policy`	ổn định	1.9.0
`CryptoCapabilities`	final class	`hasAesGcm()`, `detectFipsMode()`, `assertFipsAvailableForProfile()`	ổn định	2.0.0

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

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('Encrypted Document — Restricted Permissions');

// Call setEncryption() BEFORE addPage().
// Permission bit 3 (value 4) = printing allowed; all other operations denied.
$doc->setEncryption(
    userPassword: 'demo',
    ownerPassword: 'admin',
    permissions: 4,
);

$doc->addPage();
$doc->setFont('helvetica', 'B', 20);
$doc->cell(0, 14, 'Encrypted PDF Document', newLine: true);

$doc->save(__DIR__ . '/output/22-protection.pdf');

Mật khẩu người dùng dùng để mở tài liệu. Mật khẩu chủ sở hữu cấp quyền truy cập đầy đủ. Cờ quyền chỉ ràng buộc trình đọc tuân thủ.

Mẫu mã — sản xuất

<?php

declare(strict_types=1);

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

use NextPDF\Contracts\CryptoPolicyInterface;
use NextPDF\Core\Document;
use Psr\Log\LoggerInterface;

final readonly class PolicyGatedEncryption
{
    public function __construct(
        private CryptoPolicyInterface $cryptoPolicy,
        private LoggerInterface $logger,
    ) {}

    /**
     * Encrypt only when the active policy permits AES-256-CBC.
     *
     * @param non-empty-string $userPassword  Opens the document.
     * @param non-empty-string $ownerPassword Grants full access.
     */
    public function protect(
        Document $doc,
        string $userPassword,
        string $ownerPassword,
        int $permissions,
    ): void {
        if (!$this->cryptoPolicy->isEncryptionAlgorithmAllowed('aes-256-cbc')) {
            $this->logger->error('Encryption refused by crypto policy', [
                'policy' => $this->cryptoPolicy->getName(),
            ]);

            throw new \RuntimeException('AES-256-CBC denied by the active crypto policy.');
        }

        $doc->setEncryption($userPassword, $ownerPassword, $permissions);

        $this->logger->info('Document encrypted', [
            'policy' => $this->cryptoPolicy->getName(),
            'algorithm' => 'aes-256-cbc',
        ]);
    }
}

Cổng tham vấn chính sách trước khi mã hóa, ghi tên chính sách vào dấu vết kiểm toán và ném một ngoại lệ cụ thể khi chính sách từ chối mật mã.

Trường hợp biên & lưu ý

Hãy gọi setEncryption() trước addPage(). Lời gọi sau đó không mã hóa hồi tố nội dung mà trình ghi đã phát ra.
Chế độ PDF/A và mã hóa loại trừ lẫn nhau. ISO 19005 cấm khóa trailer Encrypt trong mọi phiên bản PDF/A, vì vậy setEncryption() và useAesGcm() sẽ ném ngoại lệ khi một trình quản lý PDF/A đang hoạt động.
Bên trong setEncryption(), mật khẩu chủ sở hữu rỗng sẽ quay về dùng mật khẩu người dùng. Tài liệu chỉ có một mật khẩu chung sẽ cấp quyền truy cập cấp chủ sở hữu cho người giữ mật khẩu người dùng.
Khi không có chính sách nào được tiêm vào, CryptoPolicyInterface cho phép mọi thuật toán. Hãy coi giá trị mặc định mở là tiện ích cho phát triển, và đặt chính sách rõ ràng trong mọi bản triển khai chịu quản lý.
Cờ quyền chỉ mang tính tư vấn cho trình đọc. Đừng mô tả chúng như cơ chế kiểm soát truy cập mà một bộ xử lý thù địch không thể bỏ qua.

Hiệu năng

setEncryption() chạy một thủ tục dẫn xuất khóa lặp (Algorithm 2.B, bản sửa đổi 6) trong quá trình dựng tài liệu. Chi phí bị giới hạn và cố định cho mỗi tài liệu; nó không tăng theo số trang. Mã hóa theo từng đối tượng thực hiện một phép AES cho mỗi luồng hoặc chuỗi. Đường tùy chọn AES-256-GCM bổ sung 28 byte chi phí trên mỗi đối tượng (12 byte initialization vector (IV) cộng 16 byte tag) và truyền nội dung lớn theo từng khối 16 MiB. Cách này giữ lượt truyền dưới mức đỉnh 64 MB đã ghi. performance_budget gồm 1500 ms thời gian thực và 64 MB đỉnh chủ yếu do kết xuất tài liệu chi phối, không phải do mã hóa.

Lưu ý bảo mật

Mô hình mối đe dọa được nêu rõ ràng. Cổng chính sách mật mã giảm thiểu việc hạ cấp thuật toán bằng cách từ chối các mật mã yếu, hàm băm yếu và khóa ngắn trước mọi phép toán. Engine không âm thầm thay thế bằng một nguyên hàm yếu hơn khi nguyên hàm được yêu cầu vắng mặt; nó nâng một ngoại lệ để người vận hành có thể hành động. KeyMaterial giảm thiểu việc tiết lộ khóa qua ghi nhật ký: dạng chuỗi và dạng gỡ lỗi của nó che các byte và chỉ phơi bày một dấu vân tay không thể đảo ngược. Việc giả mạo bản mã chỉ được phát hiện trên đường tùy chọn AES-256-GCM, nơi tag xác thực được kiểm chứng và trường hợp không khớp sẽ nâng một ngoại lệ thay vì trả về bản rõ. Đường mặc định AES-256 Cipher Block Chaining (AES-256-CBC) chỉ bảo đảm tính bí mật và tự nó không phát hiện được sửa đổi. Trên đường GCM, việc tái sử dụng IV được giảm thiểu bằng bộ đếm đơn điệu cộng với một tập va chạm phòng thủ theo chiều sâu, nhất quán với yêu cầu IV duy nhất trong NIST SP 800-38D §8.

Các ranh giới cũng được nêu rõ tương tự. Mã hóa AES-256 được áp dụng như được định nghĩa trong ISO 32000-2:2020 §7.6. Khả năng bảo vệ thực tế phụ thuộc vào độ mạnh mật khẩu, quản lý khóa, môi trường triển khai và trình đọc tiêu thụ. Trình đọc tuân thủ tôn trọng cờ quyền, nhưng mật mã không thực thi chúng. Phép thăm dò chế độ FIPS báo cáo xem bản dựng OpenSSL của máy chủ đã tải nhà cung cấp FIPS hay chưa. Thư viện vận hành ở chế độ tương thích FIPS khi máy chủ cung cấp mô-đun đã được kiểm định; nó không chứng nhận bất kỳ mô-đun nào. NIST SP 800-57 Part 1 §4 đặt thời hạn khóa và chu kỳ mật mã trong phạm vi trách nhiệm của bản triển khai. Core cung cấp các điều khiển, còn bản triển khai đặt chính sách xoay vòng.

Lưu trú dữ liệu & giảm thiểu PII

Bề mặt mã hóa không truyền các byte tài liệu, bao gồm mọi thông tin định danh cá nhân (PII) mà chúng chứa, ra ngoài máy chủ. Việc dẫn xuất khóa, mã hóa và giải mã chạy trong tiến trình. Đường tùy chọn GCM lập khóa cho một tập va chạm IV trong bộ nhớ bằng dấu vân tay khóa không thể đảo ngược, không phải bằng các byte khóa. Mô-đun bảo mật không ghi bất kỳ giá trị mật khẩu hay khóa nào ra đĩa. Bản triển khai định tuyến khóa qua dịch vụ quản lý khóa bên ngoài chịu trách nhiệm về việc lưu trú của dịch vụ đó.

Telemetry an toàn & làm sạch nhật ký

KeyMaterial::__toString() và __debugInfo() trả về một chỗ giữ chỗ đã che, vì vậy việc vô tình ghi nhật ký một đối tượng khóa sẽ cho ra dấu vân tay, không phải các byte khóa. Các mật khẩu truyền cho setEncryption() mang thuộc tính #[\SensitiveParameter], vốn che chúng khỏi dấu vết ngăn xếp. Đối với kiểm toán, hãy dùng tên chính sách từ CryptoPolicyInterface::getName() và dấu vân tay khóa 8 ký tự làm định danh phép toán mật mã. Hãy ghi nhật ký các giá trị đó, không bao giờ ghi khóa hay mật khẩu.

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

Mối đe dọa	Giảm thiểu trong Core	Ranh giới còn lại
Hạ cấp thuật toán / thay thế bằng mật mã yếu	Cổng chính sách mật mã; không suy giảm âm thầm (nâng `UnsupportedAlgorithmException`)	Chỉ có hiệu lực khi một chính sách được tiêm vào
Tiết lộ khóa qua nhật ký	`KeyMaterial` che; `#[\SensitiveParameter]` trên các mật khẩu	Bên gọi truyền `exposeKey()` cho trình ghi nhật ký sẽ vô hiệu hóa biện pháp này
Giả mạo bản mã	Kiểm chứng tag GCM trên đường tùy chọn	Đường CBC mặc định chỉ bảo đảm tính bí mật
Tái sử dụng IV (GCM)	Bộ đếm đơn điệu cộng với tập va chạm; tràn số thì từ chối	—
Bỏ qua cờ quyền	Không có; các cờ chỉ mang tính tư vấn	Một trình đọc không tuân thủ sẽ bỏ qua các cờ
Tấn công vét cạn trên một mật khẩu yếu	SASLprep cộng với dẫn xuất khóa lặp làm tăng chi phí	Một mật khẩu yếu vẫn là rủi ro chủ đạo

Hành vi chế độ FIPS

Core không phải là mô-đun mật mã đã được kiểm định FIPS và không được chứng nhận FIPS. CryptoCapabilities::detectFipsMode() là phép thăm dò thời gian chạy nỗ lực tối đa: nó đọc ghi đè của người vận hành, rồi danh sách nhà cung cấp OpenSSL, rồi lời gọi chế độ FIPS cũ, sau đó báo cáo trạng thái hoạt động, vắng mặt hoặc không xác định. assertFipsAvailableForProfile() thất bại đóng kín khi hồ sơ FIPS được chọn trên máy chủ không thể chứng minh có nhà cung cấp FIPS. Thư viện vận hành ở chế độ tương thích FIPS khi được cấu hình dựa trên bản dựng OpenSSL của máy chủ đã tải nhà cung cấp đã được kiểm định FIPS. Một tư thế FIPS đã được kiểm định và chứng nhận là mối quan tâm của Enterprise; xem tài liệu Enterprise.

Tuân thủ

Tuyên bố	Tiêu chuẩn	Điều khoản
Đường GCM giữ mỗi IV là duy nhất cho một lần gọi, nhất quán với yêu cầu về tính duy nhất của tiêu chuẩn.	NIST SP 800-38D	§8.2.1
Core cung cấp các điều khiển cho thời hạn khóa và chu kỳ mật mã; bản triển khai sở hữu chính sách.	NIST SP 800-57 Part 1 Rev. 5	§4
Khóa tệp AES dài 256 bit, khớp với độ dài khóa của tiêu chuẩn.	FIPS 197	§4.2.1
Việc tạo khóa thường trú trên token là điểm tích hợp cho một kho khóa bên ngoài.	OASIS PKCS#11 v3.1	C_GenerateKey

ISO 32000-2:2020 §7.6 là cơ sở quy phạm cho trình xử lý bảo mật chuẩn. Văn bản của tiêu chuẩn này bị hạn chế bởi giấy phép và được diễn giải lại ở đây, không bao giờ trích dẫn nguyên văn; trang này dẫn điều khoản theo số. Mọi điểm ở trên đều được diễn giải lại từ tiêu chuẩn được dẫn.

Bối cảnh thương mại

Core định nghĩa và đóng băng hợp đồng chính sách mật mã, cung cấp đường mã hóa AES-256 và cung cấp bề mặt khóa cục bộ. Phiên bản Enterprise cung cấp đường lưu giữ khóa HSM/PKCS#11 và hồ sơ chính sách mật mã chế độ FIPS sau cùng một CryptoPolicyInterface. Bề mặt hợp đồng giống nhau giữa các phiên bản; bản triển khai tiêm vào một phần triển khai chính sách và một backend lưu giữ khóa khác.

Xem thêm

Security / Encryption — tài liệu tham chiếu chuyên sâu về AES-256 và AES-256-GCM.
Contracts / Security Policy — các hợp đồng chính sách mật mã và chính sách tài nguyên.
Security / Signing — PDF Advanced Electronic Signatures (PAdES), Cryptographic Message Syntax (CMS), và dấu thời gian.
Audit — ghi nhật ký kiểm toán tên chính sách và phép toán.
Conformance — tương tác PDF/A với mã hóa.