Lewati ke konten
NextPDF

Contracts / Signing

Sekilas

Bagian berjudul “Sekilas”

Domain penandatanganan mencakup enam contract. Contract tersebut menentukan cara menghasilkan tanda tangan Cryptographic Message Syntax (CMS), menerapkan stempel waktu Request for Comments (RFC) 3161, menandatangani dengan kunci hardware security module (HSM), dan mengaktifkan validasi jangka panjang (LTV). Core memublikasikan contract tersebut; edisi Pro dan Enterprise menyertakan implementasi produksinya.

Pemasangan

Bagian berjudul “Pemasangan”
Terminal window
composer require nextpdf/core:^3

Gambaran umum konseptual

Bagian berjudul “Gambaran umum konseptual”

Tanda tangan digital Portable Document Format (PDF) adalah struktur CMS SignedData yang disimpan di dalam kamus tanda tangan. Entri Contents menyimpan struktur yang dikodekan dengan Distinguished Encoding Rules (DER). Entri ByteRange menentukan rentang bita yang dicakup oleh digest. Digest mencakup seluruh berkas dan mengecualikan nilai tanda tangan itu sendiri; lihat International Organization for Standardization (ISO) 32000-2 §12.8.1. Struktur CMS mengikuti RFC 5652 §5.1: versi, algoritme digest, konten terenkapsulasi, dan informasi penanda tangan.

SignerInterface adalah contract inti. Antarmuka ini menghasilkan CMS SignedData untuk suatu rentang bita, menerapkan stempel waktu pada nilai tanda tangan, dan melaporkan apakah LTV didukung. Ia memuat tingkat baseline PDF Advanced Electronic Signatures (PAdES) B-B hingga B-LTA sebagaimana didefinisikan oleh European Telecommunications Standards Institute (ETSI) EN 319 142. Setiap tingkat yang lebih tinggi menambahkan materi validasi. B-B memuat tanda tangan dasar. B-T menambahkan stempel waktu tanda tangan. B-LT menambahkan data pencabutan. B-LTA menambahkan stempel waktu arsip.

HsmSignerInterface menandatangani dengan kunci yang disimpan di dalam hardware security module. Kunci privat tidak pernah meninggalkan batas perangkat keras. Contract ini mengembalikan sertifikat penanda tangan dan rantai sertifikat dalam bentuk DER, sehingga lapisan CMS dapat membangun strukturnya. DeferredSignerInterface memperluas SignerInterface untuk penandatanganan asinkron. Pemanggil mengirimkan data, menerima pengidentifikasi tugas, melakukan polling hingga selesai, lalu mengambil hasilnya. Gunakan ini ketika HSM jarak jauh atau layanan kunci cloud tidak segera mengembalikan hasil.

TimestampProviderInterface meminta token stempel waktu RFC 3161. Protokolnya berupa pertukaran permintaan-tanggapan dengan Time-Stamping Authority (TSA); lihat RFC 3161 §2.4. messageImprint di dalam token adalah hash dari nilai tanda tangan; lihat RFC 3161 §2.4.2. LtvManagerInterface mengaktifkan LTV. Antarmuka ini mengumpulkan rantai sertifikat, mengambil respons Online Certificate Status Protocol (OCSP) dan certificate revocation list (CRL), membangun Document Security Store (DSS), dan menambahkan stempel waktu dokumen untuk B-LTA. CryptoPolicyInterface menyaring algoritme hash, tanda tangan, dan enkripsi yang diizinkan, beserta kekuatan kunci, sebelum operasi kriptografi apa pun dijalankan.

Permukaan API

Bagian berjudul “Permukaan API”
TipeJenisAnggota utamaStabilitasSejak
SignerInterfaceinterfacesign(string): SignatureResult, timestamp(string): string, supportsLtv(): boolstabil1.0.0
HsmSignerInterfaceinterfacesign(string, string): string, getCertificateDer(), getCertificateChainDer(), getPublicKeyAlgorithm()stabil1.0.0
DeferredSignerInterfaceinterfacesubmitForSigning(string): string, retrieveSignature(string), isComplete(string) (memperluas SignerInterface)eksperimental3.0.0
TimestampProviderInterfaceinterfacegetTimestamp(string): stringeksperimental3.0.0
LtvManagerInterfaceinterfaceenableLtv(...), addDocumentTimestamp(...)stabil1.10.0
CryptoPolicyInterfaceinterfaceisHashAlgorithmAllowed(), isSignatureAlgorithmAllowed(), isEncryptionAlgorithmAllowed(), isKeyStrengthAllowed(), getPreferredHashAlgorithm(), getName()stabil1.9.0

SignerInterface::sign() mengembalikan NextPDF\Security\Signature\SignatureResult. Properti publik $cmsSignedData berisi CMS berkode DER. Properti publik $digestHex berisi digest SHA-256. Properti publik $timestampToken berisi token TSA opsional. Aksesornya adalah toHex() / toHexPadded(int) / getSize() / hasTimestamp(). HsmSignerInterface::sign() mengembalikan bita berkode DER untuk Rivest-Shamir-Adleman (RSA) dan bita r‖s mentah untuk Elliptic Curve Digital Signature Algorithm (ECDSA). Argumen algoritme menggunakan pengidentifikasi OpenSSL.

Contoh kode — Mulai cepat

Bagian berjudul “Contoh kode — Mulai cepat”
examples/contracts/signing-quickstart.php
<?php


declare(strict_types=1);


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


use NextPDF\Contracts\SignerInterface;


/**
 * Sign a byte range with any SignerInterface implementation.
 *
 * @param SignerInterface $signer    A core or Premium signer.
 * @param string          $byteRange The PDF byte range to sign.
 *
 * @return string Hex-encoded CMS SignedData for the PDF /Contents field.
 */
function signByteRange(SignerInterface $signer, string $byteRange): string
{
    $result = $signer->sign($byteRange);


    return $result->toHex();
}

SignerInterface::sign() mengembalikan SignatureResult. toHex() menghasilkan string heksadesimal yang ditempatkan penulis PDF di bidang /Contents; bita DER mentah tersedia pada properti publik $cmsSignedData. Fungsi ini bergantung pada contract, bukan pada kelas konkret. Penanda tangan uji Core dan penanda tangan HSM Premium sama-sama memenuhinya.

Contoh kode — Produksi

Bagian berjudul “Contoh kode — Produksi”
examples/contracts/signing-production.php
<?php


declare(strict_types=1);


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


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


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


    /**
     * Sign a byte range, then timestamp the CMS structure.
     *
     * @param string $byteRange The PDF byte range to sign.
     *
     * @return array{cms: string, digest: string, tst: string}
     */
    public function sign(string $byteRange): array
    {
        if (!$this->policy->isHashAlgorithmAllowed($this->policy->getPreferredHashAlgorithm())) {
            throw new \LogicException('Preferred hash rejected by crypto policy.');
        }


        try {
            $signature = $this->signer->sign($byteRange);
            $token = $this->timestamps->getTimestamp($signature->cmsSignedData);


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


            throw $e;
        }
    }
}

Layanan ini menerima tiga contract melalui injeksi. Ia memeriksa kebijakan kripto sebelum menandatangani. SignatureResult mengekspos bita CMS pada properti publik $cmsSignedData, digest SHA-256 pada $digestHex, dan string heksadesimal /Contents melalui toHex(). Penyedia stempel waktu menerima bita CMS dan mengembalikan token berkode DER. Blok catch mencatat nama kebijakan dan melempar ulang pengecualian. Ia tidak pernah menelan kegagalan tersebut.

Kasus tepi & jebakan

Bagian berjudul “Kasus tepi & jebakan”
  • Digest rentang bita harus mengecualikan nilai tanda tangan. Digest yang mencakup entri Contents menghasilkan tanda tangan yang tidak akan pernah bisa diverifikasi; lihat ISO 32000-2 §12.8.1.
  • SignerInterface::supportsLtv() melaporkan kapabilitas, bukan keadaan. Penanda tangan dapat mendukung LTV namun tetap menghasilkan tanda tangan B-B ketika tidak ada layanan stempel waktu yang dikonfigurasi.
  • DeferredSignerInterface::retrieveSignature() mengembalikan null hingga tugas selesai. Lakukan polling isComplete() terlebih dahulu agar Anda tidak mentransfer muatan pada setiap pemeriksaan. Pengambilan bersifat idempoten setelah hasil tersedia.
  • LtvManagerInterface::addDocumentTimestamp() harus dijalankan setelah Document Security Store ditulis. Memanggilnya terlebih dahulu menghasilkan struktur B-LTA yang tidak valid.
  • CryptoPolicyInterface mengembalikan true untuk setiap algoritme ketika tidak ada kebijakan yang disetel. Di lingkungan yang teregulasi, setel kebijakan eksplisit; jangan mengandalkan default yang terbuka.
  • HsmSignerInterface::getCertificateChainDer() mengecualikan sertifikat penanda tangan. Gunakan getCertificateDer() untuk daun penanda tangan dan metode rantai untuk sertifikat perantara.

Performa

Bagian berjudul “Performa”

Biaya penandatanganan terutama berasal dari operasi kriptografi dan round trip jaringan apa pun, bukan dari contract. Tanda tangan perangkat lunak lokal umumnya membutuhkan waktu dalam satuan milidetik satu digit. Tanda tangan HSM menambahkan round trip ke perangkat. Stempel waktu menambahkan round trip jaringan ke Time-Stamping Authority. Validasi jangka panjang menambahkan satu pengambilan OCSP atau CRL per sertifikat dalam rantai. performance_budget sebesar 1500 ms wall mencakup satu tanda tangan berstempel waktu dengan TSA jarak jauh pada koneksi hangat. Validasi jangka panjang terhadap endpoint pencabutan yang lambat dapat melampauinya dan sebaiknya dijalankan di luar jalur permintaan. Profil reproduktibilitasnya adalah structural, bukan bitwise. Stempel waktu menyematkan momen penandatanganan, sehingga dua eksekusi akan berbeda pada bita stempel waktu sementara struktur dokumen tetap identik.

Catatan keamanan

Bagian berjudul “Catatan keamanan”

Contract penandatanganan adalah batas kriptografi utama mesin, sehingga model ancamannya dibuat eksplisit. Penyimpanan kunci adalah perhatian pertama: HsmSignerInterface menjaga kunci privat di dalam batas perangkat keras, dan contract tidak pernah mengekspos materi kunci. Penurunan algoritme adalah yang kedua: CryptoPolicyInterface memblokir hash lemah dan kunci pendek sebelum operasi, sehingga implementasi dapat menegakkan profil Federal Information Processing Standards (FIPS) 140-3 atau electronic identification, authentication, and trust services (eIDAS) tanpa mem-fork mesin. Kepercayaan stempel waktu adalah yang ketiga: token RFC 3161 hanya dapat dipercaya sejauh Time-Stamping Authority dapat dipercaya, sehingga contract penyedia dapat disuntikkan dan implementasi dapat menyematkan otoritasnya sendiri. Validasi jangka panjang adalah yang keempat: materi pencabutan diambil pada saat penandatanganan dan disimpan di Document Security Store sehingga verifikasi tetap dapat dilakukan setelah sertifikat kedaluwarsa. Perlakukan setiap masukan penanda tangan sebagai tidak tepercaya. Mesin menghitung rentang bita; rentang tersebut tidak pernah diterima dari pemanggil. Halaman ini ditandai export_control_class: legal-review-required karena contract mengatur penandatanganan kriptografi. Prosa ini memparafrasakan semua sumber normatif dan tidak mengutip satu pun, sesuai higiene sitasi.

Konformansi

Bagian berjudul “Konformansi”
KlaimStandarKlausaBukti
Entri Contents pada kamus tanda tangan menyimpan nilai tanda tangan sebagai CMS SignedData berkode DER atau TimeStampToken.ISO 32000-2§12.8.1
Digest dihitung terhadap rentang bita yang didefinisikan oleh larik ByteRange dan mengecualikan nilai tanda tangan.ISO 32000-2§12.8.1,
Document Security Store memuat materi validasi jangka panjang dengan validation-related information (VRI), OCSP, CRL, dan entri sertifikat.ISO 32000-2§12.8.4.3,
Validasi jangka panjang PAdES menempatkan data validasi di kamus DSS dan VRI.ETSI EN 319 142-2§6.3,
Token stempel waktu RFC 3161 mengikat hash nilai tanda tangan melalui messageImprint dalam pertukaran permintaan-tanggapan TSA.RFC 3161§2.4.2, §2.4,
Sekuens CMS SignedData membawa versi, algoritme digest, konten terenkapsulasi, dan informasi penanda tangan.RFC 5652§5.1

Semua klausa diparafrasakan. NextPDF tidak mereproduksi teks normatif. Rujuk standar yang diterbitkan untuk rumusan yang otoritatif.

Konteks komersial

Bagian berjudul “Konteks komersial”

Core memublikasikan dan membekukan contract penandatanganan. Edisi Pro dan Enterprise menyertakan implementasi produksi di balik HsmSignerInterface, LtvManagerInterface, dan penanda tangan tertunda, termasuk integrasi perangkat keras Public-Key Cryptography Standards #11 (PKCS#11) serta PAdES B-LT dan B-LTA. Core menemukan implementasi ini saat runtime dengan class_exists() dan mengonversinya ke contract, sehingga mesin sumber terbuka tidak membawa dependensi komersial dan API tidak berubah saat pemutakhiran.

Lihat juga

Bagian berjudul “Lihat juga”