Техническая статья

PDFium: удалённая подпись PAdES через HSM и облако

Заполнитель подписи PAdES на 16 384 байта виден в файле как 32 768 ASCII-нулей между угловыми скобками, и каждый байт PDF вне этого пробега уже покрыт хешем, который одобрит подписывающий. Вот неловкая часть подписания ключом, которого вы не касаетесь: документ обязан зафиксировать свою финальную компоновку до того, как CMS существует, а потом ждать — иногда часами, — пока сетевой HSM или облачная служба подписи просит человека подтвердить на телефоне. Что бы ни случилось с файлом за время этого ожидания, оно решает, валидна ли подпись

Почему удалённый ключ не может использовать SignPadesBytes

Обычный вызов предполагает, что приватный ключ достижим внутри вызова. SignPadesBytes в PDFium Component строит инкрементальное обновление, хеширует ByteRange, подписывает сертификатом, названным в CertificateThumbprint из хранилища Windows, и записывает готовый файл до возврата. Для ключа в локальном хранилище это ровно та форма, что нужна

Квалифицированное устройство создания подписи под управлением доверенного поставщика услуг работает иначе. Облачный API подписи с шагом второго фактора — тоже, как и HSM за очередью. Обмен — это разговор: вы отправляете дайджест, что-то вне вашего процесса аутентифицирует человека, а CMS приезжает позже, в другом потоке, в другом обработчике запроса, может быть, на другом сервере. Синхронный вызов может смоделировать такое только блокировкой потока на чьём-то телефоне

Поэтому удалённый путь распадается на два вызова. PreparePadesRemoteSignature производит подготовленный PDF и небольшую запись запроса. CompletePadesRemoteSignature принимает подготовленный PDF, запись и вернувшийся DER CMS и записывает подписанный файл. Ничто не привязывает два вызова к одному процессу

Подготовка документа через PreparePadesRemoteSignature

PreparePadesRemoteSignature читает исходный PDF, дописывает инкрементальное обновление с невидимым виджетом подписи на первой странице и записывает словарь подписи с /Filter /Adobe.PPKLite и /SubFilter /ETSI.CAdES.detached. Запись /Contents заполняется нулями фиксированной ширины, четыре числа ByteRange вписываются вокруг неё, а SHA-256 по этим двум диапазонам становится Request.DocumentDigest. Исходные байты файла остаются нетронутыми; обновление только дописывает

Выходная запись TPadesRemoteSigningRequest имеет шесть полей: FormatVersion, PreparedFingerprint (SHA-256 всего подготовленного файла), DocumentDigest, четырёхэлементный ByteRange, ContentsHexOffset (где начинаются hex-цифры) и ContentsSize. Службе подписи уходит только дайджест. Остальное существует, чтобы второй вызов мог доказать, что завершает те же байты, из которых пришёл дайджест

Три правила опций влияют на подготовленный файл, а четвёртое — на вашу сборку. Когда задан CommitmentTypeOid, словарь не несёт /Reason, потому что ETSI EN 319 142-1 считает тип обязательства в CMS и причину в PDF альтернативами; служба подписи тогда должна вписать commitment-type-indication в подписанные атрибуты CMS. SigningTimeUtc становится записью /M. Зашифрованные источники отвергаются сразу, так что сначала расшифруйте. Удалённые функции принадлежат редакции Enterprise: юнит FPdfPadesRemote должен быть слинкован, иначе точки входа в FPdfPades бросают EPdfEnterpriseRequired

Двухфазный поток удалённого PAdES в PDFium в Delphi: PreparePadesRemoteSignature резервирует слот CMS и передаёт дайджест документа в HSM или облачный сервис, а CompletePadesRemoteSignature встраивает возвращённый CMS в любом процессе или машине позже
Фаза один резервирует слот CMS и передаёт дайджест документа; фаза два встраивает CMS, вернувшийся от HSM или облачного ключа
uses
  System.SysUtils, System.Classes, System.DateUtils,
  FPdfCrypto, FPdfPades,
  FPdfPadesRemote;   // линкует 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;

  // Ваш код: передайте 32-байтовый дайджест в HSM или API подписи
  SendDigestToSigningService(Request.DocumentDigest);
end;

Если документ уже открыт в компоненте TPdf, TPdf.PreparePadesRemoteSignature(Prepared, Options, Request) сохраняет текущее состояние и готовит из него, возвращая False, когда активного документа нет. Завершение и помощники сессии — тоже методы класса на TPdf, так что второй фазе вообще не нужен загруженный документ

Что служба подписи должна вернуть

32 байта в DocumentDigest — это значение, которое CMS обязан нести в подписанном атрибуте message-digest. Обычно это не те байты, которые подписывает приватный ключ. RFC 5652 §5.4 говорит: когда подписанные атрибуты присутствуют, подпись вычисляется по DER-кодированию набора атрибутов, так что служба, возвращающая полный CMS, делает этот шаг сама, а голый HSM, подписывающий только хеши, оставляет его вам. Во втором случае ваш код строит SignedAttributes (content-type, message-digest, signing-certificate-v2), DER-кодирует их как SET OF с отсортированными членами, хеширует это и просит HSM подписать хеш. Перепутанный порядок сортировки даёт CMS, который выглядит нормально и проваливает криптографическую проверку; сортировка DER SET OF в подписанных атрибутах CMS разбирает эту ловушку

Кто бы ни собирал CMS, завершение принимает одну конкретную форму: SignedData ровно с одним SignerInfo, отсоединённый (без инкапсулированного содержимого), с подписанными атрибутами content-type и message-digest, алгоритмом дайджеста кроме MD5 или SHA-1 и валидным атрибутом signing-certificate-v2. Это совпадает с требованиями базовых подписей PAdES по ETSI EN 319 142-1, так что служба, уже производящая совместимый с PAdES вывод CAdES, подходит без дополнительной работы

Что отвергает CompletePadesRemoteSignature

CompletePadesRemoteSignature прогоняет все проверки, прежде чем записать хоть один байт в поток назначения, и каждый отказ бросает EPadesCrypto с сообщением, называющим проваленную проверку. Сама запись запроса проверяется первой: версия формата 1, отпечаток и дайджест по 32 байта, ContentsSize между 1024 байтами и 64 МиБ, положительное hex-смещение. Затем подготовленный файл:

  1. записанные смещения должны лежать внутри файла, и ByteRange должен точно состыковаться с заполнителем и длиной файла
  2. угловые скобки < и > вокруг /Contents должны оставаться на месте, и каждая hex-цифра между ними должна по-прежнему быть 0
  3. SHA-256 всего файла должен равняться PreparedFingerprint, а хеш по ByteRange — DocumentDigest

Затем CMS: он должен быть одним точным значением DER без хвостовых байтов, не длиннее ContentsSize, поддерживаемой формы SignedData, с присутствующим signing-certificate-v2, и наконец его атрибут message-digest должен равняться DocumentDigest

Подготовленный файл, перегенерированный между фазами, меняет отпечаток, даже если в просмотрщике выглядит идентично. Проверка нулей в заполнителе ловит двойное завершение, когда повтор записывает второй CMS поверх уже существующей подписи. Сравнение message-digest ловит самый мерзкий случай: корректно сформированный CMS от вашего собственного сертификата, подписанный над другим документом, потому что очередь перепутала две параллельные сессии. Такой файл открылся бы без проблем и нёс одобрение, предназначенное другому договору

Проверка signing-certificate-v2 — про соответствие больше, чем про целостность. CMS без неё может криптографически проверяться и всё равно провалить PAdES-валидатор, и отказ на завершении переносит это открытие из отчёта валидации заказчика в ваши собственные логи. Почему валидаторы отвергают подписи PAdES разбирает остальные атрибуты, которые ищут валидаторы

Диаграмма шлюза завершения удалённого подписания PAdES в PDFium в Delphi: CompletePadesRemoteSignature проверяет целостность файла, форму CMS и соответствие PAdES, записывая подписанный PDF только когда все проверки проходят
CompletePadesRemoteSignature валидирует целостность, форму CMS и соответствие PAdES прежде, чем будет записан хоть один байт
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;   // ваш код: байты DER, не 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);   // ваш код: сохраните точный текст сообщения
      end;
    finally
      Dest.Free;
    end;
  finally
    Prepared.Free;
  end;
end;

Многие API подписи возвращают CMS как Base64 внутри JSON, иногда с PEM-заголовками вокруг. Передавайте только декодированный DER. Хвостовой перевод строки или оставшийся байт заголовка провалит проверку одного точного значения DER — это и есть задуманный результат: альтернативой был бы CMS, который разбирается с мусором после себя

Файлы сессий между процессами и машинами

SavePadesRemoteSigningRequest пишет фиксированную 120-байтовую бинарную запись: 8-байтовая магия PDRSIG01, версия формата, hex-смещение, ContentsSize, четыре значения ByteRange, затем дайджест и отпечаток. LoadPadesRemoteSigningRequest отвергает всё с неправильным размером, неправильной магией, хвостовыми данными или версией формата кроме 1. Запись не несёт ни материала ключей, ни содержимого документа, так что хранить её рядом с подготовленным PDF в строке базы данных или object store можно

Это делает случай веб-приложения прямолинейным. Один обработчик запроса готовит файл и хранит оба артефакта, браузер или приложение на телефоне одобряет дайджест, а обработчик колбэка на другом узле грузит сессию и завершает её. Ограничение лежит на подготовленном PDF: он должен вернуться байт в байт. Пересохранение через PDF-библиотеку, прогон через оптимизатор или слой передачи, трогающий концы строк, — всё это меняет отпечаток

Тарифицируемая служба квалифицированных подписей берёт плату за операцию, поэтому стоит проверить сохранённый файл, прежде чем вообще просить подпись. Набросок ниже сравнивает хеш файла с PreparedFingerprint через System.Hash из Delphi RTL; это проверка, которую вы добавляете сами, и завершение всё равно повторит её

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

// Рекомендуемая preflight-проверка, которую вы добавляете сами; не часть компонента
function PreparedFileStillMatches(const PreparedPath: string;
  const Request: TPadesRemoteSigningRequest): Boolean;
var
  S: TFileStream;
  H: TBytes;
begin
  S := TFileStream.Create(PreparedPath, fmOpenRead or fmShareDenyWrite);
  try
    // Перегрузка GetHashBytes для TStream требует свежего System.Hash в Delphi;
    // в Lazarus нет System.Hash, поэтому там вызывайте свою SHA-256-процедуру
    H := THashSHA2.GetHashBytes(S);   // SHA-256 по умолчанию
  finally
    S.Free;
  end;
  Result := (Length(H) = Length(Request.PreparedFingerprint)) and
    CompareMem(@H[0], @Request.PreparedFingerprint[0], Length(H));
end;

Подбор ContentsSize до того, как CMS существует

ContentsSize считает байты DER CMS. Заполнитель в файле — вдвое больше hex-символов, вот почему умолчание 16384 даёт 32 768 нулей из вводного абзаца. Значения ниже 1024 поднимаются до 1024, значение выше 64 МиБ отвергается на подготовке, а завершение отвергает любой CMS длиннее ContentsSize байтов

Слишком маленький — дорогая ошибка: служба уже подписала, операция потрачена, и единственный путь вперёд — готовить заново с большим слотом и подписывать заново. Слишком большой стоит лишь набивки в каждом подписанном файле. Клонитесь в большую сторону. Пусть ваша служба возвращает CMS около 7 000 байтов с цепочкой из трёх сертификатов; умолчание всё ещё оставляет свободной больше половины слота. Если служба вдобавок встраивает токен метки времени подписи или данные отзыва как неподписанные атрибуты, они ложатся в тот же CMS и считаются против того же лимита, так что измерьте один реальный ответ из вашего производственного контура и подбирайте размер по нему, с запасом под более длинную цепочку промежуточных позже

После завершения: B-B, затем LTV и проверка

Завершённая удалённая подпись — это PAdES B-B. Долгосрочная валидация добавляет метку времени документа и материал валидации в более позднем инкрементальном обновлении с DSS и его словарями VRI для каждой подписи — это описано в статье о долгосрочных подписях с метками времени RFC 3161 и DSS. Этот шаг выполняется локально, потому что сертификатам, ответам OCSP и CRL приватный ключ не нужен

Проверяйте вывод тем же путём, каким пошла бы доверяющая сторона, — это разобрано в статье об инспекции цифровых подписей и уровней PAdES. В удалённом конвейере код, собирающий CMS, живёт на чужом сервере, и первое место, где его вывод встречает настоящий валидатор, должна быть ваша собственная сборка — раньше ваших заказчиков

Вызовы удалённого подписания поставляются с редакцией Enterprise компонента PDFium Component для Delphi и Lazarus вместе с нативным Pascal-кодом подписания PAdES, простановки меток времени и валидации. Справочник API и пробные загрузки — на странице продукта PDFium Component