기술 문서

PDFium VCL 원격 PAdES 서명: HSM과 클라우드 키

16,384바이트짜리 PAdES 서명 플레이스홀더는 파일에서 꺾쇠 괄호 사이의 32,768개 ASCII 0으로 나타나며, 그 구간 밖의 PDF 바이트는 모두 이미 서명자가 승인할 해시로 덮여 있습니다. 손댈 수 없는 키로 서명할 때의 까다로운 지점이 바로 이것입니다. 문서는 CMS가 존재하기 전에 최종 배치를 확정해야 하고, 그다음 네트워크 HSM이나 클라우드 서명 서비스가 사람에게 휴대폰 확인을 요청하는 동안 몇 시간씩 기다려야 할 수 있습니다. 그 대기 동안 파일에 일어나는 일이 서명의 검증 여부를 결정합니다

원격 키는 왜 SignPadesBytes를 쓸 수 없는가?

평범한 호출은 개인 키가 호출 안에서 닿는 거리에 있다고 가정합니다. PDFium Component의 SignPadesBytes는 증분 업데이트를 만들고 ByteRange를 해시한 뒤, Windows 스토어에서 CertificateThumbprint가 가리키는 인증서로 서명하고, 돌아오기 전에 완성된 파일을 기록합니다. 로컬 스토어의 키라면 딱 원하는 형태입니다

신뢰 서비스 제공자가 운영하는 적격 서명 생성 장치는 그렇게 동작하지 않습니다. 2차 인증 단계가 있는 클라우드 서명 API도, 큐 뒤에 있는 HSM도 마찬가지입니다. 그 교환은 대화입니다. 다이제스트를 보내면 프로세스 바깥의 무언가가 사람을 인증하고, CMS는 나중에 다른 스레드, 다른 요청 핸들러, 어쩌면 다른 서버에 도착합니다. 동기 호출이 그것을 흉내 내는 유일한 방법은 누군가의 휴대폰에서 스레드 하나를 붙잡아 두는 것입니다

그래서 원격 경로는 두 호출로 나뉩니다. PreparePadesRemoteSignature는 준비된 PDF와 작은 요청 레코드를 만들고, CompletePadesRemoteSignature는 준비된 PDF와 레코드, 돌아온 DER CMS를 받아 서명된 파일을 기록합니다. 두 호출을 같은 프로세스에 묶는 것은 아무것도 없습니다

PreparePadesRemoteSignature로 문서 준비하기

PreparePadesRemoteSignature는 원본 PDF를 읽고, 첫 페이지에 보이지 않는 서명 위젯을 얹은 증분 업데이트를 덧붙이며, /Filter /Adobe.PPKLite와 /SubFilter /ETSI.CAdES.detached를 붙인 서명 딕셔너리를 기록합니다. /Contents 항목은 고정 폭의 0으로 채워지고, 네 개의 ByteRange 숫자가 그 주위에 패치되며, 그 두 범위에 대한 SHA-256이 Request.DocumentDigest가 됩니다. 원본 파일의 바이트는 그대로이고 업데이트는 덧붙이기만 합니다

출력 레코드 TPadesRemoteSigningRequest는 여섯 개의 필드를 갖습니다. FormatVersion, PreparedFingerprint(준비된 파일 전체의 SHA-256), DocumentDigest, 네 요소짜리 ByteRange, ContentsHexOffset(16진수가 시작하는 위치), ContentsSize입니다. 서명 서비스로 가는 것은 다이제스트뿐입니다. 나머지는 두 번째 호출이 다이제스트가 나온 바로 그 바이트를 완성하는 것임을 증명하기 위해 존재합니다

옵션 규칙 세 개는 준비된 파일에 영향을 주고, 넷째는 빌드에 영향을 줍니다. CommitmentTypeOid가 설정되면 딕셔너리에는 /Reason이 들어가지 않습니다. ETSI EN 319 142-1이 CMS의 커밋먼트 타입과 PDF의 reason을 대안으로 취급하기 때문이며, 이때 서명 서비스는 commitment-type-indication을 CMS 서명 속성에 기록해야 합니다. SigningTimeUtc는 /M 항목이 됩니다. 암호화된 원본은 그대로 거부되므로 먼저 복호화하세요. 원격 함수는 Enterprise 에디션에 속합니다. 유닛 FPdfPadesRemote를 링크해야 하며, 그렇지 않으면 FPdfPades의 엔트리 포인트가 EPdfEnterpriseRequired를 일으킵니다

Delphi의 2단계 PDFium 원격 PAdES 흐름: PreparePadesRemoteSignature가 CMS 슬롯을 예약하고 문서 다이제스트를 HSM이나 클라우드 서비스로 넘기며, CompletePadesRemoteSignature가 나중에 아무 프로세스나 머신에서 돌아온 CMS를 박아 넣는 모습
1단계는 CMS 슬롯을 예약하고 문서 다이제스트를 넘기고, 2단계는 HSM이나 클라우드 키에서 돌아온 CMS를 밀어 넣습니다
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의 클래스 메서드이므로, 두 번째 단계에는 로드된 문서가 전혀 필요 없습니다

서명 서비스가 돌려주어야 하는 것

DocumentDigest의 32바이트는 CMS가 message-digest 서명 속성에 담아야 할 값입니다. 그렇다고 개인 키가 서명하는 바이트인 것은 보통 아닙니다. RFC 5652 §5.4에 따르면 서명 속성이 있을 때 서명은 속성 집합의 DER 인코딩 위에서 계산되므로, 완성된 CMS를 돌려주는 서비스는 그 단계를 자체적으로 처리하고, 해시에만 서명하는 맨바닥 HSM은 그것을 여러분에게 맡깁니다. 후자의 경우 코드가 SignedAttributes(content-type, message-digest, signing-certificate-v2)를 만들고, 멤버를 정렬해 SET OF로 DER 인코딩한 뒤 그것을 해시하고, HSM에게 그 해시에 서명하라고 요청합니다. 정렬 순서가 틀리면 얼핏 멀쩡해 보이지만 암호학적 검증에 실패하는 CMS가 나옵니다. CMS 서명 속성의 DER SET OF 정렬이 그 함정을 상세히 다룹니다

CMS를 누가 조립하든, 완성 호출은 하나의 특정 형태만 받습니다. SignerInfo를 정확히 하나 갖는 detached(캡슐화된 콘텐츠 없음) SignedData, content-type과 message-digest 서명 속성, MD5나 SHA-1이 아닌 다이제스트 알고리즘, 그리고 유효한 signing-certificate-v2 속성입니다. 이것들은 ETSI EN 319 142-1의 PAdES baseline 서명 요건과 일치하므로, 이미 PAdES 호환 CAdES 출력을 만드는 서비스는 추가 작업 없이 들어맞습니다

CompletePadesRemoteSignature는 무엇을 거부하는가?

CompletePadesRemoteSignature는 대상 스트림에 단 한 바이트를 쓰기 전에 모든 검사를 돌리고, 거부할 때마다 실패한 검사 이름을 밝히는 메시지와 함께 EPadesCrypto를 일으킵니다. 요청 레코드 자체부터 검사합니다. 포맷 버전 1, 32바이트 지문과 다이제스트, 1024바이트에서 64 MiB 사이의 ContentsSize, 양수인 16진수 오프셋. 그다음은 준비된 파일입니다:

  1. 기록된 오프셋들이 파일 안에 있어야 하고, ByteRange는 플레이스홀더와 파일 길이와 정확히 맞아야 합니다
  2. /Contents 주위의 <와 >가 제자리에 있어야 하고, 그 사이의 모든 16진수는 여전히 0이어야 합니다
  3. 파일 전체의 SHA-256은 PreparedFingerprint와, ByteRange 해시는 DocumentDigest와 같아야 합니다

그다음은 CMS입니다. 하나의 정확한 DER 값이어야 하고, 뒤에 붙는 바이트가 없어야 하며, ContentsSize보다 길면 안 되고, 지원되는 SignedData 형태여야 하고, signing-certificate-v2가 있어야 하고, 마지막으로 message-digest 속성이 DocumentDigest와 같아야 합니다

단계 사이에 준비 파일이 다시 만들어지면 뷰어에서 똑같아 보여도 지문은 바뀝니다. 플레이스홀더의 all-zero 검사는 이중 완성을 잡아냅니다. 재시도가 이미 서명된 자리 위에 두 번째 CMS를 덮어쓰는 경우입니다. message-digest 비교는 가장 지독한 경우를 잡습니다. 큐가 동시 세션 둘을 바꿔 끼워서, 여러분 인증서가 다른 문서에 서명한, 형태는 완벽히 올바른 CMS가 들어오는 경우입니다. 그 파일은 잘 열리고 다른 계약을 위한 승인을 달고 다닙니다

signing-certificate-v2 검사는 무결성보다 규격 준수에 가깝습니다. 그 속성이 없는 CMS는 암호학적으로는 검증을 통과할 수 있지만 여전히 PAdES 검증기에 걸리며, 완성 단계에서 이를 거부하면 그 발견이 고객의 검증 보고서가 아니라 여러분의 로그에서 일어납니다. 검증기가 찾는 나머지 속성은 검증기가 PAdES 서명을 거부하는 이유를 참고하세요

Delphi의 PDFium 원격 PAdES 서명 완성 게이트 다이어그램: 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;   // 여러분의 코드: Base64가 아닌 DER 바이트

  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를 JSON 안의 Base64로 돌려주고, 때로 PEM 헤더가 둘러싸여 있기도 합니다. 넘기는 것은 디코딩된 DER뿐이어야 합니다. 뒤에 붙은 개행이나 남은 헤더 바이트는 하나의 정확한 DER 값 검사에 걸리는데, 그것이 의도된 결과입니다. 대안은 뒤에 쓰레기가 붙은 채 파싱되는 CMS입니다

프로세스와 머신을 넘나드는 세션 파일

SavePadesRemoteSigningRequest는 고정된 120바이트 이진 레코드를 기록합니다. 8바이트 PDRSIG01 매직, 포맷 버전, 16진수 오프셋, ContentsSize, 네 개의 ByteRange 값, 그 뒤에 다이제스트와 지문입니다. LoadPadesRemoteSigningRequest는 크기가 틀리거나 매직이 틀리거나 뒤에 데이터가 더 있거나 포맷 버전이 1이 아닌 것은 무조건 거부합니다. 레코드는 키 재료도 문서 내용도 담지 않으므로, 준비된 PDF 곁에 데이터베이스 행이나 오브젝트 스토어에 저장해도 아무 문제 없습니다

덕분에 웹 애플리케이션 케이스는 단순합니다. 한 요청 핸들러가 파일을 준비해 두 아티팩트를 저장하고, 브라우저나 휴대폰 앱이 다이제스트를 승인하면, 다른 노드의 콜백 핸들러가 세션을 로드해 완성합니다. 제약은 준비된 PDF 쪽에 있습니다. 바이트 단위로 그대로 돌아와야 합니다. PDF 라이브러리로 다시 저장하거나, 옵티마이저를 통과시키거나, 전송 계층이 줄 끝을 건드리는 것만으로도 지문은 바뀝니다

종량제 적격 서명 서비스는 호출당 요금을 받으므로, 서명 자체를 요청하기 전에 저장된 파일을 검사해 두면 돈이 됩니다. 아래 스케치는 Delphi RTL의 System.Hash로 파일 해시를 PreparedFingerprint와 비교합니다. 직접 추가하는 검사이며, 어차피 완성 호출이 같은 검사를 되풀이합니다

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

// 직접 추가하는 사전 점검. 컴포넌트에 포함되지 않음
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 오버로드에는 최신 Delphi의 System.Hash가 필요합니다
    // 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;

CMS가 존재하기 전에 ContentsSize 크기 정하기

ContentsSize는 DER CMS의 바이트 수를 셉니다. 파일 속 플레이스홀더는 그 두 배의 16진수 문자인데, 서두의 32,768개 0이 나온 이유가 바로 기본값 16384입니다. 1024 미만의 값은 1024로 올리고, 64 MiB를 넘는 값은 준비 단계에서 거부하며, 완성 단계는 ContentsSize보다 긴 CMS는 무조건 거부합니다

너무 작은 것이 비싼 실수입니다. 서비스는 이미 서명했고 호출은 소진되었으며, 앞으로 길은 더 큰 슬롯으로 다시 준비하고 다시 서명하는 것뿐입니다. 너무 큰 것은 서명된 모든 파일에 패딩이 드는 것에 그칩니다. 큰 쪽으로 기우세요. 서비스가 인증서 세 개 체인을 갖춘 약 7,000바이트 CMS를 돌려준다고 치면, 기본값에도 슬롯의 절반 이상이 남습니다. 서비스가 서명 타임스탬프 토큰이나 폐기 데이터를 unsigned 속성으로 묶어 넣는다면 그것들도 같은 CMS 안에 들어 같은 한도로 계산되므로, 프로덕션 체인의 실제 응답 하나를 측정해 그것을 기준으로 크기를 잡되 나중에 더 긴 중간 체인을 위한 여유를 남겨 두세요

완성 이후: B-B, 그리고 LTV와 검증

완성된 원격 서명은 PAdES B-B입니다. 장기 검증(LTV)은 문서 타임스탬프와 검증 재료를 DSS와 서명별 VRI 딕셔너리와 함께 나중의 증분 업데이트로 추가하며, 이는 RFC 3161 타임스탬프와 DSS로 만드는 장기 서명에서 설명합니다. 그 단계는 로컬에서 돌아갑니다. 인증서와 OCSP 응답, CRL에는 개인 키가 필요 없기 때문입니다

출력은 의존 당사자가 밟을 경로와 같은 경로로 검증하세요. 디지털 서명과 PAdES 레벨 점검하기가 이를 다룹니다. 원격 파이프라인에서 CMS를 만드는 코드는 남의 서버에 살고, 그 출력이 진짜 검증기를 처음 만나는 장소는 고객보다 여러분의 빌드여야 합니다

원격 서명 호출은 네이티브 Pascal PAdES 서명, 타임스탬프, 검증 코드와 함께 Delphi 및 Lazarus용 PDFium Component의 Enterprise 에디션에 들어 있습니다. API 레퍼런스와 평가판 다운로드는 PDFium Component 제품 페이지에 있습니다