การลงนามด้วย Cloud KMS (AWS KMS, Azure Key Vault, GCP KMS)

ภาพรวมโดยสังเขป

NextPDF Pro ลงนาม PDF ด้วยคีย์ที่เก็บไว้ในบริการจัดการคีย์บนคลาวด์ (KMS) ผู้ให้บริการที่รองรับได้แก่ Amazon Web Services (AWS) KMS, Microsoft Azure Key Vault และ Google Cloud Platform (GCP) Cloud KMS ผู้ให้บริการแต่ละรายนำสัญญาการลงนามหนึ่งเดียวมาใช้งาน แอปพลิเคชันของคุณจึงพึ่งพาสัญญา ไม่ใช่คลาสของผู้ให้บริการ มีเพียงไดเจสต์ของแอตทริบิวต์ที่ลงนามเท่านั้นที่ถูกส่งไปยังผู้ให้บริการ เอกสารไม่เคยออกจากโฮสต์ของคุณสำหรับการดำเนินการลงนาม หน้านี้เป็นระดับพฤติกรรม คือระบุสิ่งที่ผู้ให้บริการแต่ละรายส่งและรับ วิธี resolve เวอร์ชันคีย์ และจุดที่การดูแลคีย์หยุดเป็นความรับผิดชอบของ NextPDF

สัญญานี้ต่อยอดจากสัญญาตัวลงนามฮาร์ดแวร์และคลาวด์ของ Core กลยุทธ์ cloud-KMS จึงเสียบเข้ากับเส้นทางการลงนามเดียวกับที่ตัวลงนามของ Core ใช้

ข้อกำหนดเบื้องต้นระบุไว้ใน front matter และกล่าวซ้ำไว้ใน ข้อกำหนดเบื้องต้น

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

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

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

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

กระแสการลงนามคงเอกสารไว้บนโฮสต์ของคุณ:

1. เซสชันการลงนามของ Pro คำนวณไดเจสต์ของเอกสารและสร้างแอตทริบิวต์ที่ลงนามของ CMS
2. เซสชันแฮชแอตทริบิวต์ที่ลงนามและส่งเฉพาะไดเจสต์นั้นไปยังผู้ให้บริการ บริการการลงนามภายนอกที่รับไดเจสต์ของข้อความที่ผู้เรียกใช้จัดหาและคืนค่าลายเซ็นคือรูปแบบที่เป็นที่ยอมรับสำหรับการคงเอกสารไว้ภายในขอบเขตของคุณ ตามที่อธิบายไว้ในกรอบอ้างอิง EU Digital Signature Service (DSS)
3. ผู้ให้บริการลงนามไดเจสต์ด้วยเวอร์ชันคีย์ที่ resolve ได้และคืนค่าลายเซ็นดิบ
4. เซสชันประกอบ CMS SignedData และฝังลงใน PDF

ผู้ให้บริการถูกนำมาใช้งานบนการเรียก Hypertext Transfer Protocol (HTTP) แบบ PSR-18 ล้วน ๆ — ไม่มีการพึ่งพา software development kit (SDK) ของผู้ขายคลาวด์ การพิสูจน์ตัวตนถูกมอบหมายให้แอปพลิเคชันของคุณ คุณเป็นผู้จัดหา bearer token (AWS, GCP) หรือโทเค็นหรือข้อมูลรับรอง service-principal (Azure) ผู้ให้บริการแต่ละรายทำให้เอาต์พุตของตนเป็นรูปแบบปกติสำหรับ CMS คือ AWS และ GCP คืนค่าลายเซ็น Rivest–Shamir–Adleman (RSA) ในรูปแบบ DER ที่พร้อมสำหรับ CMS ส่วนลายเซ็น Elliptic Curve Digital Signature Algorithm (ECDSA) ที่ผู้ให้บริการคืนค่าเป็นคู่จำนวนเต็มดิบ (Azure) จะถูกแปลงเป็นรูปแบบที่เข้ารหัส DER ขณะที่ GCP คืนค่า ECDSA ที่เข้ารหัส DER ไว้แล้ว เส้นโค้ง ECDSA และไดเจสต์ถูกจับคู่ตามแบบแผน — P-256 กับ SHA-256, P-384 กับ SHA-384, P-521 กับ SHA-512 — ตามการจับคู่ที่แนะนำใน RFC 5480

รีจิสทรี PSR-11 resolve ผู้ให้บริการตามตัวระบุและรองรับ lazy factory ลูกค้า Enterprise แบบ self-host ลงทะเบียนไดรเวอร์ HSM หรือ KMS เฉพาะของตนได้โดยการนำสัญญาผู้ให้บริการมาใช้งานและผูกไว้ในรีจิสทรี — โดยไม่ต้อง fork NextPDF Pro

ความหมายของเวอร์ชันคีย์เฉพาะผู้ให้บริการ

ผู้ให้บริการเปิดเผยไพรมิทีฟ “เวอร์ชันที่ใช้งานอยู่” ที่แตกต่างกัน พฤติกรรมเวอร์ชันคีย์เริ่มต้นจึงต่างกัน:

• AWS KMS — เวอร์ชันคีย์ที่เป็น null จะใช้ key alias ซึ่ง AWS resolve เป็นเวอร์ชันคีย์ปัจจุบันที่ฝั่งผู้ให้บริการ
• Azure Key Vault — เวอร์ชันคีย์ที่เป็น null จะใช้ URL ของคีย์แบบไม่ระบุเวอร์ชัน ซึ่ง Azure resolve เป็นเวอร์ชันล่าสุดที่เปิดใช้งานอยู่ การกำหนดทับแบบชัดแจ้งต้องเป็นตัวระบุเลขฐานสิบหก 32 อักขระ ค่าอื่นใดจะถูกปฏิเสธเพื่อป้องกันการแทรกใน URL-segment
• GCP Cloud KMS — ปลายทาง asymmetric-sign ทำงานบนเวอร์ชันคีย์เข้ารหัสที่เฉพาะเจาะจงเท่านั้น ไม่มี “เวอร์ชันที่ใช้งานอยู่” ฝั่งเซิร์ฟเวอร์ คุณต้องปักหมุดเวอร์ชันไว้ในการกำหนดค่าหรือส่งเข้ามาแบบชัดแจ้ง หากไม่ได้ตั้งทั้งสองอย่าง ตัวลงนามจะยกข้อผิดพลาดการจัดการคีย์แทนที่จะเดา

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

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

1. ติดตั้ง NextPDF Core และแพ็กเกจ Pro และถือสิทธิ์การใช้งาน Pro ที่ใช้งานอยู่
2. จัดเตรียมคีย์ลงนามในผู้ให้บริการที่คุณเลือกและจดตัวระบุของคีย์นั้น (key alias หรือ Amazon Resource Name สำหรับ AWS; vault และชื่อคีย์สำหรับ Azure; project, location, key ring, crypto key และ version สำหรับ GCP)
3. จัดหา PSR-18 HTTP client และ PSR-17 request และ stream factory
4. รับข้อมูลรับรองผู้ให้บริการในแอปพลิเคชันของคุณ ได้แก่ bearer token สำหรับ AWS หรือ GCP หรือโทเค็นที่รับมาล่วงหน้าหรือข้อมูลรับรอง service-principal สำหรับ Azure การได้มาซึ่งโทเค็นเป็นความรับผิดชอบของแอปพลิเคชันของคุณ จัดหาความลับจาก secret manager ของคุณ ไม่ใช่จากซอร์ส

การกำหนดค่า

ผู้ให้บริการแต่ละรายมีอ็อบเจกต์การกำหนดค่าแบบ immutable ที่สร้างจากตัวระบุและข้อมูลรับรองของคุณ ข้อพิจารณาด้านการกำหนดค่าทั่วไป:

• ตัวระบุผู้ให้บริการ — aws-kms, azure-keyvault หรือ gcp-kms ใช้เป็นคีย์ค้นหาในรีจิสทรี
• อัลกอริทึม — เลือกต่อการเรียกจากชื่ออัลกอริทึมที่เซสชันการลงนามของคุณส่งเข้ามา ผู้ให้บริการจะปฏิเสธอัลกอริทึมที่ตนไม่รองรับ
• เวอร์ชันคีย์ — ปักหมุดในการกำหนดค่าหรือส่งต่อการเรียก ด้วยความหมายเฉพาะผู้ให้บริการที่อธิบายไว้ข้างต้น
• ข้อมูลรับรอง — bearer token หรือข้อมูลรับรอง service-principal ที่แอปพลิเคชันของคุณจัดหาจาก secret manager ของตน

ทีละขั้นตอน

1. สร้างการกำหนดค่าผู้ให้บริการจากตัวระบุของคุณและข้อมูลรับรองที่อ่านจาก secret manager ของคุณ
2. สร้างตัวลงนามของผู้ให้บริการด้วยการกำหนดค่า ใบรับรองของผู้ลงนามในรูปแบบ DER ห่วงโซ่ PSR-18 client และ PSR-17 factory
3. ลงทะเบียนผู้ให้บริการในรีจิสทรี PSR-11 ภายใต้ตัวระบุของผู้ให้บริการตามต้องการ เพื่อให้ตัวประสานงาน resolve ตามชื่อ
4. รันเซสชันการลงนามของ Pro คือคำนวณไดเจสต์ สร้างแอตทริบิวต์ที่ลงนาม และเรียกผู้ให้บริการด้วยไดเจสต์เท่านั้น
5. จับความล้มเหลวที่เฉพาะเจาะจงที่สุด — key-management, unsupported-algorithm หรือ signature-failed — บันทึกข้อความเชิงโครงสร้างโดยไม่มีความลับ และโยนซ้ำ

examples/pro/kms-provider-registry.php

<?php

declare(strict_types=1);

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

use NextPDF\Pro\Security\Signing\Kms\KeyManagementProviderRegistry;
use NextPDF\Pro\Security\Signing\Kms\KmsSignerInterface;

/**
 * Register cloud-KMS providers behind one registry resolved by identifier.
 *
 * Each provider is supplied as a lazy factory so a provider is only
 * constructed when first resolved. The caller depends on the registry and
 * the provider contract, not on a concrete provider class.
 *
 * @param array<non-empty-string, callable(): KmsSignerInterface> $factories
 *        Provider factories keyed by provider identifier.
 *
 * @return KeyManagementProviderRegistry The populated registry.
 */
function buildKmsRegistry(array $factories): KeyManagementProviderRegistry
{
    $registry = new KeyManagementProviderRegistry();

    foreach ($factories as $providerId => $factory) {
        $registry->registerFactory($providerId, $factory);
    }

    return $registry;
}

examples/pro/kms-sign-guarded.php

<?php

declare(strict_types=1);

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

use NextPDF\Pro\Security\Signing\Kms\KmsSignerInterface;
use NextPDF\Pro\Security\Exception\KeyManagementException;
use NextPDF\Pro\Security\Exception\SignatureFailedException;
use NextPDF\Pro\Security\Exception\UnsupportedAlgorithmException;
use Psr\Log\LoggerInterface;

final readonly class KmsSigningService
{
    public function __construct(
        private KmsSignerInterface $provider,
        private LoggerInterface $logger,
    ) {}

    /**
     * Sign a signed-attributes digest with a pinned key version.
     *
     * Only the digest is sent to the provider; the document stays on the
     * host. Each failure mode is caught as its most specific type so the
     * caller can distinguish a key-version problem from a transport failure.
     *
     * @param string      $digest     The signed-attributes digest to sign.
     * @param string      $algorithm  The OpenSSL-style algorithm name.
     * @param string|null $keyVersion The pinned key version, or null for the
     *                                 provider default (per-provider semantics).
     *
     * @throws KeyManagementException        When the key version is unknown or required and absent.
     * @throws UnsupportedAlgorithmException When the provider does not support the algorithm.
     * @throws SignatureFailedException      When the provider sign operation fails.
     *
     * @return string The raw signature bytes (DER for RSA and ECDSA per CMS rules).
     */
    public function sign(string $digest, string $algorithm, ?string $keyVersion): string
    {
        try {
            return $this->provider->signWithVersion($digest, $algorithm, $keyVersion);
        } catch (KeyManagementException | UnsupportedAlgorithmException | SignatureFailedException $e) {
            $this->logger->error('KMS signing failed', [
                'provider' => $this->provider->providerId(),
                'reason'   => $e->getMessage(),
            ]);

            throw $e;
        }
    }
}

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

1. ยืนยันว่าผู้ให้บริการอธิบายตนเองถึงอัลกอริทึมที่คุณตั้งใจจะใช้ก่อนลงนาม เพื่อให้อัลกอริทึมที่ไม่รองรับถูกจับได้ที่ขั้นการเลือก ไม่ใช่ที่การเรียกผู้ให้บริการ
2. ยืนยันว่ามีเพียงไดเจสต์เท่านั้นที่ถูกส่ง ไบต์ของเอกสารต้องไม่ปรากฏในเนื้อความของคำขอไปยังผู้ให้บริการ คำขอพกพาไดเจสต์ที่เข้ารหัส base64 ไม่ใช่ไฟล์
3. สำหรับ ECDSA ยืนยันว่าลายเซ็นที่ฝังไว้ถูกเข้ารหัส DER — ตัวลงนามแปลงลายเซ็นคู่จำนวนเต็มดิบให้คุณ
4. เปิด PDF ที่ลงนามแล้วในตัวตรวจสอบที่กำหนดค่าด้วย trust anchor ของคุณ และยืนยันว่าลายเซ็นถูกรายงานว่าครบถ้วนสมบูรณ์ในทางการเข้ารหัสลับ ลายเซ็นที่สร้างขึ้นไม่ใช่ลายเซ็นที่ผ่านการตรวจสอบ การตัดสินใจเรื่องความเชื่อถือเป็นของฝ่ายตรวจสอบ
5. ยืนยันว่าไม่มีโทเค็น ข้อมูลรับรอง หรือวัสดุคีย์ปรากฏในล็อกของแอปพลิเคชันของคุณ

ความปลอดภัยและการเป็นไปตามข้อกำหนด

• คีย์อยู่ในผู้ให้บริการ กลยุทธ์ cloud-KMS เป็นจุดผสานการทำงาน ไม่ใช่ที่จัดเก็บคีย์ NextPDF Pro ไม่ได้ถือคีย์ส่วนตัวสำหรับกลยุทธ์ KMS
• มีเพียงไดเจสต์เท่านั้นที่ข้ามขอบเขต เซสชันส่งไดเจสต์ของแอตทริบิวต์ที่ลงนามไปยังผู้ให้บริการ ไม่ใช่เอกสาร — รูปแบบ message-digest-input ที่อธิบายในกรอบอ้างอิง EU DSS
• ช่วงไบต์ถูกคำนวณโดยเอนจิน ไม่เคยรับมาจากผู้เรียกใช้
• Fail-closed ความล้มเหลวของผู้ให้บริการ เครือข่าย เวอร์ชันคีย์ หรืออัลกอริทึมที่ไม่รองรับจะยกข้อยกเว้นแบบมีชนิด เซสชันจะไม่สร้างเอกสารที่ไม่ได้ลงนามอย่างเงียบ ๆ และไม่เคยแทนที่ด้วยอัลกอริทึมที่อ่อนแอกว่า
• ข้อมูลรับรองเป็นความลับ โทเค็นและข้อมูลรับรอง service-principal มาจาก secret manager ของคุณและถูกแยกออกจากล็อก

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

การปกป้องคีย์ขึ้นอยู่กับการจัดการคีย์ KMS ที่กำหนดค่าไว้ และการปรับใช้ NextPDF Pro มอบการผสานการทำงาน KMS ไม่ใช่ที่จัดเก็บคีย์ NextPDF Pro เข้ากันได้กับ FIPS เฉพาะเมื่อกำหนดค่ากับ KMS หรือ HSM ที่ผ่านการตรวจรับรองตาม FIPS เท่านั้น ตัวมันเองไม่ใช่โมดูลการเข้ารหัสลับที่ผ่านการตรวจรับรองตาม FIPS และไม่กล่าวอ้างการรับรอง FIPS ใด ๆ

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

• เวอร์ชันคีย์ที่ไม่รู้จักหรือถูกปิดใช้งาน ผู้ให้บริการแมปการตอบสนองแบบ not-found หรือ disabled-version เป็นข้อยกเว้นการจัดการคีย์ที่ระบุชื่อผู้ให้บริการและคีย์
• GCP ที่ไม่มีเวอร์ชันที่ปักหมุด ตัวลงนาม GCP ยกข้อผิดพลาดการจัดการคีย์เมื่อทั้งการกำหนดค่าและการเรียกต่างไม่จัดหาเวอร์ชัน เพราะปลายทาง asymmetric-sign ทำงานบนเวอร์ชันที่เฉพาะเจาะจงเท่านั้น
• อัลกอริทึมที่ไม่รองรับ การร้องขออัลกอริทึมที่ผู้ให้บริการไม่รองรับจะยกข้อยกเว้น unsupported-algorithm ก่อนการเรียกเครือข่ายใด ๆ
• ความล้มเหลวในการขนส่ง ข้อผิดพลาดของ PSR-18 client ถูกแมปเป็นข้อยกเว้น signature-failed เซสชันจะไม่สร้างผลลัพธ์บางส่วน
• ข้อมูลรับรองที่ขาดหายไป ตัวลงนามที่ไม่มีโทเค็นและไม่มีข้อมูลรับรอง service-principal จะยกข้อผิดพลาดแบบมีชนิดแทนที่จะเรียกผู้ให้บริการโดยไม่ได้พิสูจน์ตัวตน

ดูเพิ่มเติม

• Security — NextPDF Pro — การปิดบัง การตรวจจับ PII และพื้นผิวการลงนามทั้งหมดของ Pro
• HSM signing — NextPDF Enterprise — การดูแลคีย์ฮาร์ดแวร์ PKCS#11
• Signature — NextPDF Enterprise — ตัวสร้างแบบระยะยาว PAdES B-LT และ B-LTA
• Security / Signing (Core) — ตัวลงนาม CMS ของ Core และสัญญากลยุทธ์การลงนาม
• KMS · CMS · ECDSA · HSM — คำศัพท์ในอภิธานศัพท์