ความปลอดภัย / การลงนาม: CMS, RFC 3161 timestamp, LTV และความเชื่อถือ

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

หน้านี้อธิบายขอบเขตการลงนามใน NextPDF Core: การสร้างลายเซ็นแบบ Content Management Syntax (CMS) การใช้ timestamp แบบ Request for Comments (RFC) 3161 การตรวจสอบความถูกต้องของห่วงโซ่ใบรับรองเทียบกับ RFC 5280 และการตรวจสอบการเพิกถอนผ่าน Online Certificate Status Protocol (OCSP) กับ certificate revocation list (CRL) เนื้อหายังคงอยู่ในระดับพฤติกรรม คลาสที่ใช้งานจริงของ Core เป็นแบบภายใน: โค้ดสำหรับใช้งานจริงเรียกใช้สัญญา SignerInterface ไม่ใช่ชนิด NextPDF\Security\Signature ที่เป็นรูปธรรม ตัวตรวจสอบและ trust anchor ที่กำหนดค่าไว้เป็นผู้ตัดสินว่าลายเซ็นที่สร้างขึ้น ผ่านการตรวจสอบ หรือไม่ ผลลัพธ์นั้นอยู่นอกเหนือการควบคุมของฝั่งผู้สร้าง และหน้านี้ระบุทุกจุดที่มีนัยสำคัญไว้แล้ว

การติดตั้ง

composer require nextpdf/core:^3

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

Core สร้างโครงสร้าง CMS SignedData จากช่วงไบต์ แล้วจัดเก็บเป็นข้อมูลที่เข้ารหัสแบบ Distinguished Encoding Rules (DER) ในรายการ Contents ของ dictionary ลายเซ็น — ISO 32000-2 §12.8.1 โครงสร้างนี้มี signed attribute ของ SignerInfo ซึ่งรวมถึง content-type และ message-digest — RFC 5652 §5.3 ตัวตรวจสอบจะคำนวณ digest ของเนื้อหาใหม่แล้วเปรียบเทียบกับ attribute message-digest การเปรียบเทียบต้องตรงกัน ลายเซ็นจึงจะถูกต้อง — RFC 5652 §5.4 SignerInfo ยังมีตัวระบุอัลกอริทึม digest และบล็อก signed-attributes ด้วย — RFC 5652 §5 Core ใช้ phpseclib3 สำหรับเส้นทางการลงนามด้วยซอฟต์แวร์ที่จัดส่งมาให้: RSA, RSASSA-PSS, ECDSA และ Ed25519

timestamp แบบ RFC 3161 คือการแลกเปลี่ยนแบบร้องขอและตอบกลับกับ Time-Stamping Authority (TSA) ซึ่งส่งโครงสร้าง TSTInfo กลับมา — RFC 3161 §2.4.1 โทเคนแต่ละรายการมี serialNumber ที่ไม่ซ้ำกันสำหรับ TSA ที่ออกโทเคนนั้น — RFC 3161 §2.4.2 — และมี genTime ที่แสดงเป็น Coordinated Universal Time (UTC) ซึ่งเป็นเวลาที่สร้างโทเคน — RFC 3161 §2.4.2

การตรวจสอบความเชื่อถือประกอบด้วยการตรวจสอบสองส่วน การตรวจสอบเส้นทางจะไล่จากใบรับรองของผู้ลงนามไปยัง trust anchor โดยตรวจสอบ basic constraint และอินพุตสำหรับการสร้างเส้นทาง — RFC 5280 §6.1 การตรวจสอบการเพิกถอนจะสอบถาม OCSP responder หรืออ่าน CRL: การตอบกลับของ OCSP รายงานเป็น good, revoked หรือ unknown — RFC 6960 §2.2 — และ thisUpdate กับ nextUpdate ของการตอบกลับเป็นตัวกำหนดขอบเขตความใหม่ของสถานะนั้น — RFC 6960 §4.2 ผู้เรียกใช้เป็นผู้จัดหา trust anchor และนโยบายความใหม่ของการเพิกถอน เอนจินตรวจสอบความถูกต้องเทียบกับอินพุตเหล่านั้น และไม่ได้จัดส่ง trust list ในตัวมาให้

พื้นผิวของ API

ชนิด	ประเภท	บทบาท	เสถียรภาพ	ตั้งแต่
SignerInterface	interface (NextPDF\Contracts)	สัญญาการลงนามที่ผู้เรียกใช้พึ่งพา	เสถียร	1.0.0
SignatureLevel	enum	ตัวเลือกระดับและการตรวจสอบความพร้อมใช้งานของ PDF Advanced Electronic Signatures (PAdES)	เสถียร	1.0.0
Rfc5280PathValidator	interface	จุดเริ่มต้นการตรวจสอบเส้นทางการรับรอง (validate(...))	เสถียร (ตรึงไว้ที่ 3.1.0)	3.1.0
RevocationStatus	enum	OCSP / CRL ผลลัพธ์: good, revoked, unknown	เสถียร	3.1.0
CaTrustAnchorBundle	type	ชุด trust anchor ที่ผู้เรียกใช้จัดหา	เสถียร	3.1.0
TstInfo	type	ฟิลด์ timestamp แบบ RFC 3161 ที่ผ่านการแยกวิเคราะห์แล้ว	เสถียร	3.2.0

SignerInterface::sign() คืนค่า SignatureResult เมท็อด toHex() ของออบเจกต์นี้ให้สตริงเลขฐานสิบหกของ /Contents และพร็อพเพอร์ตี cmsSignedData เก็บไบต์ DER ดิบไว้ คลาส NextPDF\Security\Signature ที่เป็นรูปธรรมซึ่งทำให้พฤติกรรมนี้เกิดขึ้นเป็นคลาสภายใน (stability: internal ใน manifest ของโมดูล) คลาสเหล่านี้ไม่ใช่ส่วนหนึ่งของ public API และอาจเปลี่ยนแปลงได้โดยไม่ต้องเพิ่มเลขเวอร์ชันหลัก ให้พึ่งพาสัญญาและ enum ข้างต้น

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

examples/contracts/signing-quickstart.php

<?php

declare(strict_types=1);

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

use NextPDF\Contracts\SignerInterface;

/**
 * Produce the CMS SignedData hex for a PDF /Contents field.
 *
 * @param SignerInterface $signer    A Core or Premium signer.
 * @param string          $byteRange The PDF byte range to sign.
 *
 * @return string Hex-encoded CMS SignedData.
 */
function sign(SignerInterface $signer, string $byteRange): string
{
    return $signer->sign($byteRange)->toHex();
}

ผู้เรียกใช้พึ่งพาสัญญา ทั้งตัวลงนามด้วยซอฟต์แวร์ของ Core และตัวลงนามแบบ Premium Hardware Security Module (HSM) ต่างเป็นไปตาม SignerInterface ดังนั้นโค้ดนี้จึงไม่เปลี่ยนแปลงระหว่างรุ่น

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

examples/contracts/signing-trust.php

<?php

declare(strict_types=1);

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

use NextPDF\Contracts\SignerInterface;
use NextPDF\Contracts\TimestampProviderInterface;
use NextPDF\Exception\NextPdfException;
use Psr\Log\LoggerInterface;

final readonly class TimestampedSigner
{
    public function __construct(
        private SignerInterface $signer,
        private TimestampProviderInterface $timestamps,
        private LoggerInterface $logger,
    ) {}

    /**
     * Sign a byte range, then timestamp the CMS structure.
     *
     * The timestamp's trust still depends on the verifier accepting the
     * Time-Stamping Authority; this method only produces the structure.
     *
     * @param string $byteRange The PDF byte range to sign.
     *
     * @return array{cms: string, tst: string}
     */
    public function sign(string $byteRange): array
    {
        try {
            $signature = $this->signer->sign($byteRange);
            $token = $this->timestamps->getTimestamp($signature->cmsSignedData);

            return ['cms' => $signature->toHex(), 'tst' => $token];
        } catch (NextPdfException $e) {
            $this->logger->error('Signing failed', ['error' => $e->getMessage()]);

            throw $e;
        }
    }
}

ตัวให้บริการ timestamp ถูกฉีดเข้ามา เพื่อให้การติดตั้งใช้งานกำหนด Time-Stamping Authority ของตนเองได้ บล็อก catch จะบันทึกลงล็อกแล้วโยนข้อยกเว้นซ้ำ โดยไม่กลืนความล้มเหลว ดังนั้นเส้นทางการลงนามจึงยังคงเป็นแบบ fail-closed

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

• ลายเซ็นที่สร้างขึ้นไม่ใช่ลายเซ็นที่ผ่านการตรวจสอบแล้ว การตรวจสอบเส้นทางและการเพิกถอนทำงานที่ฝั่งตัวตรวจสอบ โดยใช้ trust anchor ของตัวตรวจสอบนั้น ฝั่งผู้สร้างไม่สามารถยืนยันผลลัพธ์ได้
• digest ของช่วงไบต์ไม่รวมค่าลายเซ็น digest ที่ครอบคลุมอ็อกเท็ต Contents จะไม่ผ่านการตรวจสอบ — ISO 32000-2 §12.8.1
• สถานะการเพิกถอนมีกรอบเวลาความใหม่ การตอบกลับของ OCSP จะเป็นปัจจุบันเฉพาะในช่วง thisUpdate / nextUpdate เท่านั้น — RFC 6960 §4.2 การตอบกลับที่ล้าสมัยไม่สามารถใช้แทนการตรวจสอบที่เป็นปัจจุบัน ณ เวลาตรวจสอบได้
• เอนจินไม่ได้จัดส่ง trust list ในตัวมาให้ CaTrustAnchorBundle เป็นสิ่งที่ผู้เรียกใช้จัดหา; bundle ที่ว่างเปล่าหมายความว่าจะไม่มีห่วงโซ่ใดผ่านการตรวจสอบ ซึ่งเป็นไปตามที่ออกแบบไว้
• OCSP unknown ไม่ใช่ good ให้ถือว่า unknown เป็นผลที่ไม่สามารถตัดสินได้ ไม่ใช่การผ่านโดยปริยาย — RFC 6960 §2.2
• การคุ้มครองคีย์แบบ HSM, การลงนามแบบเลื่อนเวลาและบนคลาวด์ และตัวสร้าง PAdES B-LT / B-LTA ไม่มีอยู่ใน Core การเลือกเส้นทางเหล่านั้นในชุดแจกจ่ายของ Core จะล้มเหลวแบบ fail-closed พร้อมข้อความที่ระบุชื่อองค์ประกอบ Enterprise ที่ขาดหายไป

ประสิทธิภาพ

ลายเซ็นด้วยซอฟต์แวร์ใช้เวลาในระดับมิลลิวินาทีหลักหน่วย timestamp เพิ่มการรับส่งข้อมูลผ่านเครือข่ายไปกลับหนึ่งครั้งไปยัง TSA การตรวจสอบเส้นทางทำในเครื่องเมื่อใบรับรองอยู่ในหน่วยความจำแล้ว; การเพิกถอนเพิ่มการดึงข้อมูล OCSP หรือ CRL หนึ่งครั้งต่อใบรับรองหนึ่งใบในห่วงโซ่ งบประมาณ wall 1500 ms ครอบคลุมลายเซ็นที่ประทับ timestamp หนึ่งรายการกับ TSA ระยะไกลบนการเชื่อมต่อที่อุ่นเครื่องแล้ว การเพิกถอนกับ endpoint ที่ช้าจะเกินงบประมาณนั้น และควรอยู่นอกเส้นทางคำขอ โปรไฟล์ความสามารถในการทำซ้ำคือ structural: timestamp ฝังช่วงเวลาที่ลงนามไว้ ดังนั้นการรันสองครั้งจะต่างกันที่ไบต์ของ timestamp ขณะที่โครงสร้างเอกสารยังเหมือนกัน

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

นี่คือขอบเขตด้านการเข้ารหัสลับหลักของเอนจิน จึงระบุแบบจำลองภัยคุกคามไว้อย่างชัดเจน เอนจินคำนวณช่วงไบต์เองและไม่เคยรับค่าจากผู้เรียกใช้ เส้นทางการลงนามเป็นแบบ fail-closed: ความล้มเหลวของไพรมิทิฟหรือช่องว่างด้านความสามารถจะทำให้เกิดข้อยกเว้นแบบมีชนิด และจะไม่ลดระดับไปใช้อัลกอริทึมที่อ่อนแอกว่าโดยเงียบ ๆ ที่ระดับซึ่งต้องมี timestamp (B-T, B-LT, B-LTA), Time-Stamping Authority ที่ส่งโทเคนว่างเปล่ากลับมาถือเป็นข้อผิดพลาดร้ายแรง: ลายเซ็นจะถูกปฏิเสธ ไม่ถูกออกในสถานะที่ไม่มีการประทับ timestamp และไม่ถูกลดระดับลงโดยเงียบ ๆ เว้นแต่จะมีการเชื่อมต่อตัวจัดการข้อผิดพลาดเพื่ออนุญาตการลดระดับที่มีการบันทึกไว้ ความเชื่อถือถูกควบคุมโดยผู้เรียกใช้ตามที่ออกแบบไว้: anchor และนโยบายการเพิกถอนเป็นอินพุต ไม่ใช่ค่าเริ่มต้นของเอนจิน เพราะหากฝั่งผู้สร้างยืนยันความเชื่อถือของตนเอง ก็จะเป็นการยืนยันข้อเท็จจริงที่มีเพียงตัวตรวจสอบเท่านั้นที่สร้างขึ้นได้ ความเชื่อถือใน timestamp ย่อลงเหลือความเชื่อถือใน Time-Stamping Authority ซึ่งสามารถฉีดเข้ามาได้ เพื่อให้การติดตั้งใช้งานกำหนดของตนเองได้ หน้านี้ถูกทำเครื่องหมายเป็น export_control_class: legal-review-required เนื่องจากเกี่ยวข้องกับการลงนามด้านการเข้ารหัสลับ; แหล่งข้อมูลเชิงบรรทัดฐานทุกแหล่งถูกถอดความ และไม่มีการคัดลอกซ้ำใด ๆ ตามหลักสุขลักษณะการอ้างอิง

ความสอดคล้อง

ข้ออ้าง	มาตรฐาน	ข้อ	หลักฐาน
ลายเซ็น CMS ถูกจัดเก็บแบบเข้ารหัส DER ในรายการ Contents ของ dictionary ลายเซ็น	ISO 32000-2	§12.8.1
SignerInfo มี signed attribute content-type และ message-digest	RFC 5652	§5.3
ตัวตรวจสอบจะคำนวณ digest ของเนื้อหาใหม่และเปรียบเทียบกับ attribute message-digest	RFC 5652	§5.4
โทเคน timestamp สร้างโดย RFC 3161 TSA และมี serialNumber ที่ไม่ซ้ำกันกับ genTime แบบ UTC	RFC 3161	§2.4.1, §2.4.2	,,
การตรวจสอบเส้นทางการรับรองตรวจสอบ basic constraint และอินพุตเส้นทางจากผู้ลงนามไปยัง trust anchor	RFC 5280	§6.1	,
OCSP รายงาน certStatus เป็น good, revoked หรือ unknown โดยมีขอบเขตจาก thisUpdate / nextUpdate	RFC 6960	§2.2, §4.2	,

ข้อกำหนดทุกข้อถูกถอดความ NextPDF ไม่คัดลอกข้อความเชิงบรรทัดฐานซ้ำ โปรดดูถ้อยคำที่เป็นทางการจากมาตรฐานที่เผยแพร่แล้ว

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

Core จัดส่งตัวลงนาม CMS ด้วยซอฟต์แวร์ (RSA, RSASSA-PSS, ECDSA, Ed25519), การใช้งาน timestamp แบบ RFC 3161, การตรวจสอบเส้นทางแบบ RFC 5280 และการตรวจสอบการเพิกถอนแบบ OCSP / CRL การคุ้มครองคีย์แบบ HSM และ Public-Key Cryptography Standards #11 (PKCS#11), การลงนามแบบเลื่อนเวลาและบนคลาวด์, ตัวสร้าง PAdES B-LT และ B-LTA และโปรไฟล์นโยบายการเข้ารหัสลับแบบ Federal Information Processing Standards (FIPS) 140-3 จัดส่งในรุ่น Pro และ Enterprise Core จะแก้สิ่งเหล่านี้ที่รันไทม์เทียบกับสัญญา ดังนั้นเอนจินโอเพนซอร์สจึงไม่มีการพึ่งพาเชิงพาณิชย์ และ API ไม่เปลี่ยนแปลงเมื่ออัปเกรด

ดูเพิ่มเติม

• PAdES การแมป baseline — Core เทียบกับ Premium ในระดับ B-B, B-T, B-LT, B-LTA
• สัญญา / การลงนาม — อินเทอร์เฟซผู้ให้บริการ (SPI) SignerInterface และระดับเสถียรภาพ
• ความปลอดภัย — การเข้ารหัสลับและขอบเขตลายเซ็นในภาพรวม
• ความสอดคล้อง — การบังคับใช้โปรไฟล์ที่จับคู่กับการจัดเก็บถาวรแบบลงนาม
• CMS · RFC 3161 timestamp · Long-Term Validation (LTV) · Document Security Store (DSS) · Validation-Related Information (VRI) · Hardware Security Module (HSM) — คำศัพท์ในอภิธานศัพท์