技术文章

HotPDF 把 PDF 图像编解码器隔离进工作进程

一个把图像提取包在 try..except 里的 Delphi 服务,日志看上去可以健康得很:EAccessViolation 被接住,上传标记为坏件,下一个任务照常开始。几分钟后,一个毫不相干的请求却在释放字符串列表时死于 EInvalidPointer。两件事是连着的。JPEG 2000 或 JBIG2 解码器在出错前已经写过缓冲区边界,堆早就被它损坏了,接住异常只是恢复控制流,那道伤原封不动留在原地。信不过的内存只能整个扔掉,而 Windows 允许你干净扔掉的内存单位就是进程

为什么在解码器外面套 try..except 并不够

图像编解码器是 PDF 阅读器里用最少校验的数据跑最复杂状态机的部件。字节到达 JPEG 2000 或 JBIG2 解码器时,交叉引用表已解析完,图像对象已解析,过滤器链已展开,剩下的只有一段原始码流,自报里面有多少个 tile、多少个分量、每个采样多少位。这里一个错误的数字不是解析器能拒绝的语法错误,它会变成紧凑解码循环内部的一个分配大小、一个循环边界或一个数组下标

字节预算能盖住一部分,摄入路径本来也该有。HotPDF 用 DecodeBudgetBytes 和 DocumentDecodeBudgetBytes 限制膨胀,用 DecodeFilterLimit 和 DecodePipelineDepthLimit 限制过滤器链;这些上限背后的考量写在嵌套过滤器与 PDF 炸弹的有界解码里。预算只回答一个问题:允许多少输出。至于一个 decoder 往错误位置写了几个字节之后才出错,预算无话可说

被接住的那种故障,某种意义上反而是更糟的结局。没接住的崩溃至少停掉进程;接住了的,让服务踩着损坏的堆继续接客,而最终失败的调用栈指向的绝不是肇事的那个 PDF

把 DCTDecode、JPXDecode 和 JBIG2Decode 挪进工作进程

HotPDF 可以把三个高风险图像过滤器——DCTDecode、JPXDecode 和 JBIG2Decode——放进短生命周期的 HotPDFCodecWorker.exe 工作进程里跑,而不是在你的应用程序内部。HPDFCodecIsolation 单元把它们命名为 hckDCT、hckJPX 和 hckJBIG2。Flate、LZW、RunLength、ASCII85 和 CCITT 留在进程内:这些解码器状态简单,解码预算就是对口的工具

每个请求都拿到一个全新进程。宿主创建一个随机命名的共享内存映射,写入固定的 THPDFCodecSharedHeader,后接压缩码流,JBIG2 再加全局段,然后以挂起态启动 worker,把它放进一个 Windows Job Object,最后才放行。这个 Job 只允许一个活动进程,被攻破的 decoder 生不出子进程;Job 以 kill-on-close 创建,worker 也活不过 job 句柄。解码出的像素以 24 位 BGR 回到同一块映射里,附带一个状态字

HotPDF 编解码隔离架构图:Delphi VCL 宿主与一次性工作进程交换共享内存映射,处理 DCTDecode、JPXDecode 和 JBIG2Decode 图像
宿主把压缩码流写进有界的共享内存映射,一次性工作进程在 Job Object 上限内解码,传回的只有像素和一个状态字

在 THotPDF 上设四个属性即可启用。图像调用的还是你已经在用的那几个:

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;            // 这些绝不在进程内解码
    Pdf.CodecWorkerExecutable := '';                  // '' = 宿主 EXE 旁边
    Pdf.CodecWorkerTimeoutMilliseconds := 5000;       // 1..600000,越界抛 ERangeError
    Pdf.CodecWorkerMemoryLimitBytes := 256 * 1024 * 1024; // 0 或 >= 64 MiB
    Pdf.DecodeBudgetBytes := 128 * 1024 * 1024;

    if Pdf.LoadFromFile(FileName) > 0 then            // 返回页数
      for I := 0 to Pdf.GetLoadedImageCount - 1 do
      begin
        Bmp := Pdf.ExtractLoadedImage(I);
        try
          // 立刻读结果:它只描述最近一次请求
          if Pdf.GetLastCodecWorkerInfo(Info) then
            LogCodecOutcome(FileName, I, Info);
          if Bmp <> nil then
            StoreImage(FileName, I, Bmp);             // 你自己的代码
        finally
          Bmp.Free;
        end;
      end;
  finally
    Pdf.Free;
  end;
end;

隔离解码失败时,ExtractLoadedImage 返回 nil,所以 Bmp <> nil 这个判断在这里有实际分量。GetLastCodecWorkerInfo 在没有 worker 请求记录时返回 False——Flate 压缩的图像或 cimDisabled 模式下看到的就是这个

部署上有两个细节最惹麻烦。空 CodecWorkerExecutable 解析到 ParamStr(0) 目录下的 HotPDFCodecWorker.exe;非空值走 ExpandFileName,相对路径就按当前目录解析——Windows 服务通常落在 System32,于是 bin\HotPDFCodecWorker.exe 在 IDE 里好好的,装完就找不到。另一个细节是位数:worker 构建脚本分别产出 Win32 和 Win64 二进制,发布哪个必须与宿主进程架构一致

Automatic 还是 Required:worker 缺席时会发生什么

THPDFCodecIsolationMode 的三个值回答同一个问题:worker 根本用不了时怎么办。cimDisabled 从不尝试,全部进程内解码。默认值 cimAutomatic 在 HotPDFCodecWorker.exe 存在时用 worker,文件不在就回退进程内解码并记录 cwsUnavailable。cimRequired 拒绝回退;worker 缺席就意味着这张图不解码

这条回退路比看上去窄,而且是刻意收窄的。只有可执行文件缺失才回退。文件在但 CreateProcess 失败——典型原因是终端安全软件拦了——结果是 cwsLaunchFailed,图像不解码,cimAutomatic 下也一样。worker 起来了随后崩溃、超时或超限的,两种模式都绝不改在进程内重试。把刚杀死 worker 的那个文件放进自己的进程再试一次,等于把 worker 本来要保护的目标再送攻一次

HotPDF 中 CodecIsolationMode 三个取值的对比图:编解码 worker 可执行文件缺失时 cimDisabled、cimAutomatic 与 cimRequired 的行为
只有 cimAutomatic 会回退到进程内解码并报告 cwsUnavailable,cimRequired 拒绝回退;崩溃与超时在两种模式下都算失败

凡是要读上传、邮件附件或合作方投递的场景,设 cimRequired。默认模式有个部署后才现形的坑:安装包忘了带 worker,产出的服务器照样张张图像提取正确、功能测试全过,而每个请求都在宿主里跑编解码器,看起来毫无异常。cimAutomatic 适合桌面查看器打开用户已有的文件——worker 缺席时应当降级而非停摆。cimRequired 还会关掉 ProgressiveJPEGScanDecoding 这条逐扫描段的渐进式 JPEG 路径,因为那条路在宿主里解码

加一个启动检查,能让忘带的 worker 立刻炸响。HPDFResolveCodecWorkerExecutable 在 HPDFCodecIsolation 里是公开的,解析规则与组件一致:

// 自己加的启动检查:没有 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;

读懂 THPDFCodecWorkerStatus

THPDFCodecWorkerInfo 带着 Status、ProcessId、ExitCode、ElapsedMilliseconds 和宿主侧的 ErrorMessage。状态值有 cwsNotRun、cwsSucceeded、cwsUnavailable、cwsLaunchFailed、cwsTimedOut、cwsCrashed、cwsDecodeFailed、cwsProtocolError 和 cwsOutputLimit,按运维含义分三组

  • 部署类:cwsUnavailable 和 cwsLaunchFailed。worker 缺失、被拦,或没法在 Job 里启动。呼服务器负责人;文档本身可能没毛病
  • 文档类:cwsDecodeFailed 和 cwsOutputLimit。码流畸形,或超出你的策略允许的尺寸。拒收文件就是正确处置
  • 遏制类:cwsTimedOut、cwsCrashed 和 cwsProtocolError。卡死、worker 暴毙,或者应答头与协议版本对不上、声称的几何尺寸算不拢。这些正是进程边界存在的意义,文件该隔离观察而非一拒了之

读数据时值得分清 cwsDecodeFailed 和 cwsCrashed 的界线。Delphi 把大多数访问违例转成异常,worker 在解码器外围接住异常并报告为解码失败。cwsCrashed 表示 worker 进程以非零退出码收场,那是故障重到任何异常处理器都来不及跑的时候。ExitCode 是 Cardinal,格式化用 %u 或十六进制;$C0000005 拿 %d 打出来是个负数,没人能按它搜对日志

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);   // 你自己的代码
    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]));          // 你自己的代码
  else
    RejectDocument(FileName, Info.ErrorMessage);                  // 你自己的代码
  end;
end;

worker 还替自己压掉了 Windows 故障对话框,于是无人值守服务器上的崩溃会出现在这份日志里,而不是弹出一个模态框,在没人看的机器上干等谁来点确定

每次隔离解码头上的三道天花板

每次隔离解码都跑在时间、内存、输出三道限制之下,状态值会告诉你是哪道收的场。CodecWorkerTimeoutMilliseconds 默认 10,000,接受 1 到 600,000;越界的值在赋值时就抛 ERangeError,不做钳制。超时时宿主终止整个 Job 并报告 cwsTimedOut。CodecWorkerMemoryLimitBytes 默认 536,870,912 字节,取值须为零——即不设上限——或至少 67,108,864 字节;它会变成 Job Object 上的每进程 committed 内存限额

输出限制是推出来的。HotPDF 按每像素三字节,从请求的目标尺寸、请求的区域或 PDF 里声明的图像几何算出解码图像该占的字节数,设了预算时再拿 DecodeBudgetBytes 封顶。共享映射就按这个数开尺寸,worker 越界无处可写。假设一张扫描件自称 10,000 乘 10,000 像素:那是 300,000,000 字节 BGR 输出,超过默认 268,435,456 字节的 DecodeBudgetBytes,上限于是取 256 MiB,解码以 cwsOutputLimit 收场

宿主也不信 worker 回报的尺寸。应答只有在宽乘高乘三等于它声称的字节数、且该数目既容得进宿主自己的输出限制也容得进映射时才被接受。被策反的 worker 能往头部写任何值;对不上就以 cwsProtocolError 报告,一个像素都不拷贝

HotPDF 每次隔离解码的三道天花板:worker 超时、Job Object 内存上限,以及被 DecodeBudgetBytes 封顶的推导输出上限
严格的超时与内存校验加推导的像素输出上限,让超大或卡死的解码以状态码终止在 worker 里,而不是终止在你的进程里

内存限制要给得比输出限制宽裕。按第一个例子的设置,256 MiB 进程上限里装 128 MiB 输出预算,还给压缩输入和 decoder 自己的工作集留了余地。两个数贴太近,大张的合法扫描件就会开始死在 worker 里,理由与敌意输入毫无关系

进程边界的代价

每张隔离图像起一个进程要花时间,几百页扫描 JPEG 的文档能明显感觉到。无人值守的批处理转换器上,这点时间消失在过夜窗口里,而遏制本来就是这项工作的存在理由。交互式查看器打开用户本就信任的文件是另一回事;那里用 cimAutomatic,对已知的内部档案用 cimDisabled,都算公道。CodecIsolationMode 是个普通属性,所以同一个服务可以对上传用 cimRequired,对自己生成的文档用轻量模式

具体是哪种编解码器也改变风险画像。JPXDecode 流带着直接驱动分配的 tile 数与分量数,而JBIG2 图像常常依赖多页共享的一条 /JBIG2Globals 流。沙箱要是只带单图码流,这些页要么解错要么解不出,所以全局段随每张图一起进 worker

编解码隔离、解码预算和解析器的结构性限制都住在同一个原生 VCL 组件里,额外要部署的只有 worker 可执行文件。安装说明、Win32 与 Win64 的 worker 构建和试用下载,见 HotPDF 组件页(Delphi 与 C++Builder)