Artigo Técnico

HotPDF: isolamento de codecs de imagem PDF

Um serviço Delphi que envolve a extração de imagens em try..except pode parecer perfeitamente saudável no log dele: um EAccessViolation é capturado, o upload é marcado como ruim, e o próximo job começa. Minutos depois, uma solicitação sem relação nenhuma pode morrer com EInvalidPointer ao liberar uma string list. Os dois eventos estão conectados. Um decodificador JPEG 2000 ou JBIG2 que escreveu além do fim de um buffer antes de falhar já danificou a heap, e capturar a exceção restaura o fluxo de controle deixando aquele dano exatamente onde estava. Memória em que você não pode confiar só pode ser jogada fora, e a unidade de memória que o Windows deixa você jogar fora de forma limpa é um processo

Por que um try..except ao redor do decodificador não basta

Um codec de imagem é a parte de um leitor de PDF que executa a máquina de estados mais complicada sobre os dados menos verificados. Quando os bytes chegam a um decodificador JPEG 2000 ou JBIG2, a tabela de referência cruzada já foi analisada, o objeto de imagem já foi resolvido e a cadeia de filtros já foi desfeita. O que resta é um codestream bruto que anuncia quantos tiles, quantos componentes e quantos bits por amostra ele contém. Um número errado ali não é um erro de sintaxe que o parser possa rejeitar. Ele vira um tamanho de alocação, um limite de loop ou um índice de array dentro de um loop de decodificação apertado

Orçamentos de bytes cobrem parte disso, e um caminho de entrada deveria tê-los de qualquer forma. O HotPDF limita a expansão com DecodeBudgetBytes e DocumentDecodeBudgetBytes, e limita cadeias de filtros com DecodeFilterLimit e DecodePipelineDepthLimit; o raciocínio por trás desses tetos está em decodificação limitada para filtros aninhados e PDF bombs. Um orçamento responde a uma pergunta: quanta saída é permitida. Ele não tem nada a dizer sobre um decodificador que falha depois de escrever um punhado de bytes no lugar errado

A falha que é capturada é, de certa forma, o pior desfecho. Um crash não tratado pelo menos para o processo. Um capturado deixa que ele continue servindo solicitações sobre uma heap corrompida, e a falha eventual chega com um stack trace que não aponta nem de longe para o PDF que a causou

Movendo DCTDecode, JPXDecode e JBIG2Decode para um processo worker

O HotPDF pode rodar os três filtros de imagem de alto risco, DCTDecode, JPXDecode e JBIG2Decode, em um processo worker de curta duração, o HotPDFCodecWorker.exe, em vez de dentro da sua aplicação. A unit HPDFCodecIsolation os nomeia como hckDCT, hckJPX e hckJBIG2. Flate, LZW, RunLength, ASCII85 e CCITT permanecem no mesmo processo: esses decodificadores têm estado simples, e os orçamentos de decodificação são a ferramenta certa para eles

Cada solicitação recebe um processo novo. O host cria um mapeamento de memória compartilhada com nome aleatório, grava um THPDFCodecSharedHeader fixo seguido do codestream comprimido e, no caso do JBIG2, dos segmentos globais, e então inicia o worker suspenso, coloca-o em um Windows Job Object e só então o deixa rodar. O job permite exatamente um processo ativo, então um decodificador comprometido não consegue criar filhos, e é criado com kill-on-close, então o worker não pode sobreviver ao handle do job. Os pixels decodificados voltam como BGR de 24 bits no mesmo mapeamento, junto com uma palavra de status

Diagrama de arquitetura do isolamento de codecs do HotPDF mostrando um host VCL Delphi trocando um mapeamento de memória compartilhada com um processo worker descartável para imagens DCTDecode, JPXDecode e JBIG2Decode
O host grava o codestream comprimido em um mapeamento de memória compartilhada limitado, um worker descartável o decodifica sob tetos de job-object, e apenas os pixels mais uma palavra de status voltam

Ativar isso leva quatro propriedades no THotPDF. As chamadas de imagem continuam as mesmas que você já usa:

uses
  Vcl.Graphics, HPDFDoc, HPDFCodecIsolation;

procedure ExtractUntrustedImages(const FileName: string);
var
  Pdf: THotPDF;
  Info: THPDFCodecWorkerInfo;
  Bmp: TBitmap;
  I: Integer;
begin
  Pdf := THotPDF.Create(nil);
  try
    Pdf.CodecIsolationMode := cimRequired;            // nunca decodifique estes em processo
    Pdf.CodecWorkerExecutable := '';                  // '' = ao lado do EXE do host
    Pdf.CodecWorkerTimeoutMilliseconds := 5000;       // 1..600000, senão ERangeError
    Pdf.CodecWorkerMemoryLimitBytes := 256 * 1024 * 1024; // 0 ou >= 64 MiB
    Pdf.DecodeBudgetBytes := 128 * 1024 * 1024;

    if Pdf.LoadFromFile(FileName) > 0 then            // retorna a contagem de páginas
      for I := 0 to Pdf.GetLoadedImageCount - 1 do
      begin
        Bmp := Pdf.ExtractLoadedImage(I);
        try
          // Leia o veredito imediatamente: ele descreve apenas a solicitação mais recente
          if Pdf.GetLastCodecWorkerInfo(Info) then
            LogCodecOutcome(FileName, I, Info);
          if Bmp <> nil then
            StoreImage(FileName, I, Bmp);             // código seu
        finally
          Bmp.Free;
        end;
      end;
  finally
    Pdf.Free;
  end;
end;

Quando uma decodificação isolada falha, o ExtractLoadedImage retorna nil, então a conferência Bmp <> nil carrega peso real aqui. O GetLastCodecWorkerInfo retorna False quando nenhuma solicitação ao worker foi registrada, que é o que você vê para uma imagem comprimida com Flate ou com cimDisabled

Dois detalhes de implantação causam a maior parte do problema. Um CodecWorkerExecutable vazio resolve para HotPDFCodecWorker.exe no diretório de ParamStr(0). Um valor não vazio passa por ExpandFileName, o que significa que um caminho relativo resolve contra o diretório atual. Para um serviço do Windows, esse diretório costuma ser o System32, então 'bin\HotPDFCodecWorker.exe' funciona na IDE e falha depois da instalação. O outro detalhe é o bitness: o script de build do worker produz binários Win32 e Win64 separados, e o que você distribuir precisa casar com a arquitetura do processo host

Automático ou obrigatório: o que acontece quando o worker está ausente?

Os três valores de THPDFCodecIsolationMode respondem a uma única pergunta, que é o que fazer quando o worker simplesmente não pode ser usado. O cimDisabled nunca o tenta e decodifica tudo no mesmo processo. O cimAutomatic, o padrão, usa o worker quando o HotPDFCodecWorker.exe existe e volta para a decodificação em processo quando o arquivo não está lá, registrando cwsUnavailable. O cimRequired recusa o fallback; um worker ausente significa que a imagem não é decodificada

O fallback é mais estreito do que parece à primeira vista, e a estreiteza é deliberada. Só um executável ausente gera fallback. Se o arquivo existe mas o CreateProcess falha, tipicamente porque um produto de segurança de endpoint o bloqueia, o resultado é cwsLaunchFailed e a imagem não é decodificada, mesmo sob cimAutomatic. Um worker que iniciou e depois travou, expirou ou excedeu um limite nunca é retentado em processo em nenhum dos modos. Retentar dentro do seu próprio processo um arquivo que acabou de matar o worker entregaria ao atacante uma segunda tentativa exatamente contra o alvo que o worker existia para proteger

Comparação dos valores de CodecIsolationMode no HotPDF mostrando o comportamento de cimDisabled, cimAutomatic e cimRequired quando o executável do worker de codecs está ausente
Apenas cimAutomatic recorre à decodificação em processo, reportada como cwsUnavailable, enquanto cimRequired recusa o fallback; travamentos e timeouts são falhas em ambos os modos

Para qualquer coisa que leia uploads, anexos de e-mail ou pastas de parceiros, defina cimRequired. O modo padrão tem uma armadilha que só aparece depois da implantação: um instalador que esquece o worker produz um servidor que extrai todas as imagens corretamente, passa em todos os testes funcionais e roda os codecs dentro do host em cada solicitação. Nada parece quebrado. O cimAutomatic é razoável para um visualizador desktop abrindo arquivos que o usuário já tem, onde um worker ausente deve degradar em vez de parar o produto. O cimRequired também desliga o ProgressiveJPEGScanDecoding, o caminho de JPEG progressivo scan a scan, porque esse caminho decodifica no host

Uma verificação de inicialização transforma um worker esquecido em uma falha imediata e barulhenta. O HPDFResolveCodecWorkerExecutable é público na HPDFCodecIsolation e aplica a mesma regra de resolução do componente:

// Uma verificação de inicialização que você mesmo adiciona: recuse-se a iniciar sem o worker
procedure RequireCodecWorker(Pdf: THotPDF);
var
  WorkerPath: string;
begin
  WorkerPath := HPDFResolveCodecWorkerExecutable(Pdf.CodecWorkerExecutable);
  if not FileExists(WorkerPath) then
    raise Exception.CreateFmt(
      'Codec worker missing at %s; refusing to accept PDF uploads',
      [WorkerPath]);
end;

Lendo o THPDFCodecWorkerStatus

O THPDFCodecWorkerInfo carrega Status, ProcessId, ExitCode, ElapsedMilliseconds e um ErrorMessage do lado do host. Os valores de status são cwsNotRun, cwsSucceeded, cwsUnavailable, cwsLaunchFailed, cwsTimedOut, cwsCrashed, cwsDecodeFailed, cwsProtocolError e cwsOutputLimit, e eles se ordenam em três grupos operacionais

  • Implantação: cwsUnavailable e cwsLaunchFailed. O worker está ausente, bloqueado ou não pôde ser iniciado dentro do job dele. Acione quem cuida do servidor; o documento em si pode estar bom
  • Documento: cwsDecodeFailed e cwsOutputLimit. O codestream está malformado ou é maior do que a sua política permite. Rejeitar o arquivo é a resposta correta
  • Contenção: cwsTimedOut, cwsCrashed e cwsProtocolError. Um travamento, um worker morto, ou uma resposta cujo cabeçalho não bate com a versão do protocolo ou cuja geometria declarada não fecha. Esses são os eventos para os quais a fronteira de processo existe, e o arquivo merece quarentena em vez de uma rejeição simples

A fronteira entre cwsDecodeFailed e cwsCrashed vale conhecer quando você lê os números. O Delphi transforma a maioria das access violations em exceções, e o worker captura exceções ao redor do decodificador e as reporta como uma decodificação que falhou. cwsCrashed significa que o processo worker terminou com um exit code diferente de zero, o que acontece quando a falha foi severa demais para nenhum handler de exceção chegar a rodar. ExitCode é um Cardinal, então formate-o com %u ou como hex; $C0000005 impresso com %d vira um número negativo que ninguém pesquisa corretamente

procedure LogCodecOutcome(const FileName: string; ImageIndex: Integer;
  const Info: THPDFCodecWorkerInfo);
begin
  case Info.Status of
    cwsSucceeded:
      ;
    cwsUnavailable, cwsLaunchFailed:
      AlertOps('Codec worker not usable: ' + Info.ErrorMessage);   // código seu
    cwsTimedOut, cwsCrashed, cwsProtocolError:
      Quarantine(FileName, Format('image %d: pid %u exit $%.8x after %u ms: %s',
        [ImageIndex, Info.ProcessId, Info.ExitCode,
         Info.ElapsedMilliseconds, Info.ErrorMessage]));          // código seu
  else
    RejectDocument(FileName, Info.ErrorMessage);                  // código seu
  end;
end;

O worker também suprime a própria caixa de diálogo de falhas do Windows, então um crash em um servidor sem supervisão aparece neste log em vez de aparecer como uma caixa modal esperando alguém clicar em OK em uma máquina que ninguém está olhando

Os três tetos de cada decodificação isolada

Cada decodificação isolada roda sob um limite de tempo, um limite de memória e um limite de saída, e o status diz qual deles a encerrou. CodecWorkerTimeoutMilliseconds tem padrão 10,000 e aceita de 1 a 600,000; qualquer coisa fora dessa faixa dispara ERangeError na atribuição em vez de ser truncado. No timeout, o host encerra o job inteiro e reporta cwsTimedOut. CodecWorkerMemoryLimitBytes tem padrão 536,870,912 bytes e precisa ser zero, significando sem teto, ou pelo menos 67,108,864 bytes; ele vira um limite de memória comprometida por processo no Job Object

O limite de saída é derivado. O HotPDF calcula os bytes que a imagem decodificada deve precisar a partir do tamanho alvo solicitado, da região solicitada ou da geometria de imagem declarada no PDF, a três bytes por pixel, e então limita esse valor ao DecodeBudgetBytes quando um orçamento está definido. O mapeamento compartilhado é dimensionado a partir desse valor, então o worker não tem espaço para escrever além dele. Suponha uma digitalização que declara 10,000 por 10,000 pixels: são 300,000,000 bytes de saída BGR, mais que o DecodeBudgetBytes padrão de 268,435,456 bytes, então o limite vira 256 MiB e a decodificação termina com cwsOutputLimit

O host também não confia no tamanho que o worker reporta de volta. Uma resposta só é aceita se a largura vezes a altura vezes três dela for igual à contagem de bytes que ela declara, e se essa contagem couber tanto no limite de saída do próprio host quanto no mapeamento. Um worker subvertido pode escrever qualquer valor no cabeçalho; uma incompatibilidade é reportada como cwsProtocolError e nenhum pixel é copiado

Três tetos em cada decodificação isolada do HotPDF: timeout do worker, limite de memória do Job Object e o limite de saída derivado limitado por DecodeBudgetBytes
Validação rigorosa de timeout e memória mais um teto derivado de saída de pixels significam que decodificações gigantes ou travadas terminam dentro do worker como códigos de status, e não dentro do seu processo

Mantenha o limite de memória confortavelmente acima do limite de saída. Com as configurações do primeiro exemplo, um orçamento de saída de 128 MiB dentro de um teto de processo de 256 MiB deixa espaço para a entrada comprimida e para o working set do próprio decodificador. Defina os dois próximos um do outro e digitalizações legítimas grandes começam a falhar dentro do worker por motivos que não têm nada a ver com entrada hostil

O que a fronteira de processo custa

Iniciar um processo por imagem isolada custa tempo, e um documento com várias centenas de páginas JPEG digitalizadas vai sentir isso. Em um conversor em lote sem supervisão, esse custo desaparece na janela da madrugada e a contenção é a razão de o job existir. Um visualizador interativo mostrando arquivos em que o usuário já confia é outro caso; ali, cimAutomatic, ou cimDisabled para um acervo interno conhecido, é uma escolha justa. CodecIsolationMode é uma propriedade comum, então um serviço pode aplicar cimRequired a uploads e um modo mais leve aos documentos que ele próprio gerou

O codec em questão também muda o quadro de risco. Streams JPXDecode carregam contagens de tiles e componentes que dirigem alocações direto, enquanto imagens JBIG2 frequentemente dependem de um stream /JBIG2Globals compartilhado por várias páginas. Um sandbox que levasse só o stream por imagem decodificaria essas páginas errado ou não as decodificaria, e é por isso que os segmentos globais viajam para o worker junto com cada imagem

Isolamento de codecs, orçamentos de decodificação e os limites estruturais do parser vivem em um único componente VCL nativo, e o único arquivo extra a implantar é o executável do worker. Notas de configuração, o build do worker para Win32 e Win64 e um download de avaliação estão na página do componente HotPDF para Delphi e C++Builder