Contracts — เอกสารอ้างอิงเชิงลึก

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

โมดูล Contracts คือ seam การเชื่อมต่อสำหรับ Enterprise สำหรับไคลเอนต์ RFC 3161 Time Stamp Authority

• TsaClientInterface ประกาศการดำเนินการหนึ่งรายการ คือการร้องขอ TimeStampToken ที่เข้ารหัส DER สำหรับ digest ของเอกสารที่คำนวณไว้ล่วงหน้า
• TsaClientAdapter เชื่อมไคลเอนต์ timestamp ของ Core ซึ่งเป็นคลาส final เข้ากับอินเทอร์เฟซนั้นโดยไม่เปลี่ยนพฤติกรรม
• ส่วนประกอบ Enterprise เช่น LtvManager และ DocumentTimestamp รับอินเทอร์เฟซนี้ ดังนั้นพฤติกรรมของ TSA จึง inject และแทนที่ได้ในการทดสอบ
• มีเพียง hash ของเอกสารเท่านั้นที่ข้าม seam เนื้อหาของเอกสารไม่เคยข้าม

สำหรับคำแนะนำเกี่ยวกับเวิร์กโฟลว์ โปรดอ่านหน้าความสามารถ Contractsก่อน

ความพร้อมใช้งานและการอนุญาต

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

อินเทอร์เฟซไม่ทำงานใด ๆ และไม่จำกัดสิทธิ์สิ่งใดด้วยตนเอง พื้นผิว Enterprise ที่นำไปใช้จะบังคับใช้ capability code ของตนเอง เช่น enterprise.compliance.evidence บนพื้นผิว compliance-evidence

ระดับ	ให้บริการ
Core	TsaClient ที่เป็นรูปธรรม (final) ซึ่งทำการร้องขอ RFC 3161
Pro	ไม่มีรายการเทียบเท่าในโมดูล Contracts
Enterprise	seam TsaClientInterface และบริดจ์ TsaClientAdapter

composer require nextpdf/enterprise:^3

พื้นผิว API สาธารณะ

สัญลักษณ์	พารามิเตอร์	พฤติกรรมเริ่มต้น	คืนค่า	โยนหรือล้มเหลวด้วย	หมายเหตุ
TsaClientInterface::getDocumentTimestamp()	string $documentHash	ประกาศการร้องขอ timestamp-token สำหรับ digest ของเอกสารที่คำนวณไว้ล่วงหน้า	string — DER-encoded TimeStampToken	กำหนดโดยการนำไปใช้ อินเทอร์เฟซไม่ประกาศ exception ใด	การดำเนินการเดียว ซอร์สระบุอินพุตเป็น digest แบบ SHA-256
TsaClientAdapter::__construct()	TsaClient $client	เก็บไคลเอนต์ timestamp ของ Core	TsaClientAdapter	ไม่มีการประกาศ	final readonly ใช้ constructor promotion
TsaClientAdapter::getDocumentTimestamp()	string $documentHash	ส่งต่อไปยัง TsaClient::getDocumentTimestamp() โดยไม่เปลี่ยนแปลง	string — DER-encoded TimeStampToken	TsaException จากไคลเอนต์ Core ส่งต่อโดยไม่เปลี่ยนแปลง	ไม่เพิ่มพฤติกรรม ไม่กลืนสิ่งใด

namespace NextPDF\Enterprise\Contracts;

interface TsaClientInterface
{
    /**
     * Request a timestamp token for a document hash.
     *
     * @param string $documentHash SHA-256 digest of the document content
     *
     * @return string DER-encoded TimeStampToken
     */
    public function getDocumentTimestamp(string $documentHash): string;
}

namespace NextPDF\Enterprise\Contracts;

use NextPDF\Security\Timestamp\TsaClient;

final readonly class TsaClientAdapter implements TsaClientInterface
{
    public function __construct(
        private TsaClient $client,
    )

    public function getDocumentTimestamp(string $documentHash): string
}

สัญญาพฤติกรรม

TsaClientInterface::getDocumentTimestamp(string $documentHash): string คืนค่า TimeStampToken แบบ RFC 3161 ที่เข้ารหัส DER สำหรับ hash ของเอกสาร กฎที่สังเกตได้จากภายนอกมีดังนี้

• อินเทอร์เฟซประกาศการดำเนินการหนึ่งรายการ มันไม่ตรวจสอบโทเค็น ไม่รับรอง TSA และไม่ยืนยันผลทางกฎหมาย
• TsaClientAdapter ส่งต่อการเรียกไปยังไคลเอนต์ timestamp ของ Core โดยไม่เปลี่ยนแปลง ไม่มีพฤติกรรมเพิ่ม ไม่มีการลองใหม่เพิ่ม ไม่กลืน exception และไม่มีการรับประกันเพิ่มเติม จุดประสงค์เดียวของมันคือให้ไคลเอนต์ Core แบบ final สามารถสนองอินเทอร์เฟซที่หันไปทาง Enterprise เพื่อการ dependency inversion และการทดสอบ
• มีเพียง hash ของเอกสารเท่านั้นที่ข้ามขอบเขต ไม่มีเนื้อหาเอกสารถูกส่งผ่าน
• เบื้องหลังอะแดปเตอร์ ไคลเอนต์ Core จะปฏิเสธ digest ที่มีความยาวไม่ตรงกับอัลกอริทึม imprint ที่กำหนดไว้ด้วย TsaException แบบ fail-closed ก่อนกิจกรรมเครือข่ายใด ๆ มิฉะนั้น imprint ที่ติดป้ายผิดจะสร้างโทเค็นที่ไม่มี validator ที่สอดคล้องรายใดผูกได้
• พื้นผิวที่นำไปใช้ LtvManager รับ TsaClientInterface แบบ optional และต้องมีสำหรับ PAdES B-LTA DocumentTimestamp ใช้สัญญานี้เพื่อเติม /Contents ของ signature dictionary แบบ /DocTimeStamp ตัวดำเนินการต่ออายุ LTV-archive (LtvaRenewalExecutor) เชื่อม TsaClientAdapter รอบไคลเอนต์ Core เมื่อต่ออายุ timestamp ของเอกสาร

กรณีขอบและโหมดความล้มเหลว

• อะแดปเตอร์ส่งต่อ exception จากไคลเอนต์ที่อยู่ภายในโดยไม่เปลี่ยนแปลง ความล้มเหลวของ TSA ต้องถูกจัดการ ณ จุดที่เรียก
• digest ต้องเป็นไบนารีดิบภายใต้อัลกอริทึม imprint ที่กำหนดไว้ของไคลเอนต์ที่เป็นรูปธรรม (ค่าเริ่มต้น SHA-256, 32 bytes) digest ที่เข้ารหัสแบบ hex มีความยาวผิดและจะถูกปฏิเสธก่อนส่งการร้องขอใด ๆ
• โทเค็นที่คืนกลับมาคือไบต์ ไม่ใช่คำตัดสิน ตรวจสอบความถูกต้องของมันในที่ที่จำเป็น
• การนำไปใช้แบบกำหนดเองเป็นเจ้าของพื้นผิวความล้มเหลวของตนเอง สัญญากำหนดเพียงรูปแบบการคืนค่าเท่านั้น คือ TimeStampToken ที่เข้ารหัส DER

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

โมดูลนี้ไม่ทำการดำเนินการเชิงการเข้ารหัสลับใด ๆ การเลือกอัลกอริทึมและพฤติกรรมในโหมด FIPS ถูกกำกับโดยไคลเอนต์ TSA ที่เป็นรูปธรรมและโมดูล Security ดูเอกสารอ้างอิงเชิงลึก FIPS 140

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

พฤติกรรม	เอกสารอ้างอิง
การร้องขอและการผูก timestamp-token	IETF RFC 3161 §2
TimeStampReq พก MessageImprint คือ ตัวระบุอัลกอริทึม hash และ hash ของข้อมูลที่จะประทับเวลา	IETF RFC 3161 §2.4.1
messageImprint ของโทเค็นต้องเท่ากับค่าของการร้องขอ โดยขนาด hash ต้องตรงกับอัลกอริทึมที่ระบุ	IETF RFC 3161 §2.4.2

สัญญานี้ถูกออกแบบรอบ RFC 3161 ส่วนการร้องขอโทเค็นจริงและการตรวจสอบใด ๆ ดำเนินการโดยไคลเอนต์ที่เป็นรูปธรรมและพื้นผิว Evidence/Signature อินเทอร์เฟซไม่กล่าวอ้างความสอดคล้องหรือการรับรองใด ๆ NextPDF ไม่กล่าวอ้างการรับรองใด ๆ

บันทึกการพัฒนา

• ทั้งสองประเภทมี @since 3.0.0 เอกสารอ้างอิงนี้บันทึกพื้นผิวตามที่จัดส่งใน nextpdf/enterprise 3.1.0
• Inject TsaClientInterface ในส่วนประกอบที่ต้องการ timestamp เชื่อม TsaClientAdapter หรือการนำไปใช้แบบกำหนดเองที่ composition root ใช้ test double แทนใน unit test แทนที่จะใช้ TSA จริง
• ผู้ปฏิบัติการเป็นเจ้าของไคลเอนต์ TSA ที่เป็นรูปธรรมซึ่งอยู่เบื้องหลังอะแดปเตอร์ ถิ่นที่อยู่ของข้อมูล ขอบเขตความเชื่อถือของปลายทาง TSA และการตรวจสอบ certificate-chain ใช้กับไคลเอนต์นั้น ไม่ใช่กับอินเทอร์เฟซนี้
• ไม่มีข้อจำกัดด้านการควบคุมการส่งออกใดใช้กับพื้นผิวสัญญานี้ การได้มาซึ่ง timestamp token สนับสนุนเวิร์กโฟลว์การตรวจสอบและการตรวจสอบความถูกต้องระยะยาว มันไม่ใช่การยืนยันทางกฎหมายหรือการรับรอง เอกสารอ้างอิงนี้ไม่ใช่ความเห็นทางกฎหมาย
• รายละเอียดกลไกภายในอยู่ในเอกสารภายในของ source repository และอยู่นอกขอบเขตของคู่มือนี้

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

หน้านี้บันทึกเฉพาะพฤติกรรมที่สังเกตได้จากภายนอกและพื้นผิว API สาธารณะที่รองรับเท่านั้น internal namespace paths คลาสตัวช่วย ตารางกลไก ชื่อไฟล์ runbook และ ticket prefix อยู่นอกขอบเขต

ดูเพิ่มเติม

• Contracts — หน้าความสามารถ
• Evidence — เอกสารอ้างอิงเชิงลึก
• Archive — เอกสารอ้างอิงเชิงลึก
• Validation — เอกสารอ้างอิงเชิงลึก
• ข้อกำหนด: PAdES