Enterprise รุ่น

การลงนามด้วย hardware security module (PKCS#11)

โดยสรุป

NextPDF Enterprise ลงนาม PDF ด้วยคีย์ที่ถือไว้ภายใน hardware security module (HSM) คุณชี้ตัวลงนามไปยังโทเค็น PKCS#11 — สมาร์ตการ์ด โทเค็น Universal Serial Bus (USB) หรือ HSM ที่เชื่อมต่อผ่านเครือข่าย — และการดำเนินการลงนามจะรันบนอุปกรณ์ คีย์ส่วนตัวไม่เคยออกจากขอบเขตของโทเค็น หน้านี้เป็นระดับพฤติกรรม ระบุว่าตัวลงนามทำอะไร คุณจัดหาอะไร และที่ใดที่การดูแลคีย์หยุดเป็นความรับผิดชอบของ NextPDF

ตัวลงนาม HSM ถูกแปลงผ่านสัญญาตัวลงนามของ Core แอปพลิเคชันของคุณจึงพึ่งพาสัญญา ไม่ใช่ชนิด Enterprise รูปธรรม มันขยายเส้นทางการลงนามแบบ Cryptographic Message Syntax (CMS) เดียวกันกับที่ Core ใช้ ยกเว้นว่าการดำเนินการเชิงการเข้ารหัสลับถูกมอบหมายให้โทเค็น

ข้อกำหนดเบื้องต้นระบุไว้ใน front matter และทำซ้ำไว้ภายใต้ ข้อกำหนดเบื้องต้น เพื่อให้คุณไม่ประหลาดใจกลางงาน

รุ่นและสิทธิ์ใช้งาน

ความสามารถนี้มาในแพ็กเกจ NextPDF Enterprise (nextpdf/enterprise) และเปิดใช้งานด้วยซองสิทธิ์ใช้งานระดับ Enterprise การปรับใช้ที่ไม่มีสิทธิ์นั้นจะไม่โหลดคลาสของความสามารถนี้ เปรียบเทียบรุ่นและรับสิทธิ์ใช้งาน

NextPDF Core มาพร้อมตัวลงนาม CMS แบบซอฟต์แวร์ที่ถือคีย์ไว้ภายในกระบวนการหรือรับคีย์ผ่านสัญญากลยุทธ์การลงนามของ Core NextPDF Pro เพิ่มกลยุทธ์การลงนามแบบ remote และ cloud key-management-service (KMS) การดูแลคีย์ในฮาร์ดแวร์ผ่าน PKCS#11 เป็นความสามารถของ Enterprise ไม่ได้มอบโดย Core หรือ Pro

ความสามารถนี้ทำอะไร

โทเค็น PKCS#11 เปิดเผยออบเจกต์เชิงการเข้ารหัสลับ — ใบรับรองและคีย์ส่วนตัว — เบื้องหลัง shared library ของผู้จำหน่าย ตัวลงนาม Enterprise ปรับ library นั้น:

มันเปิด shared library ของโทเค็นหนึ่งครั้งต่อกระบวนการและแคชแฮนเดิลของโมดูล เพราะ PKCS#11 กำหนดให้เริ่มต้นโมดูลหนึ่งครั้งพอดีต่อกระบวนการ
มันเปิดเซสชันบนสล็อตที่กำหนดค่าไว้และล็อกอินด้วย PIN ที่จัดหามาให้ การล็อกอินพิสูจน์ตัวตนผู้ใช้ก่อนการดำเนินการกับคีย์ส่วนตัวใด ๆ ตาม PKCS#11 v3.1 §5.6.8
มันค้นหาใบรับรองการลงนามบนโทเค็นด้วยฉลาก อ่านใบรับรองในรูปแบบ Distinguished Encoding Rules (DER) และตรวจหาอัลกอริทึมคีย์สาธารณะ
ในเวลาลงนาม มันค้นหาคีย์ส่วนตัวด้วยฉลาก — ซึ่งอาจต่างจากฉลากใบรับรองในบางโทเค็น — และขอให้โทเค็นคำนวณลายเซ็น ข้อมูลที่จะลงนามถูกส่งเข้าไป คีย์คงอยู่บนอุปกรณ์

ตัวลงนามรองรับ RSA กับ padding แบบ PKCS#1 v1.5 (SHA-256, SHA-384, SHA-512) RSA กับ padding แบบ Probabilistic Signature Scheme (PSS) ที่ความยาว salt เท่ากับความยาวไดเจสต์ และ Elliptic Curve Digital Signature Algorithm (ECDSA) กับ SHA-256, SHA-384 และ SHA-512 เส้นโค้ง ECDSA และไดเจสต์ถูกจับคู่ตามแบบแผน — P-256 กับ SHA-256, P-384 กับ SHA-384, P-521 กับ SHA-512 — ตามการจับคู่ที่แนะนำใน RFC 5480 โทเค็นคืนค่าลายเซ็น ECDSA เป็นการต่อเชื่อมดิบของจำนวนเต็มสองตัว ตัวลงนามแปลงเป็นรูปแบบที่เข้ารหัส DER ที่ PDF และ OpenSSL คาดหวัง

สำหรับการสร้างลายเซ็น คีย์ RSA อย่างน้อย 2048 บิตและลำดับเส้นโค้ง ECDSA อย่างน้อย 224 บิตคือค่าต่ำสุดที่ยอมรับได้ตาม NIST SP 800-131A Rev.2 §3 ให้จัดเตรียมคีย์โทเค็นของคุณที่หรือสูงกว่าขนาดเหล่านั้น

มีเส้นทาง OpenSSL-engine ทางเลือกสำหรับโทเค็นที่หนุนด้วย engine บน OpenSSL 3.x ส่วนขยาย OpenSSL ของ PHP ไม่เปิดเผย application programming interface (API) ของ engine คลาส engine จึงเลิกใช้ เส้นทางที่หนุนด้วย engine ที่รองรับจะรันไบนารีบรรทัดคำสั่งของ OpenSSL ให้ใช้เส้นทาง PKCS#11 โดยตรงในจุดที่โทเค็นของคุณมี library แบบ PKCS#11

เหตุใดจึงทำงานเช่นนี้

การตัดสินใจที่สำคัญที่สุดคือคีย์ส่วนตัวไม่เคยออกจากโทเค็น ดังนั้นตัวลงนามจึงมอบหมายการดำเนินการเชิงการเข้ารหัสลับให้อุปกรณ์และย้ายเฉพาะข้อมูลที่จะลงนามข้ามรอยต่อ PKCS#11 มันไม่เคยอ่านหรือประกอบวัสดุคีย์ขึ้นใหม่ในหน่วยความจำ PHP มันถูกแปลงผ่านสัญญา HsmSignerInterface ของ Core แทนที่จะเป็นชนิด Enterprise รูปธรรม ดังนั้นโค้ดการลงนามจึงเหมือนกันไม่ว่าคีย์จะอยู่ในซอฟต์แวร์ cloud KMS หรือโทเค็นฮาร์ดแวร์ มันแคชแฮนเดิลของโมดูลหนึ่งครั้งต่อกระบวนการเพราะ PKCS#11 เริ่มต้นแต่ละโมดูลหนึ่งครั้งพอดีต่อกระบวนการ จากนั้นแปลงเอาต์พุต ECDSA ดิบของโทเค็นเป็น DER เพื่อให้เครื่องมือตรวจสอบเห็นการเข้ารหัสที่คาดหวัง การดูแลคีย์ ไม่ใช่ความสะดวก เป็นตัวกำหนดรูปทรง ขอบเขตความเชื่อถือคงอยู่ที่ขอบอุปกรณ์

ภูมิหลังการออกแบบ: HSM-backed signing

ข้อกำหนดเบื้องต้น

ก่อนคุณลงนามด้วย HSM ให้ยืนยันแต่ละรายการ:

ติดตั้ง NextPDF Core และแพ็กเกจ Enterprise: composer require nextpdf/core:^3 และ composer require nextpdf/enterprise
ถือสิทธิ์ใช้งาน NextPDF Enterprise ที่ใช้งานอยู่ แปลงแพ็กเกจเทียบกับข้อมูลรับรองสิทธิ์ใช้งานของคุณบน Private Packagist
ติดตั้ง shared library แบบ PKCS#11 ของผู้จำหน่ายโทเค็นบนโฮสต์ (เช่น .so บน Linux หรือ .dll บน Windows) และจดบันทึกพาธสัมบูรณ์ หมายเลขสล็อต และฉลากออบเจกต์
โหลดส่วนขยาย PHP ext-pkcs11 ส่วนขยายนี้ไม่ได้มาพร้อม PHP มาตรฐานและต้องติดตั้งแยกต่างหาก คอนสตรัคเตอร์ของตัวลงนามยกข้อผิดพลาดการดำเนินการแบบมีชนิดเมื่อส่วนขยายขาดหายไป

การกำหนดค่า

จัดหาอินพุตเหล่านี้ให้ตัวลงนาม:

พาธ library — พาธสัมบูรณ์ไปยัง shared library แบบ PKCS#11 ของผู้จำหน่าย
ตัวระบุสล็อต — หมายเลขสล็อตของโทเค็น โดยทั่วไปคือ 0
PIN — PIN ของโทเค็น ให้ถือว่าเป็นความลับ จัดหาจากตัวจัดการความลับของคุณ ไม่ใช่จากซอร์สหรือล็อก ตัวลงนามทำเครื่องหมายพารามิเตอร์ PIN ว่าอ่อนไหว มันจึงถูกแยกออกจาก stack trace และการซีเรียลไลซ์
ฉลากใบรับรอง — ฉลากของออบเจกต์ใบรับรองบนโทเค็น
ฉลากคีย์ — ฉลากของออบเจกต์คีย์ส่วนตัว เมื่อต่างจากฉลากใบรับรอง
สายโซ่ — ใบรับรองตัวกลางในรูปแบบ DER ที่เลือกได้ เมื่อโทเค็นไม่ถือใบรับรองเหล่านั้น

ตรวจสอบความพร้อมใช้งานของโทเค็นก่อนคุณสร้างตัวลงนาม การสร้างอ่านใบรับรองจากโทเค็น สล็อตหรือฉลากที่กำหนดค่าผิดจึงล้มเหลวเร็วด้วยข้อผิดพลาดแบบมีชนิดแทนที่จะเกิดในเวลาลงนาม

ทีละขั้นตอน

ยืนยันว่ารันไทม์รองรับ PKCS#11 โดยตรวจสอบความพร้อมใช้งานของส่วนขยาย อย่าสร้างตัวลงนามเมื่อส่วนขยายขาดหายไป
อ่าน PIN จากตัวจัดการความลับของคุณเข้าสู่ตัวแปรที่ไม่เคยถูกบันทึกในล็อก
สร้างตัวลงนาม HSM ด้วยพาธ library สล็อต PIN และฉลาก การสร้างจะล็อกอินและอ่านใบรับรอง
ส่งตัวลงนามไปยังตัวประสานการลงนามของ Core ผ่าน HsmSignerInterface ตัวประสานคำนวณช่วงไบต์ สร้างแอตทริบิวต์ที่ลงนามแบบ CMS ส่งข้อมูลไปยังโทเค็น และประกอบ PDF ที่ลงนาม
จับความล้มเหลวที่เฉพาะเจาะจงที่สุด บันทึกข้อความเชิงโครงสร้างโดยไม่มี PIN และยกข้อยกเว้นซ้ำ

<?php

declare(strict_types=1);

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

use NextPDF\Contracts\HsmSignerInterface;

/**
 * Build a hardware-token signer only when the runtime supports it.
 *
 * The concrete PKCS#11 signer is resolved through the Core contract so the
 * caller depends on the interface, not the Enterprise implementation type.
 * The PIN arrives from a secret resolver; it is never written to source.
 *
 * @param callable(): bool                $pkcs11Available Reports ext-pkcs11 availability.
 * @param callable(): HsmSignerInterface  $signerFactory   Builds the configured token signer.
 *
 * @throws \RuntimeException When the PKCS#11 extension is not loaded.
 *
 * @return HsmSignerInterface The token signer, ready for the Core orchestrator.
 */
function resolveHsmSigner(callable $pkcs11Available, callable $signerFactory): HsmSignerInterface
{
    if ($pkcs11Available() !== true) {
        throw new \RuntimeException(
            'PKCS#11 signing requires the ext-pkcs11 extension; install it before signing.',
        );
    }

    return $signerFactory();
}

การเดินสายในการใช้งานจริง — รายการอาร์กิวเมนต์คอนสตรัคเตอร์ที่แน่นอนและชนิดของข้อยกเว้นแบบมีชนิด — ได้รับการบันทึกไว้ใน เอกสารอ้างอิงเชิงลึก HSM

<?php

declare(strict_types=1);

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

use NextPDF\Contracts\HsmSignerInterface;
use NextPDF\Exception\NextPdfException;
use Psr\Log\LoggerInterface;

final readonly class HsmSigningService
{
    public function __construct(
        private HsmSignerInterface $signer,
        private LoggerInterface $logger,
    ) {}

    /**
     * Sign data on the token through the Core HSM contract.
     *
     * The byte range is computed by the engine, never accepted from the
     * caller. The token performs the signing operation; the private key
     * does not leave the device.
     *
     * @param string $data      The bytes the orchestrator hands to the token.
     * @param string $algorithm The OpenSSL-style signing algorithm identifier.
     *
     * @throws NextPdfException When the token operation fails.
     *
     * @return string The raw signature bytes returned by the token.
     */
    public function sign(string $data, string $algorithm): string
    {
        try {
            return $this->signer->sign($data, $algorithm);
        } catch (NextPdfException $e) {
            // Structural message only — never the PIN or key material.
            $this->logger->error('HSM signing failed', ['reason' => $e->getMessage()]);

            throw $e;
        }
    }
}

การตรวจสอบยืนยัน

ยืนยันผลในแบบที่เครื่องมือตรวจสอบจะทำ:

อ่านใบรับรองตัวลงนามและสายโซ่กลับมาในรูปแบบ DER จากตัวลงนามและยืนยันว่าตรงกับใบรับรองที่จัดเตรียมไว้บนโทเค็น
เปิด PDF ที่ลงนามในเครื่องมือตรวจสอบที่กำหนดค่าด้วยฐานความเชื่อถือของคุณและยืนยันว่าลายเซ็นถูกรายงานว่าสมบูรณ์เชิงการเข้ารหัสลับ ลายเซ็นที่ผลิตขึ้นไม่ใช่ลายเซ็นที่ผ่านการตรวจสอบยืนยัน การตัดสินใจเรื่องความเชื่อถือเป็นของเครื่องมือตรวจสอบและฐานความเชื่อถือของมัน ไม่ใช่ของผู้ผลิต
สำหรับลายเซ็น ECDSA ให้ยืนยันว่าลายเซ็นที่ฝังถูกเข้ารหัส DER — ตัวลงนามแปลงเอาต์พุตดิบของโทเค็นให้คุณ ดังนั้นเครื่องมือตรวจสอบที่ปฏิเสธรูปแบบต่อเชื่อมดิบจึงควรยังยอมรับลายเซ็นที่ฝัง
ยืนยันว่าไม่มี PIN ฉลากโทเค็น หรือวัสดุคีย์ปรากฏในล็อกของแอปพลิเคชันของคุณ

ความปลอดภัยและการปฏิบัติตามข้อกำหนด

คีย์คงอยู่บนโทเค็น ข้อมูลที่จะลงนามถูกส่งไปยังโทเค็น การดำเนินการลงนามรันภายในขอบเขตของโทเค็น คีย์ส่วนตัวไม่เคยถูกโหลดเข้าสู่หน่วยความจำ PHP
PIN เป็นความลับ มันเป็นพารามิเตอร์คอนสตรัคเตอร์ที่อ่อนไหว ถูกแยกออกจากล็อกและการซีเรียลไลซ์ จัดหาจากตัวจัดการความลับ การพิสูจน์ตัวตนซ้ำที่ล้มเหลวซ้ำ ๆ อาจล็อก PIN ที่โทเค็น โทเค็น ไม่ใช่ NextPDF เป็นผู้บังคับใช้นโยบายนั้น
fail-closed ข้อผิดพลาดของโทเค็นหรือ HSM ยกข้อยกเว้นแบบมีชนิด ตัวลงนามไม่ผลิตผลที่ไม่ได้ลงนามหรือลงนามบางส่วนและไม่เคยแทนด้วยอัลกอริทึมที่อ่อนแอกว่า
ความแข็งแรงของอัลกอริทึม จัดเตรียมคีย์ RSA อย่างน้อย 2048 บิตและเส้นโค้ง ECDSA ที่ลำดับอย่างน้อย 224 บิต ซึ่งเป็นค่าต่ำสุดที่ยอมรับได้สำหรับการสร้างลายเซ็นตาม NIST SP 800-131A Rev.2 §3
การลงนามแบบ post-quantum เป็นแบบทดลองและปิดโดยค่าเริ่มต้น มีเส้นทาง post-quantum อยู่เบื้องหลังแฟล็กที่ต้องเปิดใช้อย่างชัดแจ้ง โปรไฟล์การเก็บถาวรระยะยาวมาตรฐานแบบ PDF Advanced Electronic Signatures (PAdES) ยังไม่รู้จักชุด post-quantum และโปรแกรมดูส่วนใหญ่ปฏิเสธมันในการตรวจสอบยืนยัน อย่าเปิดใช้สำหรับลายเซ็น PAdES ในการใช้งานจริง

หน้านี้เกี่ยวข้องกับการลงนามเชิงการเข้ารหัสลับและการผสานการทำงานกับ hardware security module แหล่งอ้างอิงเชิงบรรทัดฐานทุกแหล่งถูกถอดความ ไม่มีการนำข้อความเชิงบรรทัดฐานมาแสดงซ้ำ ### ขอบเขตการดูแลคีย์

NextPDF Enterprise ผสานการทำงานกับโทเค็น PKCS#11 หรือ HSM ไม่ได้จัดเก็บ สร้าง หรือรับประกันความปลอดภัยของคีย์ลงนาม ความปลอดภัยของคีย์ขึ้นอยู่กับโทเค็นหรือ HSM การปรับใช้ และผู้ปฏิบัติงาน ไม่ใช่ NextPDF Enterprise เพียงอย่างเดียว คุณมีหน้าที่รับผิดชอบการจัดเตรียมโทเค็น การจัดการ PIN การกำหนดค่าสล็อต และการป้องกันเครือข่ายของ HSM ที่เชื่อมต่อผ่านเครือข่าย

การจัดการความล้มเหลว

ส่วนขยายขาดหาย การสร้างตัวลงนาม PKCS#11 ยกข้อยกเว้นการดำเนินการแบบมีชนิดเมื่อ ext-pkcs11 ไม่ได้ถูกโหลด ให้ตรวจสอบความพร้อมใช้งานก่อน
ไม่พบใบรับรองหรือคีย์ด้วยฉลาก การสร้างหรือการลงนามยกข้อยกเว้นแบบมีชนิดที่ระบุชื่อออบเจกต์ที่ขาดหายไป ให้ยืนยันฉลากและสล็อต
ล็อกอินอยู่แล้ว เมื่ออินสแตนซ์ตัวลงนามหลายตัวใช้โมดูลที่แคชไว้ร่วมกันสำหรับสล็อตเดียวกัน ตัวลงนามจะล็อกเอาต์และล็อกอินกลับเข้าไปเพื่อให้มีการยืนยัน PIN ใหม่ — จำเป็นสำหรับโทเค็น personal-identity-verification ที่มีนโยบาย “PIN ทุกครั้ง”
อัลกอริทึมที่ไม่รองรับ การร้องขออัลกอริทึมที่ตัวลงนามไม่จับคู่จะยกข้อผิดพลาดอาร์กิวเมนต์แทนการลงนามด้วยตัวแทน
HSM ผ่านเครือข่ายเข้าถึงไม่ได้ ข้อผิดพลาดเครือข่ายหรืออุปกรณ์ยกข้อยกเว้นแบบมีชนิด ตัวลงนามไม่เคยผลิตเอกสารที่ไม่ได้ลงนามเงียบ ๆ

ขอบเขตการเผยแพร่

หน้านี้บันทึกเฉพาะพฤติกรรมที่สังเกตได้จากภายนอกและพื้นผิว public API ที่รองรับเท่านั้น พาธเนมสเปซภายใน คลาสตัวช่วย ตารางกลไก ชื่อไฟล์ runbook และคำนำหน้าทิกเก็ตอยู่นอกขอบเขต

ดูเพิ่มเติม

HSM signing — reference — เอกสารอ้างอิงเชิงลึกสำหรับตัวลงนาม PKCS#11
Security — NextPDF Enterprise — พื้นผิวความปลอดภัยรวมของ Enterprise
Signature — NextPDF Enterprise — ตัวผลิตระยะยาว PAdES B-LT และ B-LTA
FIPS 140 cryptographic policy — นโยบายโหมด FIPS และตัวป้องกันการทดสอบตัวเอง
Cloud KMS signing — NextPDF Pro — กลยุทธ์ key-management-service ของ AWS, Azure และ GCP
Security / Signing (Core) — ตัวลงนาม CMS ของ Core และสัญญากลยุทธ์การลงนาม
HSM · PKCS#11 · CMS · ECDSA — คำศัพท์ในอภิธานศัพท์