Sözleşmeler / imzalama

Genel bakış

İmzalama alanı altı sözleşme içerir. Bu sözleşmeler, bir Cryptographic Message Syntax (CMS) imzasını nasıl üreteceğinizi, bir Request for Comments (RFC) 3161 zaman damgasını nasıl uygulayacağınızı, bir donanım güvenlik modülü (HSM) anahtarıyla nasıl imzalayacağınızı ve uzun süreli doğrulamayı (LTV) nasıl etkinleştireceğinizi tanımlar. Core, sözleşmeleri yayımlar; üretim uygulamalarını ise Pro ve Enterprise sürümleri sağlar.

Kurulum

composer require nextpdf/core:^3

Kavramsal genel bakış

Dijital bir Portable Document Format (PDF) imzası, imza sözlüğünde saklanan bir CMS SignedData yapısıdır. Contents girdisi, Distinguished Encoding Rules (DER) ile kodlanmış yapıyı tutar. ByteRange girdisi, özet tarafından kapsanan bayt aralıklarını belirtir. Özet, dosyanın tamamını kapsar ve imza değerinin kendisini hariç tutar; bakınız International Organization for Standardization (ISO) 32000-2 §12.8.1. CMS yapısı RFC 5652 §5.1 standardını izler: sürüm, özet algoritmaları, kapsüllenmiş içerik ve imzalayan bilgisi.

SignerInterface temel sözleşmedir. Bir bayt aralığı için CMS SignedData üretir, bir imza değerine zaman damgası uygular ve LTV’yi destekleyip desteklemediğini bildirir. European Telecommunications Standards Institute (ETSI) EN 319 142 tarafından tanımlandığı şekliyle B-B düzeyinden B-LTA düzeyine kadar PDF Advanced Electronic Signatures (PAdES) temel düzeylerini taşır. Her düzey, doğrulama materyali ekler. B-B, temel imzayı taşır. B-T, bir imza zaman damgası ekler. B-LT, iptal verisi ekler. B-LTA, bir arşivleme zaman damgası ekler.

HsmSignerInterface, bir donanım güvenlik modülünde saklanan bir anahtarla imzalar. Özel anahtar donanım sınırını asla terk etmez. Sözleşme, imzalayan sertifikasını ve sertifika zincirini DER biçiminde döndürür; böylece CMS katmanı yapıyı oluşturabilir. DeferredSignerInterface, eşzamansız imzalama için SignerInterface arabirimini genişletir. Çağıran taraf veriyi gönderir, bir iş tanımlayıcısı alır, tamamlanıp tamamlanmadığını yoklar ve sonucu alır. Uzak bir HSM veya bulut anahtar hizmeti sonucu hemen döndürmediğinde bunu kullanın.

TimestampProviderInterface, bir RFC 3161 zaman damgası belirteci ister. Protokol, bir Time-Stamping Authority (TSA) ile yapılan istek-yanıt alışverişidir; bakınız RFC 3161 §2.4. Belirteçteki messageImprint, imza değerinin karmasıdır; bakınız RFC 3161 §2.4.2. LtvManagerInterface, LTV özelliğini etkinleştirir. Sertifika zincirini toplar, Online Certificate Status Protocol (OCSP) ve sertifika iptal listesi (CRL) yanıtlarını getirir, Document Security Store (DSS) yapısını oluşturur ve B-LTA için bir belge zaman damgası ekler. CryptoPolicyInterface, herhangi bir şifreleme işlemi çalışmadan önce izin verilen karma, imza ve şifreleme algoritmalarını, ayrıca anahtar güçlerini denetler.

API yüzeyi

Tür	Çeşit	Temel üyeler	Kararlılık	Beri
SignerInterface	arabirim	sign(string): SignatureResult, timestamp(string): string, supportsLtv(): bool	kararlı	1.0.0
HsmSignerInterface	arabirim	sign(string, string): string, getCertificateDer(), getCertificateChainDer(), getPublicKeyAlgorithm()	kararlı	1.0.0
DeferredSignerInterface	arabirim	submitForSigning(string): string, retrieveSignature(string), isComplete(string) (SignerInterface arabirimini genişletir)	deneysel	3.0.0
TimestampProviderInterface	arabirim	getTimestamp(string): string	deneysel	3.0.0
LtvManagerInterface	arabirim	enableLtv(...), addDocumentTimestamp(...)	kararlı	1.10.0
CryptoPolicyInterface	arabirim	isHashAlgorithmAllowed(), isSignatureAlgorithmAllowed(), isEncryptionAlgorithmAllowed(), isKeyStrengthAllowed(), getPreferredHashAlgorithm(), getName()	kararlı	1.9.0

SignerInterface::sign(), bir NextPDF\Security\Signature\SignatureResult döndürür. Genel $cmsSignedData özelliği, DER ile kodlanmış CMS verisini içerir. Genel $digestHex özelliği, SHA-256 özetini içerir. Genel $timestampToken özelliği, isteğe bağlı TSA belirtecini içerir. Erişimciler toHex() / toHexPadded(int) / getSize() / hasTimestamp() şeklindedir. HsmSignerInterface::sign(), Rivest-Shamir-Adleman (RSA) için DER ile kodlanmış baytları ve Elliptic Curve Digital Signature Algorithm (ECDSA) için ham r‖s baytlarını döndürür. Algoritma argümanı, OpenSSL tanımlayıcılarını kullanır.

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

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(), bir SignatureResult döndürür. toHex(), yazıcının /Contents alanına yerleştirdiği onaltılık dizeyi verir; ham DER baytları ise genel $cmsSignedData özelliğinde bulunur. İşlev, somut bir sınıfa değil, sözleşmeye bağımlıdır. Hem bir Core test imzalayıcısı hem de bir Premium HSM imzalayıcısı bunu karşılar.

Kod örneği — üretim

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;
        }
    }
}

Hizmet, üç sözleşmeyi enjekte eder. İmzalamadan önce şifreleme ilkesini denetler. SignatureResult, CMS baytlarını genel $cmsSignedData özelliğinde, SHA-256 özetini $digestHex özelliğinde ve /Contents onaltılık dizesini toHex() aracılığıyla sunar. Zaman damgası sağlayıcısı, CMS baytlarını alır ve DER ile kodlanmış bir belirteç döndürür. Yakalama bloğu, ilke adını günlüğe yazar ve istisnayı yeniden fırlatır. Hatayı asla bastırmaz.

Sınır durumları ve dikkat edilecek noktalar

• Bayt aralığı özeti, imza değerini hariç tutmalıdır. Contents girdisini kapsayan bir özet, asla doğrulanamayacak bir imza üretir; bakınız ISO 32000-2 §12.8.1.
• SignerInterface::supportsLtv(), durumu değil yeteneği bildirir. Bir imzalayıcı LTV destekleyebilir ve yapılandırılmış bir zaman damgası hizmeti olmadığında yine de bir B-B imzası üretebilir.
• DeferredSignerInterface::retrieveSignature(), iş tamamlanana kadar null döndürür. Her denetimde yükü aktarmamak için önce isComplete() ile yoklama yapın. Bir sonuç olduğunda, alma işlemi bağımsız olarak tekrarlanabilir.
• LtvManagerInterface::addDocumentTimestamp(), Document Security Store yazıldıktan sonra çalışmalıdır. Bunun önce çağrılması, geçersiz bir B-LTA yapısı üretir.
• CryptoPolicyInterface, hiçbir ilke ayarlanmadığında her algoritma için true döndürür. Düzenlemeye tabi bir ortamda açık tanımlı bir ilke ayarlayın; izin verici varsayılana güvenmeyin.
• HsmSignerInterface::getCertificateChainDer(), imzalayan sertifikasını hariç tutar. İmzalayanın yaprak sertifikası için getCertificateDer() yöntemini, ara sertifikalar için ise zincir yöntemini kullanın.

Performans

İmzalama maliyeti, sözleşmeden değil, esas olarak şifreleme işleminden ve varsa ağ gidiş dönüşünden kaynaklanır. Yerel bir yazılım imzası genellikle tek haneli milisaniyeler düzeyinde sürer. Bir HSM imzası, aygıta gidiş dönüşü ekler. Bir zaman damgası, Time-Stamping Authority hizmetine bir ağ gidiş dönüşü ekler. Uzun süreli doğrulama, zincirdeki her sertifika için bir OCSP veya CRL getirme işlemi ekler. 1500 ms duvar süresi olan performance_budget değeri, sıcak bir bağlantıda uzak bir TSA ile yapılan tek bir zaman damgalı imzayı kapsar. Yavaş bir iptal uç noktasına yapılan uzun süreli doğrulama bunu aşar ve istek yolunun dışında çalışmalıdır. Yeniden üretilebilirlik profili structural olup bitwise değildir. Bir zaman damgası imzalama anını kaydeder; bu nedenle iki çalıştırmada belge yapısı aynı kalırken zaman damgası baytları farklılaşır.

Güvenlik notları

İmzalama sözleşmeleri, motorun birincil şifreleme sınırıdır; bu nedenle tehdit modeli açıktır. İlk konu anahtar korumasıdır: HsmSignerInterface, özel anahtarı donanım sınırının içinde tutar ve sözleşme anahtar materyalini asla açığa çıkarmaz. İkinci konu algoritma düşürme riskidir: CryptoPolicyInterface, işlemden önce zayıf karmaları ve kısa anahtarları engeller; böylece bir dağıtım, motoru çatallamadan bir Federal Information Processing Standards (FIPS) 140-3 veya elektronik kimlik tespiti, kimlik doğrulama ve güven hizmetleri (eIDAS) profilini uygulayabilir. Üçüncü konu zaman damgası güvenidir: bir RFC 3161 belirteci yalnızca Time-Stamping Authority kadar güvenilirdir; bu nedenle sağlayıcı sözleşmesi enjekte edilebilir ve bir dağıtım kendi yetkilisini sabitler. Dördüncü konu uzun süreli doğrulamadır: iptal materyali imzalama sırasında getirilir ve Document Security Store içinde saklanır; böylece doğrulama, sertifikanın süresi dolsa da geçerliliğini korur. Her imzalayan girdisini güvenilmez olarak ele alın. Bayt aralığını motor hesaplar; bu değer çağıran taraftan asla kabul edilmez. Bu sayfa, sözleşmeler şifreleme imzalamayı yönettiği için export_control_class: legal-review-required olarak işaretlenmiştir. Metin, alıntı güvenliği gereği tüm normatif kaynakları başka sözcüklerle ifade eder ve hiçbirinden alıntı yapmaz.

Uygunluk

İddia	Standart	Madde	Kanıt
İmza sözlüğü Contents girdisi, imza değerini DER ile kodlanmış CMS SignedData veya bir TimeStampToken olarak saklar.	ISO 32000-2	§12.8.1
Özet, ByteRange dizisi tarafından tanımlanan bayt aralığı üzerinden hesaplanır ve imza değerini hariç tutar.	ISO 32000-2	§12.8.1	,
Document Security Store, uzun süreli doğrulama materyalini doğrulamayla ilgili bilgi (VRI), OCSP, CRL ve sertifika girdileriyle taşır.	ISO 32000-2	§12.8.4.3	,
PAdES uzun süreli doğrulama, doğrulama verisini DSS ve VRI sözlüklerine yerleştirir.	ETSI EN 319 142-2	§6.3	,
Bir RFC 3161 zaman damgası belirteci, bir TSA istek-yanıt alışverişinde messageImprint aracılığıyla imza değerinin karmasını bağlar.	RFC 3161	§2.4.2, §2.4	,
CMS SignedData dizisi; sürüm, özet algoritmaları, kapsüllenmiş içerik ve imzalayan bilgisini taşır.	RFC 5652	§5.1

Tüm maddeler başka sözcüklerle ifade edilmiştir. NextPDF, normatif metni yeniden üretmez. Yetkili ifade için yayımlanmış standartlara başvurun.

Ticari bağlam

Core, imzalama sözleşmelerini yayımlar ve dondurur. Pro ve Enterprise sürümleri; HsmSignerInterface, LtvManagerInterface ve ertelenmiş imzalayanın arkasındaki üretim uygulamalarını sağlar; buna Public-Key Cryptography Standards #11 (PKCS#11) donanım entegrasyonu ile PAdES B-LT ve B-LTA dahildir. Core, bu uygulamaları çalışma zamanında class_exists() ile çözer ve sözleşmeye uyarlayarak kullanır; böylece açık kaynaklı motor herhangi bir ticari bağımlılık taşımaz ve yükseltme sırasında API değişmez.

Ayrıca bakınız

• Sözleşmeler: 41 genel arabirim (SPI): hizmet sağlayıcı arabirimi için genel bakış ve kararlılık katmanları.
• Sözleşmeler / güvenlik ilkesi: CryptoPolicyInterface algoritma ve anahtar denetimi.
• Sözleşmeler / çıkarma: imzalı arşivlemeyle eşleşen PDF/A uygulaması.
• Güvenlik: şifreleme ve imza uygulama yüzeyi.
• Denetim: ilke adı ve imzalama olayı denetim günlüğü.
• İstisna: imzalayanlar tarafından fırlatılan NextPdfException hiyerarşisi.