TSA yapılandırması

Bir bakışta

NextPDF, yalnızca PAdES B-T veya üzerinde imzaladığınızda bir Zaman Damgası Yetkilisi (TSA) ile iletişime geçer. B-B düzeyinde zaman damgası yoktur ve ağ çağrısı yapılmaz; bu nedenle bu sayfa bir B-B imzası için geçerli değildir.

B-T’nin kutudan çıktığı gibi çalışmasını sağlamak için NextPDF, bir yerleşik varsayılan TSA ile gelir. Bu varsayılan bir kolaylıktır: zaman damgalı bir imzanın ek yapılandırma olmadan başarılı olmasını sağlar. Herkesçe güvenilen değildir ve eIDAS-nitelikli değildir; bu nedenle, bilinçli bir tercih olmaksızın üretim veya uyumluluk kullanımı için uygun değildir. Bu sayfa, varsayılanın tam olarak ne olduğunu, NextPDF’i kendi TSA’nıza nasıl yönlendireceğinizi, zaman damgalamayı nasıl kapatacağınızı ve iki yükseltme yolunu açıklar.

Üç özellik birbirinden bağımsızdır ve birbirine karıştırılmamalıdır:

öz barındırmalı — sunucuyu kimin işlettiği ve sertifikasının hangi köke kadar zincirlendiği;
herkesçe güvenilen — ilgili tarafların kullandığı doğrulama ekosisteminin (güven deposu veya güven listesi), elle bir özel kök kurmayı gerektirmek yerine, o köke hiçbir manuel kurulum olmadan zaten güvenip güvenmediği. Bu, herhangi bir tek program (örneğin Web PKI) ile değil, ilgili tarafın güven çıpalarıyla ilgilidir;
eIDAS-nitelikli — zaman damgasının AB’de nitelikli hukuki etki taşıyıp taşımadığı.

Birlikte gelen varsayılan yalnızca öz barındırmalıdır. Herkesçe güvenilen bir TSA, ikinci özelliği ekler. Bir eIDAS-nitelikli TSA, ek olarak AB Güvenilir Listeleri aracılığıyla doğrulanan nitelikli hukuki statü taşır ve üçüncü taraf bir QTSP tarafından işletilebilir. Üç özellik birbirinden bağımsızdır — biri diğerini gerektirmez.

Yerleşik varsayılan TSA

Varsayılan uç nokta https://timestamp.pateon.com.tw adresidir; NextPDF’in kendi RFC 3161 zaman damgalama sunucusudur. Öz barındırmalıdır: zaman damgalama birimi sertifikası, herkese açık bir güven programına değil, bir özel PATEON köküne kadar zincirlenir. Bu nedenle bir ilgili taraf, o PATEON kökünü kanal dışında kurup ona güvenmedikçe, varsayılan tarafından düzenlenen bir zaman damgasını doğrulayamaz.

Bir RFC 3161 belirteci, ileri sürülen zamanın doğru olduğuna dair hiçbir dış kanıt taşımadığından, böyle herhangi bir zaman damgasına duyulan güven tamamen düzenleyen TSA’ya güvenmeye dayanır (ISO/IEC 18014-2 §7.3). Birlikte gelen varsayılan için o güven çıpası özeldir; bu yüzden varsayılan bir kolaylık ve geliştirme varsayılanıdır, uyumluluk düzeyinde bir varsayılan değildir.

Varsayılan uç nokta kullanımdayken ve çerçeveniz yapılandırılmış bir günlükçüye sahipken, NextPDF, varsayılanın herkesçe güvenilen olmadığını belirten ve bu yapılandırmaya işaret eden bir kez gösterilen bir uyarıyı süreç başlangıcında yayımlar. Uyarı bilgilendiricidir; imzalama yine de başarılı olur.

Varsayılanı geçersiz kılma

TSA uç noktasını çerçeve bağdaştırıcınızın yapılandırmasında ayarlayın. Tam anahtar bağdaştırıcıdan bağdaştırıcıya farklılık gösterir (çerçeve başına tabloya bakın): Laravel’de bu NEXTPDF_TSA_URL ortam değişkenidir, Symfony’de nextpdf.tsa.url bundle düğümüdür ve CodeIgniter’da nextPdf.tsa.url ortam anahtarıdır.

Etkin TSA, en yüksekten başlayarak şu öncelikle çözümlenir:

Kendiniz oluşturup enjekte ettiğiniz açık bir TsaClient — bu her zaman kazanır.
Bağdaştırıcınızda yapılandırılan URL — bir istemci enjekte etmediğinizde kullanılır.
Yerleşik varsayılan — yalnızca yukarıdakilerin hiçbiri ayarlanmadığında kullanılır.

# Laravel (.env): use your own publicly-trusted TSA instead of the shipped default.
NEXTPDF_TSA_URL=http://timestamp.digicert.com

Zaman damgasını devre dışı bırakma

Bağdaştırıcınızın TSA url’sini varsayılanında (yapılandırılmamış) bırakmak, yerleşik varsayılan uç noktayı korur. O url’yi boş bir değere ayarlamak farklıdır: zaman damgalamayı devre dışı bırakır. Hiçbir TSA yapılandırılmadığında, B-T veya üzerinde istenen bir imza, sessizce B-B düzeyine düşmek yerine bir “TSA gerekli” hatasıyla hata durumunda kapalı kalır.

# Laravel (.env):
# NEXTPDF_TSA_URL unset -> use the built-in default (timestamp succeeds against pateon).
# NEXTPDF_TSA_URL empty -> no TSA; a B-T+ request fails closed.
NEXTPDF_TSA_URL=

messageImprint özet algoritmasını seçme

Bir RFC 3161 zaman damgası isteği bir messageImprint taşır — zaman damgalanan verinin bir özeti — ve NextPDF bu iz için varsayılan olarak SHA-256 kullanır. Varsayılan, bilinçli ve birlikte çalışabilir bir tercihtir; onu değiştirmeniz nadiren gerekir.

Bir TsaClient’ı elle oluşturduğunuzda, imprintHashAlgorithm yapıcı parametresi aracılığıyla farklı bir iz özeti seçebilirsiniz; bu parametre bir TsaImprintHashAlgorithm durumu alır: Sha256 (varsayılan), Sha384, Sha512, Sha3_256, Sha3_384 veya Sha3_512. Varsayılan, yayımlanan her isteği önceki sürümlerle bayt bakımından aynı tutar; bu nedenle yükseltme, siz tercih etmedikçe hiçbir şeyi değiştirmez.

use NextPDF\Security\Timestamp\TsaClient;
use NextPDF\Security\Timestamp\TsaImprintHashAlgorithm;

// Default — SHA-256 imprint, unchanged from earlier releases:
$tsa = new TsaClient('https://timestamp.example.com/tsa');

// Opt in to a stronger imprint digest:
$tsa = new TsaClient(
    'https://timestamp.example.com/tsa',
    imprintHashAlgorithm: TsaImprintHashAlgorithm::Sha512,
);

Varsayılandan ayrılmadan önce bilinmesi gereken iki kısıt vardır:

Ekosistem desteği bugün SHA-256’dır. SHA-256 olmayan bir iz, Core belirteç doğrulayıcısıyla birlikte çalışır, ancak nextpdf-server PAdES B-T kanıt geçidi ve Premium doğrulama özet eşlemesi şu anda yalnızca SHA-256 izlerini tanır. Bu nedenle, farklı bir iz özetiyle oluşturulmuş bir imza zaman damgası, bu yüzeylerde henüz B-T kanıtlamaz. Zaman damgalarınızın her tüketicisinin, seçtiğiniz özeti kabul ettiği bilinmedikçe varsayılanı koruyun.
Önceden hesaplanmış özetler algoritmayla eşleşmelidir. getDocumentTimestamp(), önceden hesaplanmış bir belge özeti alır; o özetin uzunluğu, yapılandırılmış iz algoritmasıyla eşleşmediğinde, uyumsuz bir istek göndermek yerine, herhangi bir ağ çağrısından önce hata durumunda kapalı kalır.

Yükseltme yolları

Geliştirme veya iç kullanımın ötesindeki her şey için, varsayılanı iki daha güçlü seçenekten biriyle değiştirin.

Herkesçe güvenilen TSA

Bağdaştırıcınızın TSA url’sini, sertifikası ilgili taraflarınızın zaten güvendiği herkese açık bir köke zincirlenen bir TSA’ya yönlendirin — örneğin http://timestamp.digicert.com. Hiçbir özel kökün dağıtılması gerekmez. Üretim düzeyinde bir TSA, tipik olarak ETSI EN 319 421 §5 gibi bir zaman damgalama politikasına uygunluk beyan eder ve ETSI EN 319 422 §7’de tanımlanan RFC 3161 protokol profilini izler; bunu yalnızca herkese açık güvenden varsaymak yerine işletmecinin yayımlanmış politikasına karşı doğrulayın.

eIDAS-nitelikli TSA

Avrupa Birliği’nde nitelikli hukuki etki taşıması gereken zaman damgaları için, bir AB Güvenilir Listesinde yer alan nitelikli bir güven hizmeti sağlayıcısından (QTSP) nitelikli bir zaman damgalama hizmeti kullanın. Nitelikli bir elektronik zaman damgası, saptanamayan değişikliği makul ölçüde önleyecek şekilde zamanı veriye bağlar, Eş Güdümlü Evrensel Zaman’a (UTC) bağlı doğru bir zaman kaynağına dayanır ve QTSP’nin gelişmiş bir elektronik imzası veya gelişmiş bir elektronik mührü ya da eşdeğer bir yöntemle korunur (Regulation (EU) 910/2014, Art 42). Bu en güçlü seçenektir ve bir düzenleme nitelikli zaman damgalarını açıkça adlandırdığında seçilecek olandır.

Çerçeve başına yapılandırma

Varsayılan, çekirdek motorda değil, her çerçeve bağdaştırıcısının yapılandırmasında yer alır. Core asla bir URL uydurmaz: elle oluşturduğunuz bir TsaClient açık bir uç nokta gerektirir ve boşsa bir istisna fırlatır. Uzun vadeli düzeyler (B-LT ve B-LTA), B-T ile aynı yapılandırılmış TSA’yı yeniden kullanır.

Tümleştirme	Varsayılanın yeri	Nasıl geçersiz kılınır
Laravel	`config/nextpdf.php` -> `tsa.url`	`.env` içinde `NEXTPDF_TSA_URL` ayarlayın
Symfony	bundle yapılandırması `nextpdf.tsa.url`	düğümü ayarlayın veya bir ortam değişkenine bağlayın
CodeIgniter	`Config\NextPdf::$tsa['url']`	`nextPdf.tsa.url` ortam anahtarıyla geçersiz kılın
Plain core	örtük varsayılan yok	açık bir URL ve sağlamlaştırılmış bir PSR-18 istemcisiyle bir `TsaClient` oluşturun

Her bağdaştırıcıda B-B asla bir TSA istemcisi oluşturmaz; bu nedenle zaman damgasız bir imza, bu yapılandırmanın hiçbirinden etkilenmez.

Güven modeli ve standartlar

Bir zaman damgasının değeri, baytların kendisi değil, ardındaki güven zinciridir. RFC 3161 belirteci yalnızca bir zaman ileri sürer; o ileri sürmenin inanılır olup olmadığı, onu imzalayan TSA’nın bir özelliğidir (RFC 3161 §2; ISO/IEC 18014-2 §7.3). Birlikte gelen varsayılanı koruduğunuzda, öz barındırmalı, özel güvenli bir çıpa seçiyorsunuz — her ilgili tarafın PATEON kökünü kurabildiği geliştirme ve iç iş akışları için uygun, ancak üçüncü taraflarca doğrulanan belgeler için uygun değil. Bunlar için herkesçe güvenilen bir TSA’ya, ya da nitelikli hukuki etki gerektiğinde eIDAS-nitelikli bir TSA’ya geçin.

Varsayılanı kendiniz işletiyorsanız, TSA’nın açık anahtarını kendi enjekte ettiğiniz PSR-18 istemcinizde sabitleyebilirsiniz. Birlikte gelen varsayılanı paylaşılan kodda sabitlemeyin: işletmeci tarafındaki bir anahtar dönüşü, o zaman tüm varsayılan kullanıcıları aynı anda bozar. Bir zaman damgasındaki güven, bir aktarım sabitlemesi değil, sertifika zinciri ve PATEON köküdür.