Teknik Makale

PDFium: HSM ve Bulut Anahtarlarıyla Uzaktan PAdES İmzalama

Dosyada 16.384 baytlık bir PAdES imza yer tutucusu, açı parantezleri arasında 32.768 ASCII sıfır olarak görünür ve o dizinin dışındaki PDF'nin her baytı, imzalayıcının onaylayacağı özet tarafından zaten kapsanır. Dokunamadığınız bir anahtarla imzalamanın sancılı yeri burasıdır: belge, CMS var olmadan önce son düzenine bağlanmak zorundadır; sonra bekler, kimi zaman saatlerce, bir ağ HSM'si ya da bulut imzalama hizmeti bir insanın telefonda onaylamasını isterken. O bekleme sırasında dosyaya olan her şey, imzanın doğrulanıp doğrulanmayacağına karar verir

Uzak bir anahtar neden SignPadesBytes kullanamaz?

Sıradan çağrı, özel anahtarın çağrının içinde erişilebilir olduğunu varsayar. PDFium Component'teki SignPadesBytes, artımlı güncellemeyi kurar, ByteRange'i özetler, Windows deposunda CertificateThumbprint ile adlandırılan sertifikayla imzalar ve bitmiş dosyayı yazdıktan sonra döner. Yerel depodaki bir anahtar için tam istediğiniz biçim budur

Bir güven hizmeti sağlayıcısının işlettiği nitelikli imza oluşturma aygıtı böyle çalışmaz. İkinci faktör adımı olan bir bulut imzalama API'si de, bir kuyruğun ardında duran bir HSM de öyle. Exchange bir sohbettir: siz bir özet gönderirsiniz, sürecinizin dışında bir şey bir insanın kimliğini doğrular ve CMS daha sonra başka bir iş parçacığında, başka bir istek işleyicisinde, belki başka bir sunucuda gelir. Eşzamanlı bir çağrı bunu yalnızca birinin telefonunda bir iş parçacığını bloke ederek modelleyebilir

Bu yüzden uzak yol iki çağrıya bölünür. PreparePadesRemoteSignature hazırlanmış PDF'i ve küçük bir istek kaydı üretir. CompletePadesRemoteSignature hazırlanmış PDF'i, kaydı ve dönen DER CMS'yi alır ve imzalı dosyayı yazar. İki çağrıyı aynı sürece bağlayan hiçbir şey yoktur

Belgeyi PreparePadesRemoteSignature ile hazırlamak

PreparePadesRemoteSignature kaynak PDF'i okur, ilk sayfada görünmez bir imza aracıyla artımlı bir güncelleme ekler ve /Filter /Adobe.PPKLite ile /SubFilter /ETSI.CAdES.detached taşıyan bir imza sözlüğü yazar. /Contents girdisi sabit genişlikte sıfırlarla doldurulur, dört ByteRange sayısı çevresine yamalanır ve o iki aralık üzerindeki SHA-256, Request.DocumentDigest olur. Kaynak dosyanın özgün baytlarına dokunulmaz; güncelleme yalnızca ekler

Çıktı kaydı olan TPadesRemoteSigningRequest altı alan taşır: FormatVersion, PreparedFingerprint (hazırlanmış dosyanın bütününün SHA-256'sı), DocumentDigest, dört elemanlı ByteRange, ContentsHexOffset (on altılık basamakların başladığı yer) ve ContentsSize. İmzalama hizmetine yalnızca özet gider. Gerisi, ikinci çağrının, özetin geldiği baytların aynısını tamamladığını kanıtlayabilmesi içindir

Üç seçenek kuralı hazırlanan dosyayı, dördüncüsü derlemenizi etkiler. CommitmentTypeOid atandığında sözlük /Reason taşımaz, çünkü ETSI EN 319 142-1, CMS'deki taahhüt türü ile PDF nedenini alternatifler olarak görür; imzalama hizmeti o zaman taahhüt-tür-göstergesini CMS'nin imzalı özniteliklerine yazmak zorundadır. SigningTimeUtc /M girdisi olur. Şifreli kaynaklar tamamen reddedilir, önce çözün. Uzak işlevler Enterprise sürümüne aittir: FPdfPadesRemote birimi bağlanmalıdır, aksi hâlde FPdfPades'teki giriş noktaları EPdfEnterpriseRequired fırlatır

Delphi'de iki aşamalı PDFium uzak PAdES akışı: PreparePadesRemoteSignature CMS yuvasını rezerve eder ve belge özetini bir HSM'ye veya bulut hizmetine uzatır; CompletePadesRemoteSignature ise döndürülen CMS'yi daha sonra herhangi bir süreçte veya makinede gömer
Birinci aşama CMS yuvasını rezerve eder ve belge özetini devreder; ikinci aşama, HSM'den ya da bulut anahtarından dönen CMS'yi gömer
uses
  System.SysUtils, System.Classes, System.DateUtils,
  FPdfCrypto, FPdfPades,
  FPdfPadesRemote;   // Enterprise gerçeklemesini bağlar

var
  Options: TPadesRemoteSignOptions;
  Request: TPadesRemoteSigningRequest;
  Source, Prepared, Session: TFileStream;
begin
  Options := TPadesRemoteSignOptions.Default;   // ContentsSize = 16384
  Options.Reason := 'Approved by finance';
  Options.Location := 'Lisbon';
  Options.Name := 'A. Moreira';
  Options.SigningTimeUtc := TTimeZone.Local.ToUniversalTime(Now);

  Source := TFileStream.Create('contract.pdf', fmOpenRead or fmShareDenyWrite);
  Prepared := TFileStream.Create('contract.prepared.pdf', fmCreate);
  try
    PreparePadesRemoteSignature(Source, Prepared, Options, Request);
  finally
    Prepared.Free;
    Source.Free;
  end;

  Session := TFileStream.Create('contract.signreq', fmCreate);
  try
    SavePadesRemoteSigningRequest(Session, Request);
  finally
    Session.Free;
  end;

  // Kendi kodunuz: 32 baytlık özeti HSM'ye ya da imzalama API'sine uzatın
  SendDigestToSigningService(Request.DocumentDigest);
end;

Belge zaten bir TPdf bileşeninde açıksa TPdf.PreparePadesRemoteSignature(Prepared, Options, Request) geçerli durumu kaydeder ve ondan hazırlar; etkin belge yokken False döndürür. Tamamlama ve oturum yardımcıları da TPdf üzerinde sınıf yöntemleridir, dolayısıyla ikinci aşamanın yüklü bir belgeye hiç ihtiyacı olmaz

İmzalama hizmetinin geri göndermesi gereken şey

DocumentDigest'teki 32 bayt, CMS'nin ileti-özeti imzalı özniteliğinde taşıması gereken değerdir. Bunlar genellikle özel anahtarın imzaladığı baytlar değildir. RFC 5652 §5.4 der ki, imzalı öznitelikler varken imza, öznitelik kümesinin DER kodlaması üzerinden hesaplanır; dolayısıyla eksiksiz bir CMS döndüren bir hizmet o adımı kendisi yapar, yalnızca özetleri imzalayan çıplak bir HSM ise bunu size bırakır. İkinci durumda kodunuz SignedAttributes'ı kurar (content-type, message-digest, signing-certificate-v2), bunları üyeleri sıralı bir SET OF olarak DER kodlar, onu özetler ve HSM'den özeti imzalamasını ister. Sıralama düzenini yanlış almak, iyi görünüp kriptografik doğrulamada başarısız olan bir CMS verir; CMS imzalı özniteliklerinde DER SET OF sıralaması yazısı o tuzağı adım adım gezdirir

CMS'yi kim kurarsa kursun, tamamlama tek bir belirli biçimi kabul eder: tam olarak bir SignerInfo taşıyan, detached (sarmalanmış içerik yok), content-type ve message-digest imzalı öznitelikleri olan, MD5 ya da SHA-1 dışında bir özet algoritması kullanan ve geçerli bir signing-certificate-v2 özniteliği taşıyan bir SignedData. Bunlar, ETSI EN 319 142-1 altında PAdES baseline imzalarının istedikleriyle eşleşir; dolayısıyla hâlihazırda PAdES uyumlu CAdES çıktısı üreten bir hizmet ek iş olmadan oturur

CompletePadesRemoteSignature neyi reddeder?

CompletePadesRemoteSignature, hedef akışa tek bir bayt yazmadan önce her denetimi çalıştırır ve her reddediş, başarısız denetimi adlandıran bir iletle EPadesCrypto fırlatır. Önce istek kaydının kendisi denetlenir: biçim sürümü 1, 32 baytlık parmak izi ve özet, 1024 bayt ile 64 MiB arasında bir ContentsSize, pozitif bir hex ofseti. Sonra hazırlanmış dosya:

  1. kaydedilen ofsetler dosyanın içinde bulunmalı ve ByteRange, yer tutucuyla ve dosya uzunluğuyla tam olarak hizalanmalı
  2. /Contents çevresindeki < ve > hâlâ yerinde olmalı ve aralarındaki her hex basamağı hâlâ 0 olmalı
  3. dosyanın bütününün SHA-256'sı PreparedFingerprint'e eşit olmalı ve ByteRange özeti DocumentDigest'e eşit olmalı

Sonra CMS: artık bayt taşımayan, ContentsSize'dan uzun olmayan, desteklenen SignedData biçiminde olan, signing-certificate-v2 bulunduran tek bir tam DER değeri olmalı ve nihayet ileti-özeti özniteliği DocumentDigest'e eşit olmalı

Aşamalar arasında yeniden üretilen hazırlanmış dosya, bir görüntüleyicide aynı görünse bile parmak izini değiştirir. Yer tutucu üzerindeki tam-sıfır testi, çifte tamamlamayı yakalar; bir yeniden deneme, zaten imza duran bir yerin üstüne ikinci bir CMS yazar. İleti-özeti karşılaştırması en sinsi durumu yakalar: kendi sertifikanızdan, kuyruk iki eşzamanlı oturumu karıştırdığı için farklı bir belge üzerinden imzalanmış, doğru kurulmuş bir CMS. O dosya gayet iyi açılır ve başka bir sözleşme için tasarlanmış bir onay taşır

Signing-certificate-v2 denetimi, bütünlükten çok uyumluluk içindir. Onu taşımayan bir CMS kriptografik olarak doğrulanabilir ve yine de bir PAdES doğrulayıcısında başarısız olabilir; onu tamamlamada reddetmek o keşfi, müşterinin doğrulama raporundan kendi günlüklerinize taşır. Doğrulayıcılar PAdES imzalarını neden reddeder yazısı doğrulayıcıların aradığı diğer öznitelikleri kapsar

Delphi'de PDFium uzak PAdES imzalaması için tamamlanma kapısı şeması: CompletePadesRemoteSignature dosya bütünlüğünü, CMS biçimini ve PAdES uyumluluğunu kontrol eder ve her kontrol geçtiğinde imzalı PDF'yi yazar
CompletePadesRemoteSignature, tek bir bayt yazılmadan önce bütünlüğü, CMS biçimini ve PAdES uygunluğunu doğrular
var
  Request: TPadesRemoteSigningRequest;
  Session, Prepared, Dest: TFileStream;
  CmsDer: TBytes;
begin
  Session := TFileStream.Create('contract.signreq', fmOpenRead);
  try
    Request := LoadPadesRemoteSigningRequest(Session);
  finally
    Session.Free;
  end;

  CmsDer := FetchDetachedCmsFromService;   // kendi kodunuz: DER baytları, Base64 değil

  Prepared := TFileStream.Create('contract.prepared.pdf', fmOpenRead);
  try
    Dest := TFileStream.Create('contract.signed.pdf', fmCreate);
    try
      try
        CompletePadesRemoteSignature(Prepared, Dest, Request, CmsDer);
      except
        on E: EPadesCrypto do
          FailSession(E.Message);   // kendi kodunuz: iletiyi harfiyen saklayın
      end;
    finally
      Dest.Free;
    end;
  finally
    Prepared.Free;
  end;
end;

Çok sayıda imzalama API'si CMS'yi JSON içinde Base64 olarak döndürür, kimi zaman çevresinde PEM başlıklarıyla. Yalnızca çözülmüş DER'i geçirin. Sondaki bir satır sonu ya da arta kalan bir başlık baytı, tek-tam-DER-değeri denetimini düşürür; bu amaçlanan sonuçtur: alternatif, ardında çöple ayrıştırılan bir CMS'tir

Süreçler ve makineler arasında oturum dosyaları

SavePadesRemoteSigningRequest sabit 120 baytlık bir ikili kayıt yazar: 8 baytlık bir PDRSIG01 büyüsü, biçim sürümü, hex ofseti, ContentsSize, dört ByteRange değeri, sonra özet ve parmak izi. LoadPadesRemoteSigningRequest, yanlış boyutlu, yanlış büyülü, artık verili ya da 1 dışında bir biçim sürümlü her şeyi reddeder. Kayıt anahtar malzemesi ve belge içeriği taşımaz; dolayısıyla hazırlanmış PDF'in yanında bir veritabanı satırında ya da nesne deposunda saklamak sorun değildir

Bu, web uygulaması durumunu basit kılar. Bir istek işleyicisi dosyayı hazırlar ve iki artefaktı da saklar; tarayıcı ya da bir telefon uygulaması özeti onaylar ve başka bir düğümdeki bir geri çağırım işleyicisi oturumu yükleyip tamamlar. Kısıt hazırlanmış PDF üzerindedir: bayt bayt geri gelmek zorundadır. Onu bir PDF kitaplığından yeniden kaydetmek, bir iyileştiriciden geçirmek ya da aktarım katmanının satır sonlarına dokunmasına izin vermek — hepsi parmak izini değiştirir

Ölçümlü bir nitelikli imza hizmeti işlem başına ücret alır; dolayısıyla hiç imza istemeden önce saklanan dosyayı denetlemek kârlıdır. Aşağıdaki taslak, dosya özetini Delphi RTL'sinin System.Hash'i ile PreparedFingerprint ile karşılaştırır; kendinizin ekleyeceği bir denetimdir ve tamamlama zaten tekrarlar

uses
  System.SysUtils, System.Classes, System.Hash,
  FPdfPades, FPdfPadesRemote;

// Kendinizin ekleyeceği önerilen ön uçuş denetimi; bileşenin parçası değil
function PreparedFileStillMatches(const PreparedPath: string;
  const Request: TPadesRemoteSigningRequest): Boolean;
var
  S: TFileStream;
  H: TBytes;
begin
  S := TFileStream.Create(PreparedPath, fmOpenRead or fmShareDenyWrite);
  try
    // GetHashBytes'ın TStream overloadu yakın bir Delphi System.Hash ister;
    // Lazarus'ta System.Hash yoktur, orada kendi SHA-256 yordamınızı çağırın
    H := THashSHA2.GetHashBytes(S);   // varsayılan olarak SHA-256
  finally
    S.Free;
  end;
  Result := (Length(H) = Length(Request.PreparedFingerprint)) and
    CompareMem(@H[0], @Request.PreparedFingerprint[0], Length(H));
end;

CMS var olmadan önce ContentsSize'ı boyutlandırmak

ContentsSize DER CMS baytlarını sayar. Dosyadaki yer tutucu, bunun iki katı hex karakterdir; bu yüzden 16384 varsayılanı, açılış paragrafındaki 32.768 sıfırı üretir. 1024'ün altındaki değerler 1024'e yükseltilir, 64 MiB üzerindeki bir değer hazırlama anında reddedilir ve tamamlama, ContentsSize bayttan uzun her CMS'yi reddeder

Çok küçük olmak pahalı hatadır: hizmet zaten imzalamıştır, işlem harcanmıştır ve ileriye tek yol, daha geniş bir yuva ile yeniden hazırlayıp yeniden imzalamaktır. Çok büyük olmak yalnızca her imzalı dosyada dolgu maliyetidir. Geniş tarafta kalın. Diyelim ki hizmetiniz, üç sertifikalı bir zincirle kabaca 7.000 baytlık bir CMS döndürüyor; varsayılan, yuvanın yarısından fazlasını hâlâ boş bırakır. Hizmet ayrıca bir imza zaman damgası jetonu ya da iptal verisini imzasız öznitelikler olarak gömerse, bunlar aynı CMS'nin içine düşer ve aynı sınıra sayılır; o yüzden üretim zincirinizden bir gerçek yanıt ölçün ve oradan boyutlandırın, ileride daha uzun bir ara sertifika zinciri için pay bırakarak

Tamamlamadan sonra: B-B, sonra LTV ve doğrulama

Tamamlanmış bir uzak imza PAdES B-B'dir. Uzun vadeli doğrulama, daha sonraki bir artımlı güncellemede bir belge zaman damgası ve bir DSS ile her imza için VRI sözlükleri olarak doğrulama malzemesi ekler; RFC 3161 zaman damgaları ve DSS ile uzun vadeli imzalar yazısında anlatılır. O adım yerel çalışır, çünkü sertifikaların, OCSP yanıtlarının ve CRL'lerin özel anahtara ihtiyacı yoktur

Çıktıyı, ilgili bir tarafın izleyeceği yolun aynısıyla doğrulayın; dijital imzaları ve PAdES düzeylerini inceleme yazısı bunu kapsar. Uzak bir hattı CMS'yi kuran kod, bir başkasının sunucusunda yaşar ve onun çıktısının gerçek bir doğrulayıcıyla ilk karşılaşacağı yer, müşterilerinizin önünde kendi derlemeniz olmalıdır

Uzak imzalama çağrıları, Delphi ve Lazarus için PDFium Component'in Enterprise sürümüyle gelir; yerel Pascal PAdES imzalama, zaman damgalama ve doğrulama kodunun yanı sıra. API başvurusu ve deneme indirmeleri PDFium Component ürün sayfasında bulunur