Ölçekte imzalama, ödün vermeden

SpecSpec: ISO 32000-2, §12.8ISO 32000-2 §12.8SpecSpec: ETSI EN 319 142-1ETSI EN 319 142-1SpecSpec: RFC 5652, §5.1RFC 5652 §5.1

Bir bakışta

Tek bir belgeyi imzalamak kriptografik bir işlemdir. Bir son tarihe yetişerek yüz bin belgeyi imzalamak ise aynı işlemin yinelenmesidir; burada tehlikeli başarısızlık artık “yavaştı” değil, “biri imzasız çıktı ve kimse fark etmedi”dir. Bu sayfa, ilkinden vazgeçmeden ikincisini yapmakla ilgilidir: her imzanın hâlâ doğru olduğu, çalışmanın imzalayamadığı bir dosyayı yaymayı reddettiği ve büyük bir işin baştan başlamak yerine kaldığı yerden sürdüğü toplu ve eşzamanlı imzalama.

Bunun önemi nedir

İmza, belgeye özgü bir olgudur. Özeti, imza değerinin kendisini dışarıda bırakan, bildirilmiş bir bayt aralığı üzerinde hesaplanır (SpecSpec: ISO 32000-2, §12.8ISO 32000-2 §12.8); dolayısıyla bin belgeyi tek bir hamlede “toplu olarak” imzalamanın dürüst bir yolu yoktur — her biri kendi baytları üzerinde kendi CMS SignedData’sını taşır (SpecSpec: RFC 5652, §5.1RFC 5652 §5.1). Bu nedenle ölçek, tam olarak bir şeyin sessizce ters gitme olasılığını çoğaltır: kısa süre başarısız olan bir anahtar tutamacı, zaman aşımına uğrayan bir zaman damgası otoritesi, yarı yazılmış bir dosyayı elinde tutarken ölen bir işçi.

Pahalı sonuç bir çökme değildir. Bir çökme gürültülüdür ve onu yeniden denersiniz. Pahalı sonuç sessiz olandır — bitmiş gibi görünen, bir arşivde duran ve aylar sonra bir denetçinin doğrulayıcısı tarafından keşfedilen imzasız bir PDF. Hacimde, “çoğunlukla imzalı”, önemli olan tane denetlenene dek “imzalı”dan ayırt edilemez. Ölçekte imzalamanın bütün amacı, o sonucu istatistiksel olarak nadir değil, yapısal olarak olanaksız kılmaktır.

Kısa özet

• Her belge, kendi bayt aralığı üzerinde tek tek imzalanır. Toplu, bir zamanlama sözcüğüdür, bir kriptografi sözcüğü değil. Paylaşılan imza yoktur.
• Düzey bir ipucu değil, bir sözleşmedir. Bir PAdES taban düzeyi adlandırırsınız ve motor her belge için tam olarak o düzeyi üretir ya da o belgede gürültülü biçimde başarısız olur (SpecSpec: ETSI EN 319 142-1ETSI EN 319 142-1).
• İş hattı kapalı-başarısızdır. Doğru biçimde imzalanamayan bir belge, düz baytlar olarak geçip gitmez. Devredilmez, tutulur.
• Eşzamanlılık belge başınadır ve kuruluş gereği güvenlidir. İmzalama birimleri değişebilir durumu paylaşmaz; dolayısıyla iki işçi birbirinin çıktısını bozamaz.
• Büyük çalışmalar dayanıklıdır. İşlenmiş çıktı, sürdürmede yeniden yayılmaz; çöken bir çalışma her şeyi yeniden imzalamak yerine son denetim noktasından devam eder.

NextPDF bu işe nasıl yaklaşır

Tasarım tek bir ayrıma dayanır: imzayı üretmek küçük, belirlenimci, belge başına bir adımdır; binlercesini güvenle çalıştırmak ise bir orkestrasyon adımıdır. Bunları ayrı tutmak, her birinin basit kalmasını sağlayan şeydir.

İmza adımı, asla ödün vermemesi gereken adımdır. Bir düzey istersiniz — bir SignatureLevel enum durumu, motorun yorumlamak zorunda olduğu bir dizge asla — ve o düzey, o belge için bir sözleşme olarak ele alınır. Motor istenen düzeyi üretir ya da harekete geçirilebilir bir hatayla durur; sessizce daha düşük bir düzeyde imzalayıp bir kaydın daha yüksek bir düzey iddia etmesine izin vermez. Doğruluk, bunun arkasında daha çok belge olduğu için gevşemez. Yüz bininci imza, tam olarak ilki kadar dikkatle hesaplanır.

Kapalı-başarısız kuralı, bunu hacimde güvenilir kılan şeydir. NextPDF’in imzalama yolu, istediğiniz şeyin yerine, makul görünen ama imzasız bir nesne yaymayı reddeder. Desteklenen uygulama yolu, üst düzey Document API’sidir: imzayı Document::setSignature() ile yapılandırır ve ardından baytları Document::getPdfData() (ya da save() / output()) ile istersiniz; o tek yazma geçişi, ya doğru biçimde imzalanmış bir PDF yayar ya da baytları geri vermeden önce bir istisna fırlatır — çağıranın imzalı sandığı imzasız bir dosyayı asla vermez. Bir gruba uygulandığında, “biri imzasız sıyrıldı” durumunu sessiz, gizli bir kusurdan, tek başına başarısız ve yeniden denenebilir bir işe dönüştüren kural budur.

1. Warm the signing material onceOn worker boot, open the key/certificate source and the timestamp client. This cost is paid once per worker, not once per document.
2. Enqueue the documentsA queue holds the per-document jobs. The queue is the throughput dial — signing workers scale horizontally behind it.
3. Render and sign one documentA disposable unit renders the document, then signs it over its own byte range at the requested PAdES level. Nothing is shared with the next document.
4. Commit on success, hold on failureA correctly-signed file commits once. A document that could not be signed is failed and retried — never emitted as unsigned bytes.
5. Checkpoint, and resume on crashA durable run records what has committed. After a crash it continues from the last checkpoint instead of re-signing the whole batch.

A high-volume signing run end to end: shared signing material is warmed once; each document is rendered and signed individually on a disposable unit; a correctly-signed result commits exactly once, while any failure is held for retry, never passed on as unsigned bytes; a crashed run resumes from its checkpoint.

Core, kriptografik doğruluğu verir: yazılım CMS imzalama ve PAdES B-B (zaman damgası istemcisi aracılığıyla B-T); burada her belge tek tek ve kapalı-başarısız imzalanır. Büyük bir çalışmayı dayanıklı, eşzamanlı ve tam-bir-kez kılan orkestrasyon — yan etkisiz işleme motoru artı işleyen, denetim noktası, eşgüçlülük ve ölü-mektup depoları — gelişmiş sürümlerdeki Stream modülüdür; bir HSM ya da bulut KMS aracılığıyla donanım destekli imzalama da bir gelişmiş-sürüm ekidir. Core her imzanın doğru olduğunu kanıtlar; gelişmiş sürümler ise bir milyonunu hayatta kalınabilir kılar.

Human-factors note:Human-factors note

Dürüst çerçeveleme, yüksek-hacimli üretim sayfasının verim hakkında yaptığı çerçevelemenin imzalamaya uygulanmış hâlidir: karşı mühendislik yapmanız gereken başarısızlık, gürültülü olan değil, sessiz olandır. Doğru biçimde imzalayamadığı belgelerde istisna fırlatan bir imzalama iş hattı “kırılgan” değildir — size mümkün olan en ucuz anda gerçeği söylüyordur. O başarısızlıkları yutan ve imzasız dosyalar gönderen iş hattı, bir gösterimde daha akıcı hissettirir ve üretimdeki olay hâline gelir. Ölçekte her çıktıyı elle inceleme şansınız olmaz; dolayısıyla iş hattının başarısızlıktaki varsayılan davranışı, kalite denetiminizin ta kendisidir.

Pratik örnek

Aşağıdaki biçim, bir grup döngüsünün içindeki belge başına imzalama birimidir. Her yineleme, bir belgeyi adlandırılmış bir düzeyde imzalar ve ya doğru biçimde imzalanmış bir sonuç verir ya da o işi başarısız kılar — bir sonuç gibi süslenmiş imzasız baytları asla döndürmez.

<?php

declare(strict_types=1);

use NextPDF\Contracts\DocumentFactoryInterface;
use NextPDF\Security\Signature\CertificateInfo;
use NextPDF\Security\Signature\SignatureLevel;
use NextPDF\Exception\SignatureException;
use Psr\Log\LoggerInterface;

/**
 * One signing-batch iteration: render, sign at a named level, commit or fail.
 *
 * The factory and the certificate source ($certInfo, the warmed signing
 * material) are process-lifetime singletons; the document is disposable. A
 * document that cannot be signed at the requested level fails this job loudly —
 * it is never committed unsigned.
 *
 * @param iterable<int, callable(\NextPDF\Core\Document): \NextPDF\Core\Document> $jobs
 */
function signBatch(
    DocumentFactoryInterface $factory,
    CertificateInfo $certInfo,
    LoggerInterface $logger,
    iterable $jobs,
): void {
    // The level is an explicit, ordered contract — not a flag we hope is honoured.
    $level = SignatureLevel::PAdES_B_T;

    foreach ($jobs as $jobId => $build) {
        // Fresh, disposable unit — shares the warmed signing material only.
        $doc = $factory->create();
        $doc = $build($doc);

        try {
            // Sign over this document's own byte range, at exactly $level,
            // or throw. There is no "signed lower, reported higher" path.
            $doc->setSignature(certInfo: $certInfo, level: $level);
            $signed = $doc->getPdfData();
        } catch (SignatureException $e) {
            // Fail-closed: this document does NOT continue as unsigned bytes.
            // The job is failed and left for retry / dead-letter handling.
            $logger->error('pdf.sign.failed', ['job_id' => $jobId, 'reason' => $e->getMessage()]);
            continue;
        }

        // Only a correctly-signed result reaches the commit step.
        commitSignedOutput($jobId, $signed);
        unset($doc, $signed); // release per-document state before the next iteration

        $logger->info('pdf.sign.committed', ['job_id' => $jobId, 'level' => $level->value]);
    }
}

catch, yükü taşıyan satırdır. İmzalayamadığı belgeleri geri tutan bir çalışma ile onları yine de gönderen bir çalışma arasındaki farktır. continue, başarısızlığın üzerini örtmez — iş kaydedilir ve yeniden denenmek üzere bırakılır; böylece grup, neyin imzalandığı ve neyin imzalanmadığı konusunda bilinen, eksiksiz bir listeyle biter, asla sessiz bir boşlukla değil.

Yaygın yanlış anlama

İlk yanlış anlama, “toplu imzalama”nın birçok dosyaya uygulanan tek bir imza demek olduğudur. Öyle değildir ve bunu iddia eden herhangi bir sistem geçerli PAdES imzaları üretmiyordur — her belgenin özeti kendi baytlarına bağlıdır (SpecSpec: ISO 32000-2, §12.8ISO 32000-2 §12.8). Toplu yalnızca kaç tane ve ne kadar hızlı ile ilgilidir, asla kriptografik birimi paylaşmakla değil.

İkincisi, eşzamanlılığın hız için doğruluktan ödün vermek anlamına geldiği — hızlı bir imzalayıcının, dikkatli olanın atmadığı bir köşeyi kesmesi gerektiğidir. Öyle değildir. İmzalama birimleri değişebilir durum paylaşmadığından, onları paralel çalıştırmak baytları değil, zamanlamayı değiştirir. Her paralel imza, tek bir tanesiyle aynı titizlikle hesaplanır; paralellik, onların etrafındaki orkestrasyondadır.

Üçüncüsü, dayanıklılığın ilk başarısız gece çalışmasından sonra eklediğiniz bir şey olduğudur. O zamana dek çalışmayı zaten kaybetmiş olursunuz. Sürdürülebilir bir iş hattının, çökmeden önce belge başına neyin işlendiğini ve neyin işlenmediğini bilmesi gerekir — ki bu, denetim noktası ve eşgüçlülük depolarının kaydetmek için var olduğu şeyin ta kendisidir.

Sınırlar ve kapsam

• Her imza belge başınadır ve standarda bağlıdır; toplu kısayol yoktur. Hacim zamanlamayı değiştirir, kriptografik birimi değil. NextPDF her belgeyi kendi bayt aralığı üzerinde imzalar.
• Core, yazılım CMS imzalama ve PAdES B-B (zaman damgası istemcisi aracılığıyla B-T) yapar. Dayanıklı, eşzamanlı, tam-bir-kez işleme-ve-imzalama motoru, gelişmiş sürümlerdeki Stream modülüdür; HSM/KMS destekli anahtar gözetimi bir gelişmiş-sürüm ekidir. Bu sayfa o orkestrasyonu Core olarak iddia etmez.
• Kapalı-başarısız, motorun davranışıdır, kablolamanız hakkında bir garanti değildir. NextPDF, imzasız-ama-imzalı-sanılan bir dosya yaymayı reddeder ve desteklenen imzalama yolunu öne çıkarır. Ortaya çıkan hatayı yakalayıp yine de işleyen bir iş hattı, garantiyi yenmeyi seçmiştir — örnekteki catch/continue çerçevelemesinin önlemek için var olduğu şey.
• PAdES düzeyi belge başına zorunlu kılınır, çalışma için sertifikalandırılmaz. Motor istenen taban düzeyi üretir ya da başarısız olur; bu, yapısal bir zorlamadır, üretilen dosyalar için üçüncü taraf bir uygunluk hükmü değil. Düzey ilerleyişinin kendisi PAdES taban profilleri sayfasında ele alınır.
• Kuyruk, anahtar gözetimi, zaman damgası otoritesi ve nesne deposu sizindir. NextPDF, belge başına imzalama doğruluğunu ve gelişmiş sürümlerde dayanıklı orkestrasyon ilkellerini sağlar. Altyapınızı çalıştırmaz ya da TSA’nızın hesabını vermez.

High-volume and concurrent signing — edition availability

Edition	Availability
Core	○ Belge başına yazılım CMS imzalama, PAdES B-B (zaman damgası istemcisiyle B-T), her belgenin kendi bayt aralığı üzerinde tek tek imzalanmış, sessizce-imzasız çıktıya karşı kapalı-başarısız. Düz belge başına imzalama hiçbir ticari katman gerektirmez.
Pro	○ Stream modülünü ekler: yan etkisiz bir işleme motoru artı dayanıklı işleyen, denetim noktası, eşgüçlülük ve ölü-mektup depoları — baştan başlamak yerine kaldığı yerden süren eşzamanlı, çökmeye dayanıklı, tam-bir-kez toplu çalışmalar.
Enterprise	○ Donanım destekli anahtar gözetimi (PKCS#11 aracılığıyla HSM ya da bir bulut KMS) ekler; böylece özel anahtar cihazı asla terk etmez ve uzun vadeli PAdES düzeyleri (B-LT, B-LTA) yüksek-hacimli bir arşivi on yıllar boyunca doğrulanabilir tutar.

İlgili belgeler

• Yüksek-hacimli belge üretimi — bu sayfanın üzerine imzaladığı sınırlı-bellekli, kuyruğa alınmış toplu model; verim ve ölçüm disiplini için önce onu okuyun.
• PAdES taban profilleri — her düzeyin (B-B’den B-LTA’ya) ne eklediği; böylece yükümlülüğün gerektirdiği düzeyde imzalarsınız.
• İmzalar bir PDF’de nasıl yer alır — bir imzayı belge başına kılan bayt-aralığı ve sözlük temeli.
• HSM destekli imzalama — imzalama materyali donanımda yaşadığında özel-anahtar sınırının nerede durduğu.
• Stream (Pro) — tek bir imzalama birimini sürdürülebilir bir çalışmaya dönüştüren dayanıklı, eşzamanlı, tam-bir-kez işleme motoru.

Sözlük

• Toplu imzalama — birçok belgeyi bir zamanlamada imzalama. Bir zamanlama kavramıdır; her belge yine de kendi baytları üzerinde tek tek imzalanır.
• Kapalı-başarısız — aksi hâlde imzasız ya da yanlış bir çıktı üretecek bir başarısızlıkta, iş hattı belgeyi düz baytlar olarak devretmek yerine tutar ve raporlar.
• Tam-bir-kez işleme — çöken bir çalışma sürdüğünde, doğru biçimde imzalanmış bir çıktının bir kez yayımlandığı ve yeniden yayılmadığı bir dayanıklı-iş-hattı özelliği.
• Denetim noktası — neyin işlendiğine dair belge başına dayanıklı kayıt; böylece bir çalışma her şeyi yeniden imzalamak yerine durduğu yerden devam edebilir.
• CMS SignedData — içerik üzerindeki imzalar için kriptografik kap (birden çok imzalayan taşıyabilir); bu iş hattı belge başına bir imzalayanın PDF imzasını, bir grubun ürettiği belge başına birimi üretir.
• PAdES — PDF Advanced Electronic Signatures; PDF imzalama için ETSI EN 319 142 profil ailesi; taban düzeyleri B-B’den B-LTA’ya uzanır.