Artykuł techniczny

PDFium VCL: zdalne podpisywanie PAdES kluczami HSM

Symbolem zastępczym podpisu PAdES o rozmiarze 16 384 bajtów jest w pliku 32 768 zer ASCII między nawiasami kątowymi i każdy bajt PDF poza tym ciągiem jest już objęty skrótem, który podpisujący zaakceptuje. Właśnie to jest niewygodne w podpisywaniu kluczem, którego nie możesz dotknąć: dokument musi zobowiązać się do swojego ostatecznego układu, zanim CMS w ogóle powstanie, a potem czekać — czasem godzinami — podczas gdy sieciowy HSM albo chmurowa usługa podpisująca proszą człowieka o potwierdzenie na telefonie. To, co spotka plik w trakcie tego oczekiwania, rozstrzyga, czy podpis się zweryfikuje

Dlaczego klucz zdalny nie może użyć SignPadesBytes?

Zwykłe wywołanie zakłada, że klucz prywatny jest osiągalny wewnątrz wywołania. SignPadesBytes w PDFium Component buduje aktualizację przyrostową, liczy skrót nad ByteRange, podpisuje certyfikatem wskazanym przez CertificateThumbprint w magazynie Windows i zapisuje gotowy plik, zanim wróci. Dla klucza z lokalnego magazynu to dokładnie kształt, jakiego chcesz

Kwalifikowane urządzenie do składania podpisu prowadzone przez dostawcę usług zaufania nie działa w ten sposób. Ani chmurowe API podpisujące z krokiem drugiego składnika, ani HSM schowane za kolejką. Wymiana jest rozmową: wysyłasz skrót, coś poza Twoim procesem uwierzytelnia człowieka, a CMS przychodzi później, na innym wątku, w innym handlerze żądań, może na innym serwerze. Wywołanie synchroniczne potrafi to wymodelować tylko blokując wątek czyjegoś telefonu

Droga zdalna dzieli się więc na dwa wywołania. PreparePadesRemoteSignature produkuje przygotowany PDF i mały rekord żądania. CompletePadesRemoteSignature bierze przygotowany PDF, rekord i zwrócony DER CMS i zapisuje podpisany plik. Nic nie wiąże tych dwóch wywołań z tym samym procesem

Przygotowanie dokumentu przez PreparePadesRemoteSignature

PreparePadesRemoteSignature czyta źródłowy PDF, dopisuje aktualizację przyrostową z niewidocznym widgetem podpisu na pierwszej stronie i zapisuje słownik podpisu z /Filter /Adobe.PPKLite i /SubFilter /ETSI.CAdES.detached. Wpis /Contents jest wypełniany zerami o stałej szerokości, cztery liczby ByteRange są wtapiane wokół niego, a SHA-256 nad tymi dwoma zakresami staje się Request.DocumentDigest. Oryginalne bajty pliku źródłowego zostają nietknięte; aktualizacja tylko dopisuje

Rekord wyjściowy, TPadesRemoteSigningRequest, ma sześć pól: FormatVersion, PreparedFingerprint (SHA-256 całego przygotowanego pliku), DocumentDigest, czteroelementowy ByteRange, ContentsHexOffset (gdzie startują cyfry szesnastkowe) i ContentsSize. Do usługi podpisującej jedzie tylko skrót. Reszta istnieje po to, żeby drugie wywołanie mogło udowodnić, że dokańcza dokładnie te bajty, z których przyszedł skrót

Trzy reguły opcji wpływają na przygotowany plik, a czwarta na Twoją kompilację. Gdy CommitmentTypeOid jest ustawiony, słownik nie niesie /Reason, bo ETSI EN 319 142-1 traktuje typ zobowiązania w CMS i powód w PDF jako alternatywy; usługa podpisująca musi wtedy zapisać commitment-type-indication w podpisanych atrybutach CMS. SigningTimeUtc staje się wpisem /M. Zaszyfrowane źródła są odrzucane od razu, więc najpierw odszyfruj. Funkcje zdalne należą do edycji Enterprise: moduł FPdfPadesRemote musi być dolinkowany, inaczej punkty wejścia w FPdfPades rzucają EPdfEnterpriseRequired

Dwufazowy przepływ zdalnego PAdES w PDFium dla Delphi: PreparePadesRemoteSignature rezerwuje slot CMS i przekazuje skrót dokumentu do HSM lub usługi chmurowej, a CompletePadesRemoteSignature osadza zwrócony CMS później w dowolnym procesie lub na dowolnej maszynie
Faza pierwsza rezerwuje slot CMS i przekazuje skrót dokumentu; faza druga osadza CMS, który wraca z HSM lub klucza w chmurze
uses
  System.SysUtils, System.Classes, System.DateUtils,
  FPdfCrypto, FPdfPades,
  FPdfPadesRemote;   // dolinkowuje implementację Enterprise

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;

  // Twój własny kod: przekaż 32-bajtowy skrót do HSM albo API podpisującego
  SendDigestToSigningService(Request.DocumentDigest);
end;

Jeśli dokument jest już otwarty w komponencie TPdf, TPdf.PreparePadesRemoteSignature(Prepared, Options, Request) zapisuje bieżący stan i przygotowuje od niego, zwracając False, gdy żaden dokument nie jest aktywny. Dokończenie i pomocniki sesji są też metodami klasy na TPdf, więc druga faza w ogóle nie potrzebuje wczytanego dokumentu

Co usługa podpisująca musi odesłać

32 bajty w DocumentDigest to wartość, którą CMS musi nieść w swoim podpisanym atrybucie message-digest. Zwykle nie są to bajty, które klucz prywatny podpisuje. RFC 5652 §5.4 mówi, że gdy podpisane atrybuty są obecne, podpis liczy się nad kodowaniem DER zestawu atrybutów, więc usługa zwracająca kompletny CMS robi ten krok sama, podczas gdy goły HSM podpisujący wyłącznie skróty zostawia go Tobie. W drugim przypadku Twój kod buduje SignedAttributes (content-type, message-digest, signing-certificate-v2), koduje je jako SET OF z posortowanymi składowymi, liczy od tego skrót i prosi HSM o podpisanie tego skrótu. Zła kolejność sortowania daje CMS, który wygląda dobrze i wali się na weryfikacji kryptograficznej; sortowanie DER SET OF w podpisanych atrybutach CMS przechodzi przez tę pułapkę krok po kroku

Ktokolwiek składa CMS, dokończenie przyjmuje jeden konkretny kształt: SignedData z dokładnie jednym SignerInfo, odłączony (bez opakowanej treści), z podpisanymi atrybutami content-type i message-digest, algorytmem skrótu innym niż MD5 albo SHA-1 i ważnym atrybutem signing-certificate-v2. To pokrywa się z wymogami podpisów baseline PAdES pod ETSI EN 319 142-1, więc usługa, która już produkuje wyjście CAdES zgodne z PAdES, pasuje bez dodatkowej pracy

Czego CompletePadesRemoteSignature odmawia?

CompletePadesRemoteSignature przeprowadza każde sprawdzenie, zanim zapisze jeden bajt do strumienia docelowego, i każda odmowa rzuca EPadesCrypto z komunikatem nazywającym sprawdzenie, które zawiodło. Sam rekord żądania jest sprawdzany najpierw: wersja formatu 1, odcisk palca i skrót po 32 bajty, ContentsSize między 1024 bajtami a 64 MiB, dodatnie przesunięcie szesnastkowe. Potem przygotowany plik:

  1. zapisane przesunięcia muszą leżeć wewnątrz pliku, a ByteRange musi układać się dokładnie z symbolem zastępczym i długością pliku
  2. nawiasy < i > wokół /Contents muszą być nadal na miejscu, a każda cyfra szesnastkowa między nimi musi nadal być 0
  3. SHA-256 całego pliku musi równać się PreparedFingerprint, a skrót z ByteRange musi równać się DocumentDigest

Potem CMS: musi być jedną dokładną wartością DER bez bajtów ogonowych, nie dłuższy niż ContentsSize, o obsługiwanym kształcie SignedData, z obecnym atrybutem signing-certificate-v2, a na koniec jego atrybut message-digest musi równać się DocumentDigest

Przygotowany plik zregenerowany między fazami zmienia odcisk palca, nawet gdy w przeglądarce wygląda identycznie. Test samych zer na symbolu zastępczym łapie podwójne dokończenie, gdy ponowna próba zapisuje drugi CMS nad podpisem, który już tam jest. Porównanie message-digest łapie najbrzydszy przypadek: poprawnie zbudowany CMS z Twojego własnego certyfikatu, podpisany nad innym dokumentem, bo kolejka przemieszała dwie równoległe sesje. Taki plik otworzyłby się bez zarzutu i nosił zgodę przeznaczoną dla zupełnie innego kontraktu

Sprawdzenie signing-certificate-v2 to bardziej kwestia zgodności niż integralności. CMS bez niego może zweryfikować się kryptograficznie i wciąż wywalić walidator PAdES, a odmowa przy dokończeniu przenosi to odkrycie z raportu walidacji u klienta do Twoich własnych logów. Dlaczego walidatory odrzucają podpisy PAdES omawia pozostałe atrybuty, których szukają walidatory

Diagram bramki ukończenia zdalnego podpisywania PAdES w PDFium dla Delphi: CompletePadesRemoteSignature sprawdza integralność pliku, kształt CMS i zgodność z PAdES, zapisując podpisany PDF tylko wtedy, gdy wszystkie sprawdzenia przejdą
CompletePadesRemoteSignature waliduje integralność, kształt CMS i zgodność PAdES, zanim jakikolwiek bajt zostanie zapisany
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;   // Twój własny kod: bajty DER, nie Base64

  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);   // Twój własny kod: zachowaj dokładny komunikat
      end;
    finally
      Dest.Free;
    end;
  finally
    Prepared.Free;
  end;
end;

Wiele API podpisujących zwraca CMS jako Base64 wewnątrz JSON, czasem z nagłówkami PEM wokół. Przekaż wyłącznie zdekodowany DER. Kończący znak nowej linii albo pozostały bajt nagłówka wali sprawdzanie jednej dokładnej wartości DER — i to jest zamierzony skutek: alternatywą jest CMS, który parsuje ze śmieciami na końcu

Pliki sesji między procesami i maszynami

SavePadesRemoteSigningRequest zapisuje stały binarny rekord o rozmiarze 120 bajtów: 8-bajtową magię PDRSIG01, wersję formatu, przesunięcie szesnastkowe, ContentsSize, cztery wartości ByteRange, a potem skrót i odcisk palca. LoadPadesRemoteSigningRequest odrzuca wszystko ze złą długością, złą magią, danymi ogonowymi albo wersją formatu inną niż 1. Rekord nie trzyma materiału klucza ani treści dokumentu, więc przechowywanie go obok przygotowanego PDF w wierszu bazy danych albo object store jest w porządku

To czyni przypadek aplikacji webowej prostym. Jeden handler żądań przygotowuje plik i składowuje oba artefakty, przeglądarka albo aplikacja na telefon zatwierdza skrót, a handler wywołania zwrotnego na innym węźle wczytuje sesję i dokańcza ją. Haczyk siedzi na przygotowanym PDF: musi wrócić bajt w bajt. Przepisanie go przez bibliotekę PDF, przepuszczenie przez optymalizator albo pozwolenie warstwie transferu dotknąć końców linii — wszystko to zmienia odcisk palca

Licznikowana usługa podpisu kwalifikowanego rozlicza się za operację, więc opłaca się sprawdzić zapisany plik, zanim w ogóle poprosisz o podpis. Szkic poniżej porównuje hash pliku z PreparedFingerprint przy pomocy System.Hash z RTL Delphi; to sprawdzenie, które dodajesz sam, a dokończenie i tak go powtarza

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

// Propozycja sprawdzenia pre-flight, które dodajesz sam; nie część komponentu
function PreparedFileStillMatches(const PreparedPath: string;
  const Request: TPadesRemoteSigningRequest): Boolean;
var
  S: TFileStream;
  H: TBytes;
begin
  S := TFileStream.Create(PreparedPath, fmOpenRead or fmShareDenyWrite);
  try
    // Przeciążenie TStream GetHashBytes wymaga świeżego System.Hash w Delphi;
    // Lazarus nie ma System.Hash, więc tam wołaj własną procedurę SHA-256
    H := THashSHA2.GetHashBytes(S);   // domyślnie SHA-256
  finally
    S.Free;
  end;
  Result := (Length(H) = Length(Request.PreparedFingerprint)) and
    CompareMem(@H[0], @Request.PreparedFingerprint[0], Length(H));
end;

Dobór ContentsSize, zanim CMS powstanie

ContentsSize liczy bajty DER CMS. Symbol zastępczy w pliku ma dwa razy tyle znaków szesnastkowych, dlatego domyślne 16384 daje 32 768 zer z akapitu otwierającego. Wartości poniżej 1024 są podnoszone do 1024, wartość powyżej 64 MiB jest odrzucana przy przygotowaniu, a dokończenie odrzuca każdy CMS dłuższy niż ContentsSize bajtów

Za mało to kosztowna pomyłka: usługa już podpisała, operacja jest spalona, a jedyna droga naprzód to przygotować jeszcze raz z większym slotem i podpisać jeszcze raz. Za dużo kosztuje tylko wypełnienie w każdym podpisanym pliku. Chyl się w stronę dużego. Załóżmy, że Twoja usługa zwraca CMS około 7000 bajtów z łańcuchem trzech certyfikatów; domyślna wartość i tak zostawia ponad połowę slotu wolnej. Jeśli usługa dodatkowo osadza token znacznika czasu podpisu albo dane o unieważnieniach jako atrybuty niepodpisane, lądują one w tym samym CMS i liczą się do tego samego limitu, więc zmierz jedną prawdziwą odpowiedź ze swojej produkcyjnej ścieżki i wymiaruj od niej, z zapasem na dłuższy łańcuch pośredników w przyszłości

Po dokończeniu: B-B, potem LTV i weryfikacja

Dokończony podpis zdalny to PAdES B-B. Długoterminowa walidacja dodaje znacznik czasu dokumentu i materiał walidacyjny w późniejszej aktualizacji przyrostowej z DSS i jego słownikami VRI per podpis, co opisuje artykuł o długoterminowych podpisach ze znacznikami czasu RFC 3161 i DSS. Ten krok dzieje się lokalnie, bo certyfikaty, odpowiedzi OCSP i CRL-e nie potrzebują klucza prywatnego

Wynik weryfikuj tą samą ścieżką, którą poszłaby strona ufająca — omawia ją inspekcja podpisów cyfrowych i poziomów PAdES. W potoku zdalnym kod budujący CMS mieszka na czyimś serwerze, a pierwszym miejscem, gdzie jego wyjście spotka prawdziwy walidator, powinna być Twoja własna kompilacja, zanim trafi do klientów

Wywołania zdalnego podpisywania są częścią edycji Enterprise PDFium Component dla Delphi i Lazarusa, obok natywnego kodu podpisywania PAdES, znaczników czasu i walidacji w czystym Pascalu. Referencja API i wersje próbne są na stronie produktu PDFium Component