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
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:
- 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
- nawiasy
<i>wokół/Contentsmuszą być nadal na miejscu, a każda cyfra szesnastkowa między nimi musi nadal być0 - 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
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