HSM destekli imzalama

Spec: ISO 32000-2, §12.8 Spec: FIPS 140-3 Evidence: Standard-backed

Bir bakışta

Bir donanım güvenlik modülü (HSM), imzalama anahtarını sürecinizin dışına, istek üzerine imzalayan ancak anahtarı asla geri vermeyen bir cihazın arkasına taşır. Bu sayfa, NextPDF’in imzalamak için kullandığı PKCS#11 bağlantı noktasını, anahtar sınırının tam olarak nereden geçtiğini ve sonucun hangi bölümlerinin cihazın ya da sizin değil, motorun sorumluluğunda olduğunu açıklar.

Bunun neden önemli olduğu

Süreç belleğinde duran bir imzalama anahtarı, süreci okuyabilen her şeye açıktır: bir bellek dökümü, bir hata ayıklayıcı, bir günlükleme hatası ya da güvenlik açığı içeren bir bağımlılık. Bir özel anahtar bir kez kopyalandığında, onunla atılmış her imza şüpheli hale gelir ve onu yeniden gizli kılamazsınız. Bir HSM’in amacı, alınabilecek bir kopya bırakmamaktır.

Sınırı yanlış çizmek sessizce pahalıya mal olur. Donanım destekli görünen ancak imzalamak için anahtarı belleğe çeken bir iş akışı, bir HSM’in operasyonel maliyetine ve bir yazılım anahtarının risk profiline sahip olur. Bu ayrım, tamamlanmış PDF’te görünmez; bu nedenle varsayılmak yerine en baştan tasarlanmalı ve doğrulanmalıdır.

Kısa sürümü

İlgili PKCS#11 standardı, hassas ve çıkarılamaz olarak işaretlenmiş bir anahtar nesnesi tanımlar. Bu nesnenin özel değeri belirtecin dışında düz metin olarak açığa çıkarılamaz. Spec: PKCS#11, v3.1 §10.9
NextPDF, PDF imzası yapısını ve CMS kapsayıcısını oluşturur. İmzalanacak baytları PKCS#11 bağlantı noktası üzerinden aktarır ve imzayı geri alır. Anahtar bu bağlantı noktasını asla geçmez.
Bağlantı noktası kararlı bir sözleşmedir. Aynı sözleşme bir akıllı kart belirteci, bir USB HSM, bir ağ HSM’i ve bir bulut KMS tarafından karşılanır. Motor kodu bunlar arasında değişmez.
NextPDF bir imzalama motoru yazılımıdır. Cihazın donanım güvencesi, doğrulama durumu, PIN politikası ve dağıtımı motorun belgelendirdiği unsurlar değildir. Cihazı kullanır; onun için kefil olmaz.

NextPDF buna nasıl yaklaşıyor

Bağlantı noktası, tam olarak

NextPDF, bir imzayı birleştirmeyi, imza değerini hesaplamaktan ayırır. Birleştirme motorun görevidir: imza alanını yerleştirmek, dosyada alan ayırmak, bayt aralığını hesaplamak ve CMS SignedData nesnesini imzalı öznitelikleriyle birlikte oluşturmak. Spec: ISO 32000-2, §12.8

İmza değerini hesaplamak ise devredilir. Motor, küçük bir imzalama sağlayıcı sözleşmesi tanımlar: opak bir bayt dizisi (pratikte DER kodlamalı imzalı öznitelikler) alır ve ham imza sekizlilerini döndürür. Bu sözleşme, bağlantı noktasının kendisidir. PDF ve CMS bilgisi bir tarafta kalır; anahtar ise diğer tarafta. Bir sağlayıcı, yerel bir yazılım anahtarı için o anahtarı süreç içinde, bir bulut KMS’inde ya da PKCS#11 aracılığıyla bir donanım belirteci üzerinde tutabilir. Bağlantı noktasının üstündeki motor kodu her durumda aynıdır. Yalnızca arkasındaki sağlayıcı farklılık gösterir.

Sınırın gerçekte nerede olduğu

PKCS#11 — OASIS Kriptografik Belirteç Arayüzü, tarihsel olarak “Cryptoki” — donanım belirteçlerine yönelik standart C arayüzüdür. NextPDF’in donanım yolu PKCS#11 ile iletişim kurar (doğrudan ya da engine/provider dağıtımlarında süreç içi bağlamanın bir belirteci yükleyemediği durumlar için bir OpenSSL komut satırı köprüsü aracılığıyla).

Belirteçteki anahtar nesnesi, sınırı tanımlayan iki öznitelikle oluşturulur. Anahtar hassas olarak ya da çıkarılamaz olarak işaretlendiğinde, belirli özel öznitelikler belirtecin dışında düz metin olarak açığa çıkarılamaz. Spec: PKCS#11, v3.1 §10.9 İmzalama işleminin kendisi, cihaz tarafından gerçekleştirilen belirteç işlemidir — C_SignInit ve ardından C_Sign. Spec: PKCS#11, v3.1 §5.10 NextPDF’in imzalama işlemi için ele aldığı düz metin, imzalanacak baytlardır. Dönen değer ise imza ve sertifikadır. Özel anahtar bu akışların hiçbirinde yer almaz. İşte sınır budur ve onu kütüphane değil, belirteç uygular.

Step 1 of 4: ISO 32000-2 §12.8 — signature dictionary, ByteRange, Contents
Step 2 of 4: RFC 5652 CMS SignedData — the signature container
Step 4 of 4: FIPS 140-3 / ISO/IEC 19790 cryptographic module assurance (device-level, deployment-dependent)

Donanım destekli bir PDF imzasının sırasıyla nerelere dayandığı: PDF taşıyıcısı (ISO 32000-2 §12.8), onun taşıdığı CMS kapsayıcısı, NextPDF'in aracılığıyla imzaladığı belirteç arayüzü (PKCS#11) ve arkasındaki cihazı tanımlayan — ancak tek başlarına güvence vermeyen — modül güvence standartları.

Tek PIN, tek yeniden kimlik doğrulama

PKCS#11, bir anahtarın her kullanımda yeniden kimlik doğrulaması gerektirmesine izin verir: CKA_ALWAYS_AUTHENTICATE özniteliği ayarlandığında, kullanıcı PIN’i oturum başına bir kez değil, her kriptografik işlem için yeniden sunmak zorundadır. Spec: PKCS#11, v3.1 §10.9 NextPDF’in PKCS#11 yolu bu durum için tasarlanmıştır. PIN hassas bir parametredir. Günlüğe yazılmaz veya serileştirilmez. Bir oturum mevcut bir oturum açma durumu bildirdiğinde, NextPDF bir sonraki imzanın yeni bir PIN denetiminden geçmesi için oturumu temiz bir duruma döndürür. Bu, politikası imza başına bir PIN gerektiren PIV tarzı belirteçler için önemlidir. Bu, cihazın politikasına saygı gösteren motor davranışıdır; onu gevşetmez.

Kanıtların söyledikleri

Evidence: Standard-backed Çıkarılamaz anahtar özelliği bir NextPDF iddiası değildir. Bu, PKCS#11 modelinin kendisidir: öyle bir anahtar nesnesi ki, CKA_SENSITIVE değeri doğru veya CKA_EXTRACTABLE değeri yanlış olduğunda, özel değerini belirtecin dışında düz metin olarak vermez. Spec: PKCS#11, v3.1 §10.9 NextPDF’in buradaki katkısı, o değere asla ihtiyaç duymamasıdır: anahtar malzemesi istemek yerine doğrudan belirtecin C_Sign işlemiyle imzalar.

Evidence: Standard-backed PDF tarafı şu standarda dayanır: Spec: ISO 32000-2, §12.8 . Bayt aralığı özeti, imza değeri hariç dosya üzerinden hesaplanır. İmza değeri, Contents girdisine yerleştirilmiş, DER kodlamalı bir CMS SignedData nesnesidir — açık anahtarlı imzalarda. HSM yalnızca en içteki imza sekizlilerini üretir. NextPDF bunların etrafındaki her şeyi oluşturur ve standardın tanımladığı yapıya yazar.

Evidence: Standard-backed Cihaz güvencesi şu standartla tanımlanır: Spec: FIPS 140-3 ve temel aldığı ISO/IEC 19790, on bir gereksinim alanı boyunca giderek artan dört niteliksel güvenlik düzeyi tanımlar — algoritma belirtiminden fiziksel kurcalama belirtisine kadar. Bu standartlar, bir modülün bir düzeyi iddia edebilmesi için neyi karşılaması gerektiğini tanımlar. Bunlar NextPDF’in değil, cihazın ve onun doğrulamasının bir özelliğidir ve — bizzat ISO/IEC 19790’nin ifadesiyle — uygunluk, belirli bir dağıtımda bir modülün güvenli olduğunu göstermek için tek başına yeterli değildir.

Pratik örnek

Aşağıdaki biçim açıklayıcıdır. Kopyala-yapıştır yapılacak bir dağıtımı değil, bağlantı noktasını gösterir. Önemli nokta, motora bir imzalayıcı verilmesi ve motorun anahtarı asla görmemesidir: imzalayıcının sign() işlevi cihaza yapılan bir çağrıdır.

<?php

declare(strict_types=1);

use NextPDF\Contracts\HsmSignerInterface;

/**
 * Sign a PDF where the private key lives on a PKCS#11 token.
 *
 * `$hsm` is a hardware-backed signer. Its sign() delegates to the token;
 * the key never enters this process. Everything that makes the bytes a
 * valid PDF signature — field, byte range, CMS SignedData — is built by
 * the engine around the value the device returns.
 *
 * Token wiring (library path, slot, PIN, key label) is deployment
 * configuration and is intentionally out of scope here: those values are
 * operator-owned secrets, not library inputs to hardcode.
 */
function signWithToken(
    string $pdfPath,
    HsmSignerInterface $hsm,
): string {
    // The engine asks the signer only for: the certificate (to embed in
    // the CMS) and a signature over the bytes it computes. It never asks
    // for, and the contract never exposes, the private key.
    $certificateDer = $hsm->getCertificateDer();
    $chainDer       = $hsm->getCertificateChainDer();

    // Pseudocode for the engine's own assembly step: build the signature
    // dictionary + CMS SignedData, then hand the signed-attributes bytes
    // to $hsm->sign(...) and place the returned octets in /Contents.
    return nextpdf_sign_pdf(
        pdfPath: $pdfPath,
        signer: $hsm,
        certificateDer: $certificateDer,
        chainDer: $chainDer,
    );
}

Bu biçime ilişkin iki açık not var. Süreç içi PKCS#11 bağlaması, standart PHP bileşenlerinin içermediği ayrı bir PHP uzantısıdır. Bir donanım dağıtımı bunu sonradan eklenmiş bir ayrıntı olarak değil, platformun bir parçası olarak kurar ve doğrular (ya da OpenSSL komut satırı köprüsünü kullanır). Ayrıca cihazdan istenen algoritma, anahtarın gerçekten gerçekleştirebileceği bir algoritma olmalıdır. Yapılandırılmış algoritmanın seçilen sağlayıcı için bir eşlemesi olmadığında, motor bir belirteç çağrısının derinliklerinde başarısız olmak yerine en baştan reddeder.

Yaygın yanlış kanı

“Bir HSM kullanmak, imzalamanın FIPS doğrulamalı olduğu anlamına gelir.”

Hayır. İkisini birbirine karıştırmak yanıltıcıdır. Bir HSM, anahtarın bulunduğu ve işlemin çalıştığı yerdir. FIPS 140-3 / ISO/IEC 19790 doğrulaması, cihazın (veya belirli bir modül yapılandırmasının) sahip olabileceği, bir doğrulama programı tarafından saptanan bir özelliktir — çağıran bir kütüphanenin verdiği bir şey değildir ve NextPDF’in bir cihaz adına ileri sürdüğü bir şey değildir. NextPDF, uyumlu biçimde bir PKCS#11 cihazı aracılığıyla imzalar ve imzalama yolu, kategoriyi temsil eden belirteçlerle test edilmiştir. Belirli bir dağıtımın FIPS modül düzeyinde doğrulamalı olup olmadığı tamamen donanıma, sertifikasına ve nasıl yapılandırılıp işletildiğine bağlıdır. Gerçekte sahip olduğunuz şey için doğru sözcüğü kullanın.

Sınırlar ve kapsam

Bu sayfa, bağlantı noktasını ve dayandığı standartları tanımlar. Bu bir dağıtım güvencesi değildir ve bu sınırı açıkça belirtmek gerekir:

Motorun sorumluluğu. İmza alanını oluşturmak, yer ayırmak, bayt aralığını hesaplamak, CMS SignedData nesnesini birleştirmek, imzalama sağlayıcısını çağırmak ve yapısal olarak doğru bir imza yazmak — şuna uygun olarak: Spec: ISO 32000-2, §12.8 . NextPDF’in donanım yolu, bu amaç için uyumlu biçimde PKCS#11 imzalama arayüzünü kullanır.
Cihazın ve operatörün sorumluluğu. Donanımın kurcalama direnci, FIPS 140-3 / ISO/IEC 19790 doğrulama durumu, anahtar üretimi ve muhafazası, PIN politikası, yuva yapılandırması, ürün yazılımı ve fiziksel güvenlik. Bunların hiçbiri motorun belgelendirdiği unsurlar değildir.
Test edilmiş olmak belgelendirilmiş olmak değildir. NextPDF’in, temsili belirteç kategorilerine karşı doğrulanmış bir yola sahip olması — aynı PKCS#11 sözleşmesi aracılığıyla ulaşılan akıllı kart, USB, ağ ve bulut KMS biçimleri — bir uyumluluk beyanıdır. Bu, bir belgelendirme, doğrulanmış modül listesi ya da belirli cihazınız hakkında bir iddia değildir. Aşağıdaki donanım kategorileri, tek bir standart arayüz aracılığıyla entegrasyon biçimleridir. Bunları “bağlantı noktasının nerede denendiği” olarak ele alın; kendiniz test etmediğiniz bir model için asla bir güvence olarak değil.
Kuantum sonrası imzalama deneyseldir. Motor bir belirteç aracılığıyla kuantum sonrası imzalama sunduğunda, bu isteğe bağlıdır, bir özellik kapısı arkasındadır ve gerçek kuantum sonrası HSM ürün yazılımı yerine sahte nesnelere karşı doğrulanmıştır. PAdES ve AdES kriptografik takım katalogları bu takımları uzun vadeli arşivleme için henüz tanımaz. Bunu üretime hazır olarak ele almayın.

HSM-backed signing via PKCS#11 — edition availability
Edition	Availability
Core	Bu sürümde yok. Core, imzalama motorunu ve imzalama sağlayıcı bağlantı noktasını, yerel bir yazılım anahtarı sağlayıcısıyla birlikte sağlar.
Pro	Bulut anahtar yönetimi — yönetilen KMS anahtarları aracılığıyla imzalama — yalnızca davranış düzeyinde açıklanan bir Pro yeteneğidir.
Enterprise	Mevcut. PKCS#11 arayüzü aracılığıyla donanım belirteci ile imzalama (ve engine/provider dağıtımları için bir OpenSSL komut satırı köprüsü) bir Enterprise yeteneğidir. Kullanılabilirlik bir yetenek beyanıdır; herhangi bir cihazın ya da dağıtımın belgelendirmesi değildir.

Tek bir arayüz aracılığıyla entegrasyon biçimleri

Bunlar biçimler olup PKCS#11 bağlantı noktası bunlara karşı denenmiştir. Sütun, “doğrulanmış, belgelendirilmiş ya da sayılmış cihaz listesi” değil, “entegrasyonun neye benzediğidir”.

Entegrasyon biçimi	Nasıl erişilir	Anahtar sınırı	Güvence neyin özelliğidir
Akıllı kart / PIV belirteci	PKCS#11 modülü; kullanım başına PIN yaygındır	Kart üzerinde; çıkarılamaz	Kart ve operatörü
USB HSM	PKCS#11 modülü	Cihaz üzerinde; çıkarılamaz	Cihaz ve operatörü
Ağ / aygıt HSM’i	PKCS#11 modülü; ağ aygıtı üzerinden	Aygıt üzerinde; çıkarılamaz	Aygıt, yapılandırması, operatör
Bulut KMS	Yönetilen anahtar sağlayıcısı (Pro)	Bulut hizmetinde; asla döndürülmez	Bulut sağlayıcısı ve onun beyanları
OpenSSL sağlayıcı köprüsü	PKCS#11, bir OpenSSL köprüsü aracılığıyla	Belirteç üzerinde; çıkarılamaz	Belirteç ve operatörü

Mini SSS

Anahtar PHP sürecine hiç girer mi? Hayır. Çıkarılamaz bir PKCS#11 anahtarı için özel değer, belirtecin dışında düz metin olarak açığa çıkarılamaz. NextPDF, belirteç işlemiyle imzalar ve yalnızca imzalanacak baytları ve döndürülen imzayı görür.

HSM destekli bir imza PDF’in içinde farklı mıdır? Hayır. İmza yapısı aynıdır: aynı bayt aralığı üzerinde yer alan aynı CMS SignedData, aynı Contents girdisinde. HSM, imzalamanın nerede gerçekleştiğini değiştirir, diskteki biçimi değil.

Bir HSM’i NextPDF aracılığıyla kullandığım için FIPS uyumluluğu iddia edebilir miyim? Ancak dikkatle. NextPDF, bir cihazın FIPS durumu hakkında hiçbir şey ileri sürmez. Böyle bir iddia, NextPDF’in cihazı çağırmış olmasından değil, cihazın kendi doğrulamasından ve nasıl dağıtıldığından gelmelidir.

Süreç içi PKCS#11 bağlaması kullanılamıyorsa ne olur? Motor, sessizce bir yazılım anahtarına geri dönmek yerine donanım imzalamanın kullanılamadığını bildirir. Süreç içi bağlamanın bir belirteci yükleyemediği dağıtımlar için bir OpenSSL komut satırı köprüsü yolu mevcuttur.

İlgili belgeler

Nitelikli imzalar, açıklandı — bir donanım anahtarının hangi durumlarda gerekli olsa da yeterli olmadığı ve NextPDF’in üstlenmediği roller.
İmzaların bir PDF’in içinde nasıl yer aldığı — HSM sonucunun yazıldığı bayt aralığı ve imza sözlüğü mekanizması.
NextPDF’i üretimde işletmek — bir donanım imzalama dağıtımının beraberinde getirdiği operasyonel yüzey.

Sözlük

HSM (donanım güvenlik modülü) — anahtarları tutan ve kriptografik işlemleri gerçekleştiren, böylece anahtar malzemesinin cihazı asla terk etmediği sertleştirilmiş bir cihaz.
PKCS#11 — OASIS Kriptografik Belirteç Arayüzü standardı (tarihsel olarak “Cryptoki”); NextPDF’in donanım belirteçleriyle konuşmak için kullandığı C arayüzü.
Çıkarılamaz anahtar — özel değeri belirtecin dışında düz metin olarak açığa çıkarılamayan bir PKCS#11 anahtar nesnesi (CKA_SENSITIVE doğru veya CKA_EXTRACTABLE yanlış).
Bağlantı noktası — NextPDF’teki imzalama sağlayıcı sınırı: içeri opak baytlar, dışarı imza sekizlileri. PDF ve CMS bilgisi onun üstünde yer alır; anahtar ise arkasında kalır.
CMS SignedData — imzayı ve sertifikaları PDF’in içinde taşıyan Kriptografik Mesaj Sözdizimi yapısı (RFC 5652).
FIPS 140-3 / ISO/IEC 19790 — dört niteliksel düzey tanımlayan kriptografik modül güvenlik standartları; çağıran bir kütüphanenin değil, bir cihazın ve onun doğrulamasının bir özelliği.