สัญญาสำหรับผู้ให้บริการ KMS

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

HsmSignerInterface คือสัญญาสาธารณะที่บุคคลที่สามนำไปใช้งานเพื่อให้บริการคุ้มครองคีย์แก่ NextPDF ผู้ให้บริการของคุณเป็นผู้เก็บรักษาคีย์ส่วนตัว ส่วนเอนจินเป็นผู้สร้างโครงสร้าง Cryptographic Message Syntax (CMS)

การติดตั้ง

composer require nextpdf/core:^3

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

NextPDF แยกการประกอบลายเซ็นออกจากการคุ้มครองคีย์ เอนจินเตรียมช่วงไบต์และประกอบโครงสร้าง CMS SignedData เอนจินไม่ได้เก็บรักษาคีย์ส่วนตัว แต่ส่งต่อหน้าที่คุ้มครองคีย์ให้แบ็กเอนด์การลงนามผ่านสัญญาสาธารณะ

คุณนำหนึ่งในสามสัญญาสาธารณะต่อไปนี้ไปใช้งาน:

SignerInterface สัญญาพื้นฐาน สัญญานี้คืนค่า SignatureResult สำหรับข้อมูลที่จัดเตรียมให้ ใช้การประทับเวลา และรายงานการรองรับการตรวจสอบความถูกต้องระยะยาว ใช้สัญญานี้เมื่อตรรกะการลงนามทำงานในกระบวนการเดียวกัน
HsmSignerInterface สัญญาการคุ้มครองคีย์ การนำไปใช้งานต้องดำเนินการลงนามภายในขอบเขตฮาร์ดแวร์ คีย์ส่วนตัวต้องไม่ออกนอกขอบเขตนั้น ผู้ให้บริการระบบจัดการคีย์เป็นผู้นำสัญญานี้ไปใช้งาน
DeferredSignerInterface ส่วนขยายของ SignerInterface สำหรับแบ็กเอนด์แบบอะซิงโครนัส ผู้เรียกส่งข้อมูลเข้าไป รับตัวระบุงาน และดึงผลลัพธ์มาในภายหลัง

หน้านี้ระบุข้อกำหนดของสัญญาสาธารณะ ไม่ได้อธิบายการนำไปใช้งานภายในของ NextPDF Pro หรือ NextPDF Enterprise เอดิชันแบบเสียค่าใช้จ่ายสามารถจัดหาการนำสัญญานี้ไปใช้งานที่ได้รับการสนับสนุนได้ คุณพึ่งพาสัญญา ไม่ใช่การนำไปใช้งาน

ข้อกำหนดการคุ้มครองคีย์

สัญญากำหนดให้คีย์ส่วนตัวต้องไม่ออกนอกขอบเขตที่ปลอดภัยโดยเด็ดขาด แนวปฏิบัติการจัดการคีย์ที่เป็นที่ยอมรับรองรับข้อกำหนดนี้ National Institute of Standards and Technology (NIST) SP 800-57 Part 1 Revision 5 มองการจัดการคีย์เป็นการดูแลตลอดวงจรชีวิต เพื่อให้การสร้าง การจัดเก็บ การแจกจ่าย การใช้งาน และการทำลายเป็นไปอย่างปลอดภัย Public-Key Cryptography Standards #11 (PKCS#11) v3.1 ช่วยบังคับใช้ขอบเขตดังกล่าว เมื่อออบเจกต์คีย์ส่วนตัวกำหนด CKA_SENSITIVE เป็น true หรือ CKA_EXTRACTABLE เป็น false โทเค็นต้องไม่เปิดเผยค่าคีย์เป็นข้อความธรรมดานอกโทเค็น

การนำไปใช้งานของคุณมีหน้าที่ปฏิบัติตามข้อกำหนดนี้ เอนจินไม่สามารถบังคับใช้แทนคุณได้ หากเมท็อด sign() ของคุณสามารถอ่านไบต์คีย์ดิบเข้าสู่หน่วยความจำของกระบวนการได้ สัญญาจะสูญเสียคุณสมบัติด้านความปลอดภัย

พื้นผิว API

NextPDF\Contracts\HsmSignerInterface (stable, ตั้งแต่ 1.0.0):

เมท็อด	คืนค่า	วัตถุประสงค์
`sign(string $data, string $algorithm)`	`string`	ลงนามข้อมูลภายในขอบเขตฮาร์ดแวร์ คืนค่าไบต์ลายเซ็นดิบ โยน `RuntimeException` เมื่อล้มเหลว
`getCertificateDer()`	`string`	คืนค่าใบรับรอง X.509 ของผู้ลงนามในรูปแบบ Distinguished Encoding Rules (DER)
`getCertificateChainDer()`	`array<string>`	คืนค่าใบรับรองตัวกลาง โดยเรียงจากผู้ออกใบรับรองไปยังราก และไม่รวมใบรับรองของผู้ลงนาม
`getPublicKeyAlgorithm()`	`string`	คืนค่าตัวระบุอัลกอริทึมคีย์สาธารณะ

NextPDF\Contracts\SignerInterface (stable, ตั้งแต่ 1.0.0):

เมท็อด	คืนค่า	วัตถุประสงค์
`sign(string $data)`	`SignatureResult`	คืนค่า CMS `SignedData` ที่เข้ารหัสแบบ DER
`timestamp(string $signatureValue)`	`string`	คืนค่าโทเค็นการประทับเวลา Request for Comments (RFC) 3161 ที่เข้ารหัสแบบ DER
`supportsLtv()`	`bool`	รายงานว่าสามารถฝังข้อมูลการตรวจสอบความถูกต้องระยะยาว (LTV) ได้หรือไม่

NextPDF\Contracts\DeferredSignerInterface (experimental, ตั้งแต่ 3.0.0) ขยาย SignerInterface ด้วย submitForSigning(), retrieveSignature(), และ isComplete() สำหรับแบ็กเอนด์แบบอะซิงโครนัส

ระดับลายเซ็นที่เอนจินสร้างขึ้นเป็นไปตามโปรไฟล์ PDF Advanced Electronic Signatures (PAdES) European Telecommunications Standards Institute (ETSI) EN 319 142-2 กำหนดโปรไฟล์ PAdES แบบขยายที่ต่อยอดจากบล็อกองค์ประกอบพื้นฐานใน EN 319 142-1 เอนจินจับคู่ระดับ B-B, B-T, B-LT, และ B-LTA เข้ากับบล็อกองค์ประกอบเหล่านั้น ตัวลงนามของคุณจัดเตรียมการดำเนินการเข้ารหัสลับและวัสดุใบรับรองที่เอนจินต้องใช้

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

ผู้ให้บริการสไตล์ PKCS#11 แบบขั้นต่ำนี้มอบหมายการลงนามให้โทเค็น PHP จะไม่อ่านค่าคีย์เลย

<?php

declare(strict_types=1);

use NextPDF\Contracts\HsmSignerInterface;

final class TokenSigner implements HsmSignerInterface
{
    public function __construct(private readonly TokenSession $session) {}

    public function sign(string $data, string $algorithm = 'sha256WithRSAEncryption'): string
    {
        // The token computes the signature. The key stays inside the token.
        return $this->session->c_sign($data, $algorithm);
    }

    public function getCertificateDer(): string
    {
        return $this->session->readCertificate();
    }

    /** @return array<string> */
    public function getCertificateChainDer(): array
    {
        return $this->session->readChain();
    }

    public function getPublicKeyAlgorithm(): string
    {
        return 'rsaEncryption';
    }
}

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

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

<?php

declare(strict_types=1);

use NextPDF\Contracts\HsmSignerInterface;
use Psr\Log\LoggerInterface;
use RuntimeException;

final class KmsSigner implements HsmSignerInterface
{
    public function __construct(
        private readonly RemoteKmsClient $kms,
        private readonly string $keyId,
        private readonly LoggerInterface $logger,
    ) {}

    public function sign(string $data, string $algorithm = 'sha256WithRSAEncryption'): string
    {
        if ($data === '') {
            throw new RuntimeException('Refusing to sign empty data');
        }

        try {
            // The KMS performs the operation. The key never reaches this process.
            return $this->kms->sign($this->keyId, $data, $algorithm);
        } catch (\Throwable $error) {
            // Fail closed. Do not log key material or signature bytes.
            $this->logger->error('kms.sign.failed', ['key' => $this->keyId]);

            throw new RuntimeException('KMS signing failed', previous: $error);
        }
    }

    public function getCertificateDer(): string
    {
        return $this->kms->certificate($this->keyId);
    }

    /** @return array<string> */
    public function getCertificateChainDer(): array
    {
        return $this->kms->chain($this->keyId);
    }

    public function getPublicKeyAlgorithm(): string
    {
        return $this->kms->algorithm($this->keyId);
    }
}

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

รูปแบบไบต์ลายเซ็น คืนค่าไบต์ลายเซ็นดิบ สำหรับ Rivest-Shamir-Adleman (RSA) ไบต์อยู่ในรูปแบบ DER สำหรับ Elliptic Curve Digital Signature Algorithm (ECDSA) ไบต์คือค่า r ดิบตามด้วยค่า s ตามลำดับ
ลำดับเชน getCertificateChainDer() ไม่รวมใบรับรองของผู้ลงนาม จัดเรียงใบรับรองตัวกลางจากผู้ออกใบรับรองไปยังราก
ตัวระบุอัลกอริทึม sign() ใช้ตัวระบุสไตล์ OpenSSL getPublicKeyAlgorithm() คืนค่าชื่ออัลกอริทึม X.509
ความล้มเหลวคือการปิดการทำงานอย่างปลอดภัย โยน RuntimeException เมื่อโทเค็นหรือ KMS เกิดข้อผิดพลาดใด ๆ อย่าคืนค่าลายเซ็นที่ไม่สมบูรณ์หรือว่างเปล่า
การทำลายคีย์ เมื่อคีย์ถึงจุดสิ้นสุดของรอบการเข้ารหัสลับ ให้ทำลายคีย์ตามขั้นตอนการจัดการคีย์ของคุณ NIST SP 800-57 Part 1 Revision 5 §8.2.1.2 ระบุว่าควรทำลายคีย์ทันทีที่ไม่จำเป็นต้องใช้อีกต่อไป โดยการทำลายต้องเป็นไปตาม §8.3.4

การกำหนดถิ่นที่อยู่ของข้อมูลและมาตรการลดความเสี่ยง PII

สัญญาถ่ายโอนเฉพาะข้อมูลที่จะลงนามและวัสดุใบรับรองเท่านั้น สัญญาไม่ถ่ายโอนเนื้อหาเอกสารหรือข้อมูลส่วนบุคคลไปยังแบ็กเอนด์การลงนาม รักษาช่วงไบต์ให้เล็กที่สุด อย่าใส่ข้อมูลส่วนบุคคลในฟิลด์เหตุผลหรือสถานที่ของการลงนาม เพราะฟิลด์เหล่านั้นยังคงมองเห็นได้ในไฟล์ที่ลงนามแล้ว

การวัดและส่งข้อมูลทางไกลอย่างปลอดภัยและการล้างข้อมูลในล็อก

อย่าบันทึกข้อมูลที่ส่งให้ sign() ไบต์ลายเซ็นที่คืนค่า ตัวระบุคีย์ในรูปแบบที่กู้คืนได้ หรือองค์ประกอบส่วนตัวของใบรับรองใด ๆ ให้บันทึกเฉพาะผลลัพธ์ของการดำเนินการและการอ้างอิงที่ย้อนกลับไม่ได้เท่านั้น ฮุก SignatureAppliedEvent คือจุดยึดการตรวจสอบที่ได้รับการสนับสนุน ดู ทริกเกอร์การดำเนินการ เพิ่มเติม

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

สินทรัพย์	ภัยคุกคาม	มาตรการลดความเสี่ยง
คีย์ส่วนตัว	การหลุดออกสู่หน่วยความจำของกระบวนการ	สัญญากำหนดให้ลงนามภายในขอบเขต; PKCS#11 `CKA_SENSITIVE` / `CKA_EXTRACTABLE` บังคับใช้การไม่สามารถสกัดออกได้
ออราเคิลการลงนาม	คำขอลงนามที่ไม่จำกัด	การนำไปใช้งานจำกัดอัตราและยืนยันตัวตนของผู้เรียก
เชนใบรับรอง	การแทนที่	การนำไปใช้งานคืนค่าเชนที่สร้างขึ้นไปจนถึงรากที่เชื่อถือได้
ไบต์ลายเซ็น	การเปิดเผยผ่านล็อก	เส้นทางข้อผิดพลาดแบบปิดการทำงานอย่างปลอดภัย; ไม่มีวัสดุลายเซ็นในการวัดและส่งข้อมูลทางไกล
คีย์ที่เลยรอบการเข้ารหัสลับ	การใช้งานต่อไป	การทำลายคีย์ตาม NIST SP 800-57 Part 1 Revision 5 §8.2.1.2

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

ระดับลายเซ็นสอดคล้องกับโปรไฟล์ PAdES ETSI EN 319 142-2 §5.1 กำหนดโปรไฟล์ PAdES แบบขยายบนบล็อกองค์ประกอบพื้นฐาน EN 319 142-1 เอนจินประกอบบล็อกองค์ประกอบเหล่านั้นจากวัสดุที่ตัวลงนามของคุณจัดหาให้ การจัดการคีย์สอดคล้องกับวงจรชีวิตของ NIST SP 800-57 Part 1 Revision 5 รวมถึงข้อกำหนดการทำลายตาม §8.2.1.2 การคุ้มครองคีย์ด้วยฮาร์ดแวร์สอดคล้องกับแอตทริบิวต์คีย์ที่ไม่สามารถสกัดออกได้ของ PKCS#11 v3.1 การอ้างอิงบันทึกไว้ในส่วนหัวของหน้า

การควบคุมการส่งออกและการกำกับดูแลการตรวจสอบ

หน้านี้ครอบคลุม PKCS#11 และการคุ้มครองคีย์ด้วยโมดูลความปลอดภัยฮาร์ดแวร์ (HSM) ดังนั้นส่วนหัวของหน้าจึงกำหนด export_control_class: legal-review-required ภายใต้นโยบายการตรวจสอบเอกสาร (plan §17 gate 6) หน้าใดก็ตามที่มีโหมด เส้นทาง หรือเนื้อหาด้านความปลอดภัยที่ตรงกับ PAdES, FIPS, HSM, หรือ PKCS#11 ต้องได้รับการอนุมัติจากทีม GitHub @nextpdf-labs/crypto-reviewers ก่อนจึงจะเผยแพร่ได้ การอนุมัติ CODEOWNERS เป็นเกตการรวมที่บังคับใช้อย่างเข้มงวด: หน้าจะยังคงอยู่ในสถานะ publish: false จนกว่าทั้งการตรวจสอบการควบคุมการส่งออกทางกฎหมายและการตรวจสอบของ @nextpdf-labs/crypto-reviewers จะเสร็จสมบูรณ์

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

NextPDF Enterprise จัดหาการนำสัญญานี้ไปใช้งานที่ได้รับการสนับสนุน พร้อมการคุ้มครองคีย์ด้วยระบบจัดการคีย์ การประกอบเชนใบรับรอง และการผสานรวมการตรวจสอบ คุณสามารถนำ HsmSignerInterface ไปใช้งานเองใน Core หรือใช้การนำไปใช้งานของ Enterprise ผ่านสัญญาสาธารณะเดียวกันได้โดยไม่ต้องเปลี่ยนแปลงโค้ด

ดูเพิ่มเติม

สัญญาและมอดูลที่เกี่ยวข้อง

เอกสารอ้างอิงสัญญาการลงนาม — SignerInterface, HsmSignerInterface, DeferredSignerInterface, และผู้ให้บริการการประทับเวลา
เอกสารอ้างอิงสัญญานโยบายความปลอดภัย — พื้นผิว Service Provider Interface (SPI) ที่อ่อนไหวต่อความปลอดภัยซึ่งเป็นรายการพี่น้อง
กฎเสถียรภาพ SPI — คำมั่นด้านอินเทอร์เฟซที่อยู่เบื้องหลังระดับ stable ของสัญญาการลงนาม
ทริกเกอร์การดำเนินการและตัวฟังเหตุการณ์ — SignatureAppliedEvent, จุดยึดการตรวจสอบที่ได้รับการสนับสนุน
ภาพรวมการเขียนส่วนขยาย — พื้นผิว SPI สาธารณะทั้งหมด

อภิธานศัพท์ให้คำจำกัดความของ ระบบจัดการคีย์, รอบการเข้ารหัสลับ, และ HSM; ดูคำจำกัดความหลักแต่ละคำได้ในอภิธานศัพท์ที่เผยแพร่แล้ว