Sözleşmeler

Bir bakışta

NextPDF Enterprise, Enterprise bileşenlerinin bağımlılık tersine çevirme ve test edilebilirlik için bağlandığı küçük bir genel arayüz kümesi açığa çıkarır. İlki, RFC 3161 zaman damgası belirteçleri istemek için bir TSA-istemcisi sözleşmesidir. Bunlar entegrasyon ekleridir. Kendileri hiçbir kriptografik işlem gerçekleştirmez veya hiçbir uygunluk ileri sürmez.

Kullanılabilirlik ve lisanslama

Bu yetenek NextPDF Enterprise (nextpdf/enterprise) içinde sunulur ve bir Enterprise katmanı lisans zarfıyla etkinleşir. Bu yetkiye sahip olmayan bir dağıtım, yeteneğin sınıflarını yüklemez. Sürümleri karşılaştırın ve bir lisans alın.

Kurulum

composer require nextpdf/enterprise:^3

Kavramsal genel bakış

TsaClientInterface tek bir işlem bildirir: getDocumentTimestamp($documentHash), bir belge özeti için DER ile kodlanmış bir RFC 3161 TimeStampToken döndürür. Enterprise bileşenleri, zaman damgası davranışının testlerde enjekte edilip değiştirilebilmesi için somut bir istemci yerine bu arayüzü kabul eder.

TsaClientAdapter, Core zaman damgası istemcisini bu arayüze uyarlayan ince bir sarmalayıcıdır. Core istemcisi final bir sınıftır ve bir Enterprise arayüzünü doğrudan uygulayamaz; bu nedenle bağdaştırıcı, davranışı değiştirmeden ikisini köprüler. Her yerde TsaClientInterface enjekte edin; bileşim kökünde TsaClientAdapter’ı (veya kendi uygulamanızı) bağlayın.

Bu modülün ileri sürdüğü

Bu modül entegrasyon sözleşmeleri tanımlar. Kendisi hiçbir iş yapmaz.

• TsaClientInterface, bir zaman damgası belirtecinin nasıl edinileceğini açıklar. Belirteci doğrulamaz, TSA’ya kefil olmaz veya belirtecin hukuki geçerlilik kazandırdığını ileri sürmez.
• TsaClientAdapter, çağrıları değiştirmeden iletir; hiçbir davranış ve hiçbir garanti eklemez.

Bir zaman damgası belirteci edinmek, denetim ve uzun süreli doğrulama iş akışlarını destekler; hukuki bir tasdik veya bir sertifikasyon değildir.

Katman sınırı

Contracts, yalnızca Enterprise’a özgü bir entegrasyon yüzeyidir. Somut TSA istemcisi Core’da yaşar (NextPDF\Security\Timestamp); bu modül yalnızca Enterprise’a yönelik arayüzü ve bağdaştırıcıyı sağlar; böylece Enterprise bileşenleri ayrışmış ve test edilebilir kalır.

Neden bu şekilde çalışır

Core TsaClient, final bir sınıftır; bu nedenle bir Enterprise arayüzünü doğrudan uygulayamaz. Enterprise yine de bağımlılık tersine çevirme ve test edilebilir bileşenler için enjekte edilebilir, sahte oluşturulabilir (mockable) bir zaman damgası ekine ihtiyaç duyar. NextPDF bunu, arayüzü Enterprise katmanında sahiplenerek ve somut Core istemcisini ince bir bağdaştırıcı aracılığıyla köprüleyerek çözer. Gidiş-dönüş Core’da kalır; Enterprise, istemciyi çoğaltmadan veya final garantisini gevşetmeden kararlı bir sözleşme kazanır. Testlerde sahte bir uygulamayı yerine koymak, o hâlde Core koduna hiçbir değişiklik gerektirmez.

Tasarım arka planı: Zaman damgaları ve güvenilir zaman.

API yüzeyi

Sınıf / Arayüz	Sorumluluk
TsaClientInterface	Sözleşme: DER ile kodlanmış bir RFC 3161 zaman damgası belirteci iste.
TsaClientAdapter	Core zaman damgası istemcisini TsaClientInterface değerine uyarla.

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

use NextPDF\Enterprise\Contracts\TsaClientInterface;

final class MySigner
{
    public function __construct(private TsaClientInterface $tsa) {}
}

Kod örneği — üretim

use NextPDF\Enterprise\Contracts\TsaClientAdapter;

// Composition root: bridge the Core client into the Enterprise contract.
$tsa = new TsaClientAdapter($coreTsaClient);
$container->set(TsaClientInterface::class, $tsa);
// Components depend on the interface; the adapter is wired once here.

Uç durumlar ve tuzaklar

• Bağdaştırıcı, alttaki istemciden gelen istisnaları değiştirmeden iletir; TSA hatalarını çağrı yerinde işleyin.
• Döndürülen bir belirteç, bir karar değil baytlardır; gerektiğinde onu doğrulayın ve teyit edin (Evidence / Signature sayfalarına bakın).

Performans

Arayüz ve bağdaştırıcı ölçülebilir hiçbir ek yük eklemez; maliyet tamamen alttaki TSA gidiş-dönüşüdür.

Güvenlik notları

Somut istemcinin arkasındaki TSA uç noktasını bir güven sınırı olarak ele alın. Bu sözleşme, belirteci veya TSA sertifika zincirini doğrulamaz; doğrulama, imzalama ve kanıt yüzeylerine aittir.

Veri yerleşimi ve PII azaltmaları

Bu sözleşmeyi yalnızca bir belge özeti geçer — belge içeriği geçmez. Yerleşim değerlendirmeleri, bu arayüze değil, somut TSA istemcisi uygulamasına uygulanır.

Güvenli telemetri ve günlük temizleme

Bir belge özetini günlüğe kaydetmek güvenlidir. Ham belirteç baytlarını paylaşılan alıcılara günlüğe kaydetmeyin; bunları bütünlüğe duyarlı yapıtlar olarak ele alın.

Uygunluk

Davranış	Referans	Durum
Zaman damgası belirteci isteği ve bağlaması	IETF RFC 3161 §2	Yalnızca sözleşme biçimi (iş somut istemci tarafından yapılır)

Bu tablo, sözleşmenin etrafında biçimlendiği spesifikasyonu kaydeder. Arayüz bir ek tanımlar; hiçbir uygunluk veya tasdik iddiasında bulunmaz.

FIPS modu davranışı

Bu modül hiçbir kriptografik işlem gerçekleştirmez. Somut TSA istemcisi ve Security modülü, algoritma seçimini ve FIPS modu davranışını yönetir.

Tehdit modeli

Sözleşme yüzeyi en aza indirilmiştir: bir özet girer, belirteç baytları çıkar. Önlemler: sınırı hiçbir içerik geçmez ve doğrulama sorumlulukları açıkça Evidence ve Signature modüllerine devredilir.

Davranış sözleşmesi

• TSA-istemcisi arayüzü tek bir işlem bildirir: bir belge özeti için DER ile kodlanmış bir RFC 3161 TimeStampToken döndür; Enterprise bileşenleri somut bir istemciye değil, arayüze bağımlı olur.
• Bağdaştırıcı, Core zaman damgası istemcisini davranışı değiştirmeden bu arayüze köprüleyen ince bir sarmalayıcıdır ve alttaki istemciden gelen istisnaları değiştirmeden iletir.
• Arayüz, bir belirtecin nasıl edinileceğini açıklar; belirteci doğrulamaz, TSA’ya kefil olmaz veya hukuki geçerlilik ileri sürmez.
• Döndürülen bir belirteç, bir karar değil baytlardır — doğrulama ve teyit, Evidence ve Signature yüzeylerine aittir.

Yayımlama sınırı

Bu sayfa yalnızca dışarıdan gözlemlenebilir davranışı ve desteklenen genel API yüzeyini belgeler. Dahilî ad alanı yolları, yardımcı sınıflar, mekanizma tabloları, runbook dosya adları ve bilet önekleri kapsam dışındadır.

Core yedeği

Somut TSA istemcisi Core’da yaşar; bu modül yalnızca Enterprise’a yönelik arayüzü ve bağdaştırıcıyı sağlar; böylece Enterprise bileşenleri ayrışmış ve test edilebilir kalır. Enterprise’a yönelik ekin kendisinin hiçbir Core katmanı eşdeğeri yoktur — Core, bu arayüzü değil, somut istemciyi açığa çıkarır.

Pro yedeği

Pro yedeği — hiçbiri; bu yeteneğin hiçbir Pro katmanı eşdeğeri yoktur. Enterprise’a yönelik TSA-istemcisi arayüzü ve bağdaştırıcı yalnızca nextpdf/enterprise paketinde sunulur.

Enterprise sınır notu

Arayüz ve bağdaştırıcı, davranış düzeyinde açıklanmıştır. Bağdaştırıcı çağrıları değiştirmeden iletir ve hiçbir davranış eklemez; somut TSA istemcisi ve dahilîleri bir Core ilgisidir ve bu Enterprise entegrasyon yüzeyinin kapsamı dışındadır.

Dağıtım sınırı

Bu sözleşmeyi yalnızca bir belge özeti geçer — belge içeriği geçmez. Operatör, bağdaştırıcıyı veya özel bir uygulamayı bileşim kökünde bağlar ve arkasındaki somut TSA istemcisine sahiptir; yerleşim, TSA uç noktası güven sınırı ve sertifika-zinciri doğrulaması, bu arayüze değil, o somut istemciye uygulanır.

Hukuki uyumluluk sınırı

Bu sözleşme yüzeyine hiçbir ihracat denetimi kısıtlaması uygulanmaz. Bir zaman damgası belirteci edinmek, denetim ve uzun süreli doğrulama iş akışlarını destekler; hukuki bir tasdik veya bir sertifikasyon değildir. Bu belge bir hukuki görüş değildir; kendi uyumluluk ve hukuk danışmanlarınıza başvurun.

Ayrıca bakınız

• Sözleşmeler — Derinlemesine Referans — tam sınıf ve metot yüzeyi.
• Evidence — RFC 3161 belirteçlerini paketlere gömer.
• Validation — LTV yapısal denetimleri.
• Specifications: PAdES — zaman damgası bağlamı.