ความปลอดภัย: การเข้ารหัสลับ นโยบายการเข้ารหัสลับ และส่วนติดต่อการลงนาม

ภาพรวมโดยย่อ

โมดูลความปลอดภัยของ Core ใช้การเข้ารหัสลับเอกสารแบบ 256-bit Advanced Encryption Standard (AES-256) ส่งตัวเลือกอัลกอริทึมทั้งหมดผ่านสัญญานโยบายการเข้ารหัสลับ และเปิดจุดเชื่อมต่อสำหรับบริการจัดการคีย์ที่จัดการในระดับการนำไปใช้งานจริง การปกป้องเอกสารให้ได้ผลจริงขึ้นอยู่กับการจัดการคีย์ ความแข็งแรงของรหัสผ่าน โปรแกรมอ่านที่ใช้ และสภาพแวดล้อมของการนำไปใช้งาน หน้านี้ระบุขอบเขตเหล่านั้นอย่างตรงไปตรงมา

การติดตั้ง

composer require nextpdf/core:^3

ภาพรวมเชิงแนวคิด

โมดูลความปลอดภัยมีส่วนติดต่อหลักสามส่วน ส่วนติดต่อการเข้ารหัสลับใช้จุดเข้าใช้งานเอกสาร setEncryption() เพื่อกำหนดค่าตัวจัดการความปลอดภัยมาตรฐาน AES-256 เกตนโยบายการเข้ารหัสลับใช้ CryptoPolicyInterface เพื่อตัดสินว่าการนำไปใช้งานอนุญาตแฮช ลายเซ็น ไซเฟอร์ และความแข็งแรงของคีย์แบบใด ส่วนติดต่อการลงนามมีการอ้างถึงในหน้านี้ แต่จัดทำเอกสารไว้แยกต่างหาก ดู การลงนาม

การเข้ารหัสลับใช้ AES-256 ตามที่นิยามไว้ใน ISO 32000-2:2020 §7.6 เส้นทางเริ่มต้นคือตัวจัดการความปลอดภัยมาตรฐาน V=5 / R=6 พร้อมตัวกรองการเข้ารหัสลับ AESV3 คีย์ของไฟล์มีขนาด 32 ไบต์ (256 บิต) ซึ่งตรงกับ Federal Information Processing Standards (FIPS) 197 เส้นทางแบบเลือกใช้เพิ่มการเข้ารหัสลับแบบรับรองความถูกต้อง ISO/TS 32003:2023 V=6 / R=7 AES-256 in Galois/Counter Mode (AES-256-GCM) หน้าเชิงลึกจัดทำเอกสารของทั้งสองเส้นทางไว้ที่ การเข้ารหัสลับ

เกตนโยบายการเข้ารหัสลับเป็นเพรดิเคตแบบปฏิเสธหรืออนุญาต Core จะปรึกษา CryptoPolicyInterface ก่อนขั้นตอนการลงนาม การเข้ารหัสลับ หรือการแฮชใดๆ หากไม่ได้ตั้งค่านโยบายไว้ Core จะอนุญาตทุกอัลกอริทึม ค่าเริ่มต้นแบบเปิดนี้เหมาะกับการพัฒนา ไม่ใช่การใช้งานจริง การนำไปใช้งานที่อยู่ภายใต้การกำกับดูแลต้องตั้งค่านโยบายอย่างชัดเจน Contracts / Security Policy จัดทำเอกสารส่วนติดต่อของสัญญานี้

แฟล็กสิทธิ์เป็นแหล่งของการกล่าวอ้างเกินจริงที่พบบ่อยที่สุด หน้านี้จึงระบุไว้อย่างชัดเจน บิตมาสก์ของสิทธิ์ถูกเก็บไว้ในรายการ /Perms ที่เข้ารหัสลับและในค่า /P โปรแกรมอ่านที่สอดคล้องตามมาตรฐานคาดว่าจะเคารพข้อจำกัดเหล่านั้น แฟล็กเหล่านี้ ไม่ ได้ถูกบังคับใช้ด้วยการเข้ารหัสลับ โปรเซสเซอร์ที่ละเลยบิตเหล่านั้นยังสามารถอ่าน คัดลอก หรือแก้ไขเนื้อหาได้หลังจากมีคีย์ถอดรหัสแล้ว ควรแจ้งข้อจำกัดนี้แก่ทุกฝ่ายที่พึ่งพาแฟล็กสิทธิ์

การจัดการคีย์และการผสานรวมกับ Public-Key Cryptography Standards #11 (PKCS#11) เป็นจุดของสัญญา Core มาพร้อมเส้นทางคีย์ในเครื่อง ออบเจกต์ค่า KeyMaterial ห่อหุ้มคีย์ 256 บิตที่ตรวจสอบความยาวแล้ว และป้องกันการเปิดเผยผ่านผลลัพธ์แบบสตริงและผลลัพธ์สำหรับดีบัก เส้นทางการเก็บรักษาคีย์ hardware security module (HSM)/PKCS#11 เป็นความสามารถระดับ Enterprise ที่อยู่หลังสัญญาเดียวกัน หน้านี้ระบุชื่อจุดเชื่อมต่อ แต่ไม่ได้จัดทำเอกสารการนำไปใช้งานระดับ Enterprise

พื้นผิว API

ประเภท	ชนิด	สมาชิกหลัก	ความเสถียร	ตั้งแต่
`Document::setEncryption()`	เมธอด (concern `HasSecurity`)	`userPassword`, `ownerPassword`, `permissions`	stable	1.0.0
`Document::useAesGcm()`	เมธอด (concern `HasSecurity`)	`?bool $enabled` — แบบเลือกใช้ ISO/TS 32003 V=6/R=7	stable	2.18.0
`Aes256Encryptor`	class	`encrypt()`, `decrypt()`, `buildEncryptionDictionary()`, `verifyUserPassword()`, `verifyOwnerPassword()`, `validatePerms()`	stable	1.0.0
`Aes256GcmEncryptor`	class	`encrypt()`, `decrypt()`, `encryptStream()`, `assertWithinSafetyBound()`, `invocationCount()`	stable	2.18.0
`KeyMaterial`	final readonly class	`generate()`, `exposeKey()`, `fingerprint()`	stable	2.18.0
`CryptoPolicyInterface`	interface	`isHashAlgorithmAllowed()`, `isSignatureAlgorithmAllowed()`, `isEncryptionAlgorithmAllowed()`, `isKeyStrengthAllowed()`, `getPreferredHashAlgorithm()`, `getName()`	stable	1.9.0
`Config::withCryptoPolicy()`	เมธอด	`CryptoPolicyInterface $policy`	stable	1.9.0
`CryptoCapabilities`	final class	`hasAesGcm()`, `detectFipsMode()`, `assertFipsAvailableForProfile()`	stable	2.0.0

ตัวอย่างโค้ด — เริ่มต้นอย่างรวดเร็ว

<?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');

รหัสผ่านผู้ใช้ใช้สำหรับเปิดเอกสาร รหัสผ่านเจ้าของให้สิทธิ์เข้าถึงเต็มรูปแบบ แฟล็กสิทธิ์จำกัดได้เฉพาะโปรแกรมอ่านที่สอดคล้องตามมาตรฐานเท่านั้น

ตัวอย่างโค้ด — สำหรับการใช้งานจริง

<?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',
        ]);
    }
}

เกตจะปรึกษานโยบายก่อนการเข้ารหัสลับ บันทึกชื่อนโยบายไว้สำหรับเส้นทางการตรวจสอบ และโยนข้อยกเว้นเฉพาะเมื่อนโยบายปฏิเสธไซเฟอร์

กรณีขอบและข้อควรระวัง

เรียก setEncryption() ก่อน addPage() การเรียกภายหลังจะไม่เข้ารหัสลับเนื้อหาย้อนหลังหลังจากตัวเขียนส่งออกไปแล้ว
โหมด PDF/A และการเข้ารหัสลับใช้ร่วมกันไม่ได้ ISO 19005 ห้ามใช้คีย์ trailer Encrypt ในทุกรูปแบบของ PDF/A ดังนั้น setEncryption() และ useAesGcm() จะโยนข้อยกเว้นเมื่อตัวจัดการ PDF/A ทำงานอยู่
ภายใน setEncryption() รหัสผ่านเจ้าของที่ว่างเปล่าจะถอยกลับไปใช้รหัสผ่านผู้ใช้ เอกสารที่ใช้รหัสผ่านร่วมกันเพียงตัวเดียวจะให้ผู้ถือรหัสผ่านผู้ใช้มีสิทธิ์เข้าถึงระดับเจ้าของ
เมื่อไม่ได้ฉีดนโยบายเข้าไป CryptoPolicyInterface จะอนุญาตทุกอัลกอริทึม ให้ถือว่าค่าเริ่มต้นแบบเปิดเป็นความสะดวกสำหรับการพัฒนา และตั้งค่านโยบายอย่างชัดเจนในการนำไปใช้งานที่อยู่ภายใต้การกำกับดูแล
แฟล็กสิทธิ์เป็นเพียงคำแนะนำต่อโปรแกรมอ่าน อย่าอธิบายว่าแฟล็กเหล่านี้เป็นการควบคุมการเข้าถึงที่โปรเซสเซอร์ซึ่งมุ่งร้ายไม่สามารถข้ามผ่านได้

ประสิทธิภาพ

setEncryption() รันรูทีนการสืบทอดคีย์แบบวนซ้ำ (Algorithm 2.B, revision 6) ระหว่างการสร้างเอกสาร ต้นทุนมีขอบเขตจำกัดและคงที่ต่อเอกสาร โดยไม่เพิ่มตามจำนวนหน้า การเข้ารหัสลับแบบต่อออบเจกต์ดำเนินการ AES หนึ่งครั้งต่อสตรีมหรือสตริง เส้นทาง AES-256-GCM แบบเลือกใช้เพิ่มโอเวอร์เฮด 28 ไบต์ต่อออบเจกต์ (initialization vector (IV) 12 ไบต์ บวกแท็ก 16 ไบต์) และสตรีมเนื้อหาขนาดใหญ่เป็นก้อนละ 16 MiB วิธีนี้ทำให้การประมวลผลแบบสตรีมอยู่ต่ำกว่าค่าพีค 64 MB ที่ระบุไว้ performance_budget ที่ 1500 ms wall และพีค 64 MB ถูกใช้ไปกับการเรนเดอร์เอกสารเป็นหลัก ไม่ใช่การเข้ารหัสลับ

หมายเหตุด้านความปลอดภัย

แบบจำลองภัยคุกคามถูกระบุไว้อย่างชัดเจน เกตนโยบายการเข้ารหัสลับบรรเทาการลดระดับอัลกอริทึมด้วยการปฏิเสธไซเฟอร์ที่อ่อนแอ แฮชที่อ่อนแอ และคีย์ที่สั้นก่อนการดำเนินการใดๆ เอนจินจะไม่แทนที่ไพรมิทีฟด้วยตัวที่อ่อนแอกว่าอย่างเงียบๆ เมื่อไม่มีตัวที่ร้องขอ แต่จะโยนข้อยกเว้นเพื่อให้ผู้ปฏิบัติงานดำเนินการได้ KeyMaterial บรรเทาการเปิดเผยคีย์ผ่านการบันทึกล็อก โดยรูปแบบแบบสตริงและรูปแบบสำหรับดีบักจะปิดบังไบต์และเปิดเผยเฉพาะลายนิ้วมือที่ย้อนกลับไม่ได้เท่านั้น การปลอมแปลงไซเฟอร์เท็กซ์จะตรวจพบได้เฉพาะบนเส้นทาง AES-256-GCM แบบเลือกใช้เท่านั้น ซึ่งมีการตรวจสอบแท็กการรับรองความถูกต้อง และเมื่อค่าไม่ตรงกันจะโยนข้อยกเว้นแทนการคืนค่าเพลนเท็กซ์ เส้นทาง AES-256 Cipher Block Chaining (AES-256-CBC) เริ่มต้นให้เฉพาะการรักษาความลับเท่านั้น และไม่สามารถตรวจจับการดัดแปลงได้ด้วยตัวเอง บนเส้นทาง GCM การใช้ IV ซ้ำถูกบรรเทาด้วยตัวนับแบบเพิ่มขึ้นทางเดียวพร้อมชุดตรวจจับการชนในฐานะการป้องกันเชิงลึก ซึ่งสอดคล้องกับข้อกำหนด IV ที่ไม่ซ้ำกันใน NIST SP 800-38D §8

ขอบเขตก็ถูกระบุไว้อย่างชัดเจนเช่นกัน การเข้ารหัสลับ AES-256 ถูกนำมาใช้ตามที่นิยามไว้ใน ISO 32000-2:2020 §7.6 การปกป้องให้ได้ผลจริงขึ้นอยู่กับความแข็งแรงของรหัสผ่าน การจัดการคีย์ สภาพแวดล้อมของการนำไปใช้งาน และโปรแกรมอ่านที่ใช้ โปรแกรมอ่านที่สอดคล้องตามมาตรฐานเคารพแฟล็กสิทธิ์ แต่การเข้ารหัสลับไม่ได้บังคับใช้แฟล็กเหล่านั้น การตรวจสอบโหมด FIPS รายงานว่าบิลด์ OpenSSL ของโฮสต์ได้โหลดผู้ให้บริการ FIPS หรือไม่ ไลบรารีทำงานในโหมดที่เข้ากันได้กับ FIPS เมื่อโฮสต์จัดหาโมดูลที่ผ่านการตรวจสอบรับรอง โดยไม่ได้รับรองโมดูลใดๆ เอง NIST SP 800-57 Part 1 §4 กำหนดกรอบให้อายุของคีย์และคริปโตพีเรียดเป็นความรับผิดชอบของการนำไปใช้งาน Core เปิดเผยตัวควบคุม และการนำไปใช้งานเป็นผู้ตั้งค่านโยบายการหมุนเวียน

ถิ่นที่อยู่ของข้อมูลและการบรรเทา PII

ส่วนติดต่อการเข้ารหัสลับไม่ส่งไบต์ของเอกสาร รวมถึงข้อมูลที่สามารถระบุตัวบุคคลได้ (PII) ใดๆ ที่อยู่ในเอกสาร ออกไปนอกโฮสต์ การสืบทอดคีย์ การเข้ารหัสลับ และการถอดรหัสทำงานภายในกระบวนการ เส้นทาง GCM แบบเลือกใช้กำหนดคีย์ให้ชุดตรวจจับการชนของ IV ในหน่วยความจำด้วยลายนิ้วมือคีย์ที่ย้อนกลับไม่ได้ ไม่ใช่ด้วยไบต์ของคีย์ โมดูลความปลอดภัยไม่เขียนค่ารหัสผ่านหรือคีย์ลงดิสก์ การนำไปใช้งานที่ส่งคีย์ผ่านบริการจัดการคีย์ภายนอกเป็นผู้รับผิดชอบถิ่นที่อยู่ของข้อมูลของบริการนั้น

เทเลเมตรีที่ปลอดภัยและการล้างข้อมูลออกจากล็อก

KeyMaterial::__toString() และ __debugInfo() คืนค่าตัวแทนที่ถูกปิดบัง ดังนั้นการบันทึกล็อกออบเจกต์คีย์โดยไม่ตั้งใจจะแสดงลายนิ้วมือ ไม่ใช่ไบต์ของคีย์ รหัสผ่านที่ส่งให้ setEncryption() มีแอตทริบิวต์ #[\SensitiveParameter] ซึ่งปิดบังรหัสผ่านเหล่านั้นจาก stack trace สำหรับการตรวจสอบ ให้ใช้ชื่อนโยบายจาก CryptoPolicyInterface::getName() และลายนิ้วมือคีย์ความยาว 8 อักขระเป็นตัวระบุการดำเนินการเข้ารหัสลับ บันทึกค่าเหล่านั้น อย่าบันทึกคีย์หรือรหัสผ่านเป็นอันขาด

แบบจำลองภัยคุกคาม

ภัยคุกคาม	การบรรเทาใน Core	ขอบเขตที่เหลืออยู่
การลดระดับอัลกอริทึม / การแทนที่ด้วยไซเฟอร์ที่อ่อนแอ	เกตนโยบายการเข้ารหัสลับ ไม่มีการลดระดับอย่างเงียบๆ (โยน `UnsupportedAlgorithmException`)	ได้ผลเฉพาะเมื่อมีการฉีดนโยบายเข้าไปเท่านั้น
การเปิดเผยคีย์ผ่านล็อก	`KeyMaterial` การปิดบัง; `#[\SensitiveParameter]` บนรหัสผ่าน	ผู้เรียกที่ส่ง `exposeKey()` ไปยังตัวบันทึกล็อกจะทำให้การป้องกันนี้ใช้ไม่ได้ผล
การปลอมแปลงไซเฟอร์เท็กซ์	การตรวจสอบแท็ก GCM บนเส้นทางแบบเลือกใช้	เส้นทาง CBC เริ่มต้นให้เฉพาะการรักษาความลับเท่านั้น
การใช้ IV ซ้ำ (GCM)	ตัวนับแบบเพิ่มขึ้นทางเดียวพร้อมชุดตรวจจับการชน เมื่อล้นค่าจะปฏิเสธ	—
การข้ามผ่านแฟล็กสิทธิ์	ไม่มี แฟล็กเป็นเพียงคำแนะนำ	โปรแกรมอ่านที่ไม่สอดคล้องตามมาตรฐานจะละเลยแฟล็ก
การโจมตีแบบลองทุกความเป็นไปได้ต่อรหัสผ่านที่อ่อนแอ	SASLprep บวกการสืบทอดคีย์แบบวนซ้ำเพิ่มต้นทุน	รหัสผ่านที่อ่อนแอยังคงเป็นความเสี่ยงหลัก

พฤติกรรมในโหมด FIPS

Core ไม่ใช่โมดูลการเข้ารหัสลับที่ผ่านการตรวจสอบรับรอง FIPS และไม่ได้รับการรับรอง FIPS CryptoCapabilities::detectFipsMode() เป็นการตรวจสอบขณะรันแบบดีที่สุดเท่าที่ทำได้ โดยอ่านค่าแทนที่จากผู้ปฏิบัติงาน จากนั้นอ่านรายการผู้ให้บริการ OpenSSL ต่อด้วยการเรียกโหมด FIPS แบบเดิม และรายงานสถานะว่าแอ็กทีฟ ไม่มีอยู่ หรือไม่อาจระบุได้ assertFipsAvailableForProfile() จะล้มเหลวแบบปิด (fail closed) เมื่อมีการเลือกโปรไฟล์ FIPS บนโฮสต์ที่ไม่สามารถพิสูจน์ผู้ให้บริการ FIPS ได้ ไลบรารีทำงานในโหมดที่เข้ากันได้กับ FIPS เมื่อถูกกำหนดค่าให้ทำงานกับบิลด์ OpenSSL ของโฮสต์ที่โหลดผู้ให้บริการที่ผ่านการตรวจสอบรับรอง FIPS แล้ว สถานะ FIPS ที่ผ่านการตรวจสอบรับรองและได้รับการรับรองเป็นเรื่องของ Enterprise ดูเอกสาร Enterprise

ความสอดคล้องตามมาตรฐาน

การอ้าง	มาตรฐาน	ข้อ
เส้นทาง GCM ทำให้แต่ละ IV ไม่ซ้ำกันต่อหนึ่งการเรียกใช้ ซึ่งสอดคล้องกับข้อกำหนดความไม่ซ้ำกันของมาตรฐาน	NIST SP 800-38D	§8.2.1
Core เปิดเผยตัวควบคุมสำหรับอายุของคีย์และคริปโตพีเรียด การนำไปใช้งานเป็นเจ้าของนโยบาย	NIST SP 800-57 ส่วนที่ 1 ฉบับแก้ไข 5	§4
คีย์ของไฟล์ AES มีขนาด 256 บิต ซึ่งตรงกับความยาวคีย์ของมาตรฐาน	FIPS 197	§4.2.1
การสร้างคีย์ที่อยู่ภายในโทเค็นเป็นจุดเชื่อมต่อสำหรับที่เก็บคีย์ภายนอก	OASIS PKCS#11 v3.1	C_GenerateKey

ISO 32000-2:2020 §7.6 เป็นพื้นฐานเชิงบรรทัดฐานสำหรับตัวจัดการความปลอดภัยมาตรฐาน ข้อความของมาตรฐานนี้อยู่ภายใต้ข้อจำกัดของสัญญาอนุญาตและถูกเรียบเรียงใหม่ที่นี่ โดยไม่ได้ยกมาอ้างโดยตรง หน้านี้อ้างข้อตามหมายเลข ทุกประเด็นข้างต้นเรียบเรียงใหม่จากมาตรฐานที่อ้างถึง

บริบทเชิงพาณิชย์

Core นิยามและตรึงสัญญานโยบายการเข้ารหัสลับ มาพร้อมเส้นทางการเข้ารหัสลับ AES-256 และจัดหาส่วนติดต่อคีย์ในเครื่อง รุ่น Enterprise จัดหาเส้นทางการเก็บรักษาคีย์ HSM/PKCS#11 และโปรไฟล์นโยบายการเข้ารหัสลับในโหมด FIPS ไว้หลัง CryptoPolicyInterface เดียวกัน ส่วนติดต่อของสัญญาเหมือนกันในทุกรุ่น การนำไปใช้งานเป็นผู้ฉีดการนำนโยบายไปใช้และแบ็กเอนด์การเก็บรักษาคีย์ที่ต่างกัน

ดูเพิ่มเติม

Security / Encryption — เอกสารอ้างอิงเชิงลึกของ AES-256 และ AES-256-GCM
Contracts / Security Policy — สัญญานโยบายการเข้ารหัสลับและนโยบายทรัพยากร
Security / Signing — PDF Advanced Electronic Signatures (PAdES) Cryptographic Message Syntax (CMS) และไทม์สแตมป์
Audit — การบันทึกล็อกการตรวจสอบชื่อนโยบายและการดำเนินการ
Conformance — การทำงานร่วมกันของ PDF/A กับการเข้ารหัสลับ