NextPDF Connect(Pro)에 PAdES 디지털 서명 적용하기

한눈에 보기

PAdES 기준의 디지털 서명을 NextPDF Connect를 통해 PDF에 적용합니다. 사용하는 도구는 sign_pdf입니다. Pro 도구 공급자를 기준으로 재검증되었으며, 해당 공급자는 new SignPdfTool()을 등록하고 프로토콜 이름은 sign_pdf입니다. sign_pdf는 Pro 등급 도구입니다. 서버는 부팅 시 class_exists()로 이를 탐지하며, Pro 패키지가 설치된 경우에만 등록합니다.

기본적으로 이 도구는 PAdES B-B를 생성합니다. PAdES B-T(B-B에 RFC 3161 signature-time-stamp 하나를 더한 것)는 호스트에서 타임스탬프 공급자를 도구에 연결한 경우에만 생성할 수 있습니다. 요청에서 TSA를 지정할 수 없습니다. 장기 보존 레벨(B-LT, B-LTA)과 해당 검증 자료(DSS, VRI, LTV)는 이 도구의 일부가 아니며 여기서는 범위를 벗어납니다.

U-1 유의 사항. NextPDF는 독립적인 ETSI EN 319 142-1 PAdES B-T 인증을 주장하지 않습니다. EN 319 142-1은 검증 코퍼스에 포함되어 있지 않습니다. B-T signature-time-stamp 요구 사항은 EN 319 142-1/-2가 참조로 가져오는 CAdES 기반인 ETSI EN 319 122-1 §5.3과 RFC 3161, RFC 5652, RFC 5816, 그리고 ISO 32000-2 §12.8을 기준으로 검증됩니다. B-T 프로필 지원은 적합성 또는 법적 유효성 인증이 아니며, 독립적인 검증기가 판단합니다.

설치

composer require nextpdf/server
composer require nextpdf/pro

트랜스포트를 바인딩합니다. diagnostic.capabilities에서 sign_pdf가 있는지 확인합니다. B-T의 경우, 호스트에서 타임스탬프 공급자와 함께 도구를 구성해야 합니다. 공급자가 없으면 pades_b_t: true 요청은 자동으로 다운그레이드되지 않고 형식화된 오류로 실패합니다.

개념 개요

sign_pdf는 서명 값 자리표시자를 제외하고 파일 전체에 대한 바이트 범위 다이제스트를 계산합니다(ISO 32000-2 §12.8.1). 그런 다음 DER로 인코딩된 CMS SignedData를 서명 사전 Contents에 기록합니다(ISO 32000-2 §12.8.1). 지원하는 알고리즘: RSA-SHA256(기본값), RSA + SHA-3(256/384/512), Ed25519. 선택적인 AES-GCM 봉투를 사용하면 종단 간 기밀성을 제공하지 않는 트랜스포트에서 들어오는 private_key 페이로드를 감쌀 수 있습니다.

B-T 업그레이드. pades_b_t: true와 호스트에서 연결한 타임스탬프 공급자가 모두 있으면 서명이 PAdES B-T로 업그레이드됩니다. 바이트 범위 해시가 TSA로 전송되고 TimeStampToken이 임베드됩니다(ISO 32000-2 §12.8.5). B-T는 정확히 B-B에 CMS SignerInfo의 서명되지 않은 속성으로 실리는 RFC 3161 signature-time-stamp 하나를 더한 것입니다(RFC 5652 §5.3). 서명되지 않은 속성은 서명 보호 대상이 아니므로 B-B의 서명된 다이제스트와 그 유효성은 변하지 않습니다(RFC 5652 §5.3). 속성 값은 SignatureTimeStampToken입니다(ETSI EN 319 122-1 §5.3). B-T는 DSS 사전, VRI, 검증 자료, 아카이브 타임스탬프 루프를 추가하지 않습니다. 이들은 B-LT/B-LTA Enterprise 델타이며 이 도구의 범위를 벗어납니다.

U-1 유의 사항(B-T 주장에 대한 반복). 여기서 말하는 B-T 지원은 EN 319 142-1 적합성 또는 법적 유효성 인증이 아니며, 독립적인 검증기가 판단합니다. EN 319 142-1은 검증 코퍼스에 포함되어 있지 않습니다. B-T는 ETSI EN 319 122-1 §5.3, RFC 3161, RFC 5652, RFC 5816, 그리고 ISO 32000-2 §12.8을 근거로 합니다.

요청에서 TSA를 지정할 수 없는, 호스트가 게이트하는 TSA 접점과 실패 시 폐쇄되는 B-T 분기(자동 다운그레이드가 결코 없음)를 포함한 도구 흐름은 아래와 같습니다.

Diagram

API 인터페이스

도구	등급	역할	위험 등급
`create_pdf`, `add_text`	Core	콘텐츠 빌드	안전 / 주의
`sign_pdf`	Pro	PAdES B-B(또는 호스트가 게이트하는 B-T)를 적용	승인 필요
`output_pdf`	Core	PDF를 렌더링하고 반환	승인 필요 / 검토(base64)

도구 이름은 레지스트리의 프로토콜 이름입니다. 도구 카탈로그가 기준 카탈로그입니다. 사용 가능한 도구는 설치된 등급에 따라 다르며, 장기 보존 레벨 도구는 Pro에는 제공되지 않습니다.

코드 샘플 — 빠른 시작

create_pdf → add_text로 콘텐츠를 빌드합니다.
certificate(PEM), private_key(PKCS#8 PEM), 선택적인 signer_name, reason, algorithm과 함께 sign_pdf를 호출합니다. B-B의 경우 pades_b_t를 생략하거나 false로 설정합니다.
output_pdf.

이 도구는 다음과 같은 결과 봉투를 반환합니다:

{
  "pdf": "<base64 of the signed PDF>",
  "signature_count": 1,
  "is_complete": true,
  "algorithm": "RSA_SHA256",
  "oid": "<algorithm OID>",
  "digest": "<digest algorithm>",
  "level": "PAdES-B-B",
  "timestamped": false
}

호스트가 게이트하는 B-T 서명을 만들려면 pades_b_t: true를 보냅니다. level은 "PAdES-B-T"가 되고 timestamped는 true가 됩니다.

코드 샘플 — 프로덕션

마지막 콘텐츠 작업으로 서명합니다. sign_pdf 이후의 add_text/add_image는 서명을 무효화합니다. 기밀성을 제공하지 않는 트랜스포트에서는 private_key를 AES-GCM transport_encryption 봉투로 감쌉니다(12 바이트 논스, 16/24/32 바이트 키). 결과 level이 요청한 것과 일치하는지 확인합니다. 공급자가 연결되지 않은 도구에 pades_b_t: true를 요청하면 명시적으로 실패합니다. 해당 오류를 처리하고, 자동으로 B-B로 재시도하지 마십시오.

엣지 케이스 및 함정

인증서/키 불일치. 명확한 오류와 함께 거부됩니다. 개인 키는 인증서의 공개 키와 일치해야 합니다.
잘못된 형식의 PEM / 만료된 인증서. 거부됩니다. 이 도구는 기본적으로 구문 분석할 수 없거나 만료된 인증서로 서명하지 않습니다.
서명 후 콘텐츠. 거부됩니다 — 마지막에 서명하십시오.
B-T 요청, 공급자 없음. 형식화된 오류: 서명이 생성되지 않으며 자동으로 B-B 로 다운그레이드되지 않습니다.
자체 서명 인증서. 서명은 적용되지만 리더가 알 수 없는 신뢰 상태를 표시합니다 — 이는 예상된 동작이며 도구 결함이 아닙니다.
Pro 부재. Core만 있는 경우 sign_pdf는 등록되지 않습니다.

성능

서명은 CMS 빌드를 추가하고, B-T의 경우 TSA 왕복 한 번도 추가합니다. 예산은 이를 포함합니다. 프로필은 semantic입니다. RFC 3161 토큰은 본질적으로 재현할 수 없고, §12.8.1 바이트 범위 다이제스트는 서명 값을 제외하므로 AST + 서명 메타데이터 비교만이 타당합니다.

보안 참고

서명은 서명 키를 기준으로 무결성과 인증을 제공합니다. 서명 자체만으로 문서를 “안전”하거나 “법적으로 유효”하게 만들거나 부인 방지를 보장하지는 않습니다. 이는 인증서, 그 신뢰 앵커, 키 보관, 검증자의 정책에 달려 있으며 모두 이 도구 외부에 있습니다. 키 페이로드의 암호화(AES-GCM 봉투)는 전송 중 기밀성을 보호하며, 무결성을 보호하지는 않습니다. 개인 키를 비밀로 취급하고, 기밀성을 제공하지 않는 모든 채널에서는 transport-encryption 봉투를 사용하는 것이 좋습니다.

적합성

진술	사양	절
바이트 범위 다이제스트는 파일 전체를 포함하고 서명 값을 제외합니다.	ISO 32000-2	§12.8.1
`Contents`는 DER로 인코딩된 CMS SignedData를 보관합니다.	ISO 32000-2	§12.8.1
타임스탬프의 경우 바이트 범위 해시가 TSA로 전송되고 토큰이 `Contents`에 배치됩니다.	ISO 32000-2	§12.8.5
B-T 타임스탬프는 SignerInfo의 서명되지 않은 속성입니다.	RFC 5652	§5.3
서명되지 않은 속성은 B-B의 서명된 digest/validity를 변경하지 않습니다.	RFC 5652	§5.3
signature-time-stamp 값은 SignatureTimeStampToken입니다.	ETSI EN 319 122-1	§5.3

NextPDF는 서명 구조를 생성합니다. 생성된 서명이 적합하거나 법적으로 유효하다고 주장하지는 않습니다 — 독립적인 검증기가 판단합니다. B-LT/B-LTA는 이 도구가 생성하지 않습니다.

상업적 맥락

sign_pdf는 Pro 등급 도구이며, 서버 부팅 시 Pro 패키지가 확인될 때만 등록됩니다. PAdES 장기 보존 레벨(B-LT, B-LTA)과 그 검증 자료(DSS, VRI, LTV)는 Enterprise 전용이며 이 도구 또는 이 레시피에서는 노출되지 않습니다.

데이터 상주 및 PII 완화

인증서와 개인 키는 요청을 통해 전달됩니다. 종단 간 기밀성을 제공하지 않는 모든 채널에서는 AES-GCM transport_encryption 봉투를 사용합니다. 서명된 PDF와 서명자 신원(signer_name, reason)은 문서 콘텐츠이므로 데이터 상주 경계 내에 보관하십시오. 배포 수준의 상주는 통합자의 책임입니다.

안전한 텔레메트리 및 로그 정리

private_key 페이로드, AES-GCM key/nonce, 확인 토큰을 절대 로그에 기록하지 마십시오. 알고리즘, 결과 level, signature_count는 로그에 기록하되, 키 자료는 기록하지 마십시오. 이 도구는 결과에 키 바이트를 내보내지 않습니다.

위협 모델

고려된 위협: 전송 중 키 노출(AES-GCM 봉투로 완화), MCP 호출자가 타임스탬프를 임의의 엔드포인트로 지정하는 것(방지됨 — 공급자는 호스트가 주입하며 요청으로 구성할 수 없음), 서명 후 변조(바이트 범위 다이제스트가 수정을 탐지함). 위협 모델은 고려된 위협과 완화책을 문서화하며, 취약점이 없다고 주장하지는 않습니다.

FIPS 모드 동작

알고리즘 선택(RSA-SHA256, RSA + SHA-3, Ed25519)은 요청에 따라 결정되며, 호스트의 OpenSSL이 암호화 기본 요소를 제공합니다. FIPS 제약이 있는 배포에서는 정책 계층에서 알고리즘을 제한하고 호스트의 검증된 모듈에 의존하십시오. 이 도구는 자체적으로 FIPS 검증을 주장하지 않습니다.

트랜스포트 가용성

트랜스포트	사용 가능	참고
MCP(stdio)	예(Pro)	stdio에서는 AES-GCM 키 봉투를 사용하십시오.
REST	예(Pro)	TLS와 키 봉투를 함께 사용하는 것이 좋습니다.
gRPC	예(Pro)	TLS와 키 봉투를 함께 사용하는 것이 좋습니다.

HITL 위험 등급

sign_pdf는 승인 필요 등급입니다(파괴적이고 되돌릴 수 없는 작업 — 도구가 파괴적 힌트를 알립니다). 확인 게이트는 다른 모든 승인 필요 도구와 마찬가지로 적용됩니다. 파일로 쓰는 output_pdf도 승인 필요입니다. base64 모드는 검토 등급입니다(HITL 위험 등급).

확인 게이트 JSON 봉투

유효한 토큰 없이 sign_pdf를 호출하면 챌린지 봉투를 반환합니다:

{
  "allowed": false,
  "challenge": "⚠️ CONFIRMATION REQUIRED\n\nOperation: sign_pdf\nDescription: <tool description>\n\nTo proceed, call sign_pdf again with parameter _confirmation_token: \"confirm_<single-use-hex>\"\nExpires in 300 seconds.",
  "token": "confirm_<single-use-hex>"
}

토큰 값을 _confirmation_token에 설정하여 다시 호출합니다 → { "allowed": true }. 전체 흐름: output-approval.