Güvenlik / imzalama: CMS, RFC 3161 zaman damgası, LTV ve güven

Bir bakışta

Bu sayfa, NextPDF Core’daki imzalama yüzeyini açıklar: bir Content Management Syntax (CMS) imzası üretmek, bir Request for Comments (RFC) 3161 zaman damgası uygulamak, bir sertifika zincirini RFC 5280 ölçütlerine göre doğrulamak ve iptal durumunu Online Certificate Status Protocol (OCSP) ile bir sertifika iptal listesi (CRL) üzerinden denetlemek. Davranış düzeyinde kalır. Core’daki uygulama sınıfları dahilîdir: üretim kodu SignerInterface sözleşmesini kullanır, somut NextPDF\Security\Signature türlerini değil. Üretilen bir imzanın doğrulanıp doğrulanmayacağına doğrulayıcı ve yapılandırılmış güven çıpaları karar verir. Bu sonuç, üreticinin denetimi dışındadır ve bu sayfa önem taşıdığı her yerde bunu belirtir.

Kurulum

composer require nextpdf/core:^3

Kavramsal genel bakış

Core, bayt aralığından bir CMS SignedData yapısı oluşturur, ardından bunu imza sözlüğünün Contents girdisine Distinguished Encoding Rules (DER) ile kodlanmış veri olarak saklar — ISO 32000-2 §12.8.1. Bu yapı, content-type ve message-digest dâhil olmak üzere SignerInfo’nun imzalı özniteliklerini taşır — RFC 5652 §5.3. Bir doğrulayıcı, içerik özetini yeniden hesaplar ve bunu message-digest özniteliğiyle karşılaştırır. İmzanın geçerli olabilmesi için bu karşılaştırmanın eşleşmesi gerekir — RFC 5652 §5.4. SignerInfo ayrıca özet algoritması tanımlayıcısını ve imzalı öznitelikler bloğunu da taşır — RFC 5652 §5. Core, sunduğu yazılım imzalama yolları için phpseclib3 kullanır: RSA, RSASSA-PSS, ECDSA ve Ed25519.

Bir RFC 3161 zaman damgası, bir TSTInfo yapısı döndüren bir Time-Stamping Authority (TSA) ile yapılan istek-yanıt alışverişidir — RFC 3161 §2.4.1. Her belirteç, düzenleyen TSA için benzersiz bir serialNumber taşır — RFC 3161 §2.4.2 — ve belirtecin oluşturulduğu an olarak Coordinated Universal Time (UTC) biçiminde ifade edilen bir genTime taşır — RFC 3161 §2.4.2.

Güven doğrulaması iki denetimden oluşur. Yol doğrulaması, temel kısıtlamaları ve yol oluşturma girdilerini denetleyerek imzalayan sertifikadan bir güven çıpasına doğru ilerler — RFC 5280 §6.1. İptal denetimi bir OCSP yanıtlayıcısını sorgular veya bir CRL okur: bir OCSP yanıtı good, revoked veya unknown bildirir — RFC 6960 §2.2 — ve yanıtın thisUpdate ve nextUpdate değerleri bu durumun ne kadar güncel olduğunu sınırlar — RFC 6960 §4.2. Güven çıpalarını ve iptal tazelik politikasını çağıran taraf sağlar. Motor, bu girdilere göre doğrulama yapar ve yerleşik bir güven listesiyle birlikte gelmez.

API yüzeyi

Tür	Çeşit	Rol	Kararlılık	Beri
`SignerInterface`	arabirim (`NextPDF\Contracts`)	Çağıranların bağlı olduğu imzalama sözleşmesi	kararlı	1.0.0
`SignatureLevel`	enum	PDF Advanced Electronic Signatures (PAdES) düzey seçici ve kullanılabilirlik yoklaması	kararlı	1.0.0
`Rfc5280PathValidator`	arabirim	Sertifika yolu doğrulamasının giriş noktası (`validate(...)`)	kararlı (3.1.0 sürümünde donduruldu)	3.1.0
`RevocationStatus`	enum	OCSP / CRL sonucu: good, revoked, unknown	kararlı	3.1.0
`CaTrustAnchorBundle`	tür	Çağıranın sağladığı güven çıpaları kümesi	kararlı	3.1.0
`TstInfo`	tür	Ayrıştırılmış RFC 3161 zaman damgası alanları	kararlı	3.2.0

SignerInterface::sign() bir SignatureResult döndürür. Bunun toHex() yöntemi /Contents onaltılık dizesini üretir ve cmsSignedData özelliği ham DER baytlarını tutar. Bu davranışı uygulayan somut NextPDF\Security\Signature sınıfları dahilîdir (modül bildiriminde stability: internal). Bunlar genel API’nin parçası değildir ve bir ana sürüm yükseltmesi olmadan değişebilir. Yukarıdaki sözleşmelere ve enum türlerine bağlı kalın.

Kod örneği — hızlı başlangıç

<?php

declare(strict_types=1);

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

use NextPDF\Contracts\SignerInterface;

/**
 * Produce the CMS SignedData hex for a PDF /Contents field.
 *
 * @param SignerInterface $signer    A Core or Premium signer.
 * @param string          $byteRange The PDF byte range to sign.
 *
 * @return string Hex-encoded CMS SignedData.
 */
function sign(SignerInterface $signer, string $byteRange): string
{
    return $signer->sign($byteRange)->toHex();
}

Çağıran taraf sözleşmeye bağlıdır. Core yazılım imzalayıcısı da Premium Hardware Security Module (HSM) imzalayıcısı da SignerInterface sözleşmesini karşılar; bu nedenle bu kod sürümler arasında değişmez.

Kod örneği — üretim

<?php

declare(strict_types=1);

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

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

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

    /**
     * Sign a byte range, then timestamp the CMS structure.
     *
     * The timestamp's trust still depends on the verifier accepting the
     * Time-Stamping Authority; this method only produces the structure.
     *
     * @param string $byteRange The PDF byte range to sign.
     *
     * @return array{cms: string, tst: string}
     */
    public function sign(string $byteRange): array
    {
        try {
            $signature = $this->signer->sign($byteRange);
            $token = $this->timestamps->getTimestamp($signature->cmsSignedData);

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

            throw $e;
        }
    }
}

Zaman damgası sağlayıcısı dışarıdan verilir; böylece bir dağıtım kullanacağı Time-Stamping Authority’yi sabitleyebilir. catch bloğu günlüğe kaydeder ve yeniden fırlatır. Hatayı asla yutmaz; bu nedenle imzalama yolu hata durumunda kapalı kalır.

Sınır durumları ve dikkat edilmesi gerekenler

Üretilen bir imza, doğrulanmış bir imza değildir. Yol doğrulaması ve iptal denetimi, doğrulayıcıda o doğrulayıcının güven çıpalarıyla çalışır. Üretici, sonucu öne süremez.
Bayt aralığı özeti, imza değerini dışarıda bırakır. Contents baytlarını kapsayan bir özet doğrulanamaz — ISO 32000-2 §12.8.1.
İptal durumunun bir tazelik penceresi vardır. Bir OCSP yanıtı yalnızca kendi thisUpdate / nextUpdate aralığı boyunca günceldir — RFC 6960 §4.2. Eski bir yanıt, doğrulama anında yapılacak yeni bir denetimin yerini tutmaz.
Motor, yerleşik bir güven listesiyle gelmez. CaTrustAnchorBundle çağıran tarafından sağlanır; boş bir paket, tasarım gereği hiçbir zincirin doğrulanmaması anlamına gelir.
OCSP unknown durumu good değildir. unknown durumunu örtük bir başarılı geçiş olarak değil, bir belirsizlik olarak değerlendirin — RFC 6960 §2.2.
HSM anahtar muhafazası, ertelenmiş ve bulut imzalama ile PAdES B-LT / B-LTA üreticisi Core içinde yer almaz. Core dağıtımında bu yolların seçilmesi, eksik Enterprise bileşenini adıyla belirten bir ileti vererek hata durumunda kapalı kalır.

Performans

Bir yazılım imzası tek haneli milisaniyeler sürer. Bir zaman damgası, TSA’ya bir ağ gidiş-dönüşü ekler. Sertifikalar bellekte olduğunda yol doğrulaması yereldir; iptal denetimi ise zincirdeki her sertifika için bir OCSP veya CRL getirme işlemi ekler. 1500 ms’lik duvar bütçesi, sıcak bir bağlantıda uzak bir TSA ile yapılan tek bir zaman damgalı imzayı kapsar. Yavaş bir uç noktaya karşı yapılan iptal denetimi bu bütçeyi aşar ve istek yolunun dışına aittir. Yeniden üretilebilirlik profili structural şeklindedir: bir zaman damgası imzalama anını gömdüğü için iki çalıştırma, zaman damgası baytlarında farklılaşırken belge yapısı özdeş kalır.

Güvenlik notları

Bu, motorun birincil kriptografik sınırıdır; bu nedenle tehdit modeli açıkça belirtilmiştir. Motor, bayt aralığını kendisi hesaplar ve bunu asla çağırandan kabul etmez. İmzalama yolu hata durumunda kapalıdır: kriptografik ilkel hatası veya yetenek eksikliği istisna fırlatır ve asla sessizce daha zayıf bir algoritmaya düşmez. Zaman damgası gerektiren bir düzeyde (B-T, B-LT, B-LTA), boş bir belirteç döndüren bir Time-Stamping Authority ölümcül bir arızadır: belgelenmiş bir düşürmeye izin vermek üzere bir arıza işleyicisi bağlanmadıkça imza reddedilir; sessizce damgasız ve düzeyi düşürülmüş bir durumda yayımlanmaz. Güven, tasarım gereği çağıran tarafından denetlenir: çıpalar ve iptal politikası girdilerdir, motorun varsayılanları değildir; çünkü kendi güvenini öne süren bir üretici, yalnızca doğrulayıcının saptayabileceği bir olguyu öne sürmüş olur. Zaman damgası güveni, Time-Stamping Authority’ye duyulan güvene indirgenir; bu kuruluş dışarıdan verilebilir olduğundan bir dağıtım kendininkini sabitleyebilir. Bu sayfa, kriptografik imzalamayı ilgilendirdiği için export_control_class: legal-review-required olarak işaretlenmiştir; atıf hijyeni gereği her normatif kaynak başka sözcüklerle ifade edilmiştir ve hiçbiri olduğu gibi aktarılmamıştır.

Uygunluk

İddia	Standart	Madde	Kanıt
CMS imzası, imza sözlüğünün `Contents` girdisinde DER ile kodlanmış olarak saklanır.	ISO 32000-2	§12.8.1
SignerInfo, content-type ve message-digest imzalı özniteliklerini taşır.	RFC 5652	§5.3
Doğrulayıcı, içerik özetini yeniden hesaplar ve bunu message-digest özniteliğiyle karşılaştırır.	RFC 5652	§5.4
Bir zaman damgası belirteci bir RFC 3161 TSA kuruluşu tarafından üretilir ve benzersiz bir serialNumber ile UTC olarak ifade edilen bir genTime taşır.	RFC 3161	§2.4.1, §2.4.2	,,
Sertifika yolu doğrulaması, temel kısıtlamaları ve imzalayandan bir güven çıpasına kadar olan yol girdilerini denetler.	RFC 5280	§6.1	,
OCSP, certStatus değerini good, revoked veya unknown olarak bildirir; bu, thisUpdate / nextUpdate ile sınırlanır.	RFC 6960	§2.2, §4.2	,

Tüm maddeler başka sözcüklerle ifade edilmiştir. NextPDF normatif metni olduğu gibi aktarmaz. Yetkili ifade için yayımlanmış standartlara başvurun.

Ticari bağlam

Core, yazılım CMS imzalayıcısını (RSA, RSASSA-PSS, ECDSA, Ed25519), RFC 3161 zaman damgası tüketimini, RFC 5280 yol doğrulamasını ve OCSP / CRL iptal denetimini sunar. HSM ve Public-Key Cryptography Standards #11 (PKCS#11) anahtar muhafazası, ertelenmiş ve bulut imzalama, PAdES B-LT ve B-LTA üreticisi ile Federal Information Processing Standards (FIPS) 140-3 kripto-politika profili Pro ve Enterprise sürümlerinde sunulur. Core bunları sözleşme üzerinden çalışma zamanında çözer; bu nedenle açık kaynaklı motor hiçbir ticari bağımlılık taşımaz ve API yükseltme sırasında değişmez.

Ayrıca bakınız

PAdES taban eşlemesi — B-B, B-T, B-LT, B-LTA genelinde Core ile Premium karşılaştırması.
Sözleşmeler / İmzalama — SignerInterface service provider interface (SPI) ve kararlılık katmanları.
Güvenlik — şifreleme ve daha geniş imza yüzeyi.
Uygunluk — imzalı arşivlemeyle eşleşen profil zorlaması.
CMS · RFC 3161 zaman damgası · Long-Term Validation (LTV) · Document Security Store (DSS) · Validation-Related Information (VRI) · Hardware Security Module (HSM) — sözlük terimleri.