THotPDF.SignPDFWithPFX 메서드

THotPDF.SignPDFWithPFX

PFX / PKCS#12 파일을 사용해 기존 PDF 플레이스홀더에 서명합니다. 자격 증명 ID 하나를 결정적으로 선택하고, 사용 가능한 인증서 체인을 포함한 CMS SignedData 컨테이너를 만든 뒤, 서명된 PDF를 한 번의 호출로 기록합니다

Delphi syntax (file overload):

class function SignPDFWithPFX(

const InputPDFPath: string;

const OutputPDFPath: string;

const PFXFilePath: string;

const Password: AnsiString): boolean; overload; static;

Delphi syntax (stream overload):

class function SignPDFWithPFX(

InputStream: TStream;

OutputStream: TStream;

const PFXFilePath: string;

const Password: AnsiString): boolean; overload; static;

Description

SignPDFWithPFX는 v2.119.27에서 추가된 end-to-end PFX 서명 진입점입니다. 입력 PDF에는 THPDFPage.AddSignedSignatureField(또는 그 PAdES 래퍼)가 출력한, subFilter가 adbe.pkcs7.detached인 서명 플레이스홀더가 이미 있어야 합니다. 이 메서드는 다음 순서로 동작합니다.

1. 입력을 bounded 256 KB 버퍼로 복사하거나 같은 seekable 읽기/쓰기 스트림을 재사용하고, /ByteRange + /Contents 플레이스홀더를 찾아 고정 폭 /ByteRange 필드를 실제 바이트 오프셋으로 seek-patch합니다

2. PFX 파일을 로드하고 전달된 패스워드로 복호화합니다. PBES2는 AES-128-CBC, AES-192-CBC, AES-256-CBC와 기본 HMAC-SHA-1 또는 명시적 HMAC-SHA-256, HMAC-SHA-384, HMAC-SHA-512 PBKDF2 PRF를 받습니다. 선택 사항인 PBKDF2 keyLength는 선택된 AES 암호와 일치해야 하며, 오래된 인증서 내보내기 파일을 위해 레거시 PBE-SHA1-3DES 파일도 계속 지원합니다. 그 밖의 암호화 프로필은 문제가 된 OID와 함께 진단 예외를 발생시킵니다

3. 공개 키 자료와 정확한 RFC 2985 localKeyId 값으로 RSA, named-curve ECDSA, Ed25519, Ed448 개인 키를 인증서와 짝지은 다음, 발급자 / 주체 이름과 Authority Key Identifier / Subject Key Identifier 확장을 따라가며 확보 가능한 중간 인증서와 루트 체인을 보존합니다

4. 매칭된 키에서 서명 방식을 선택하고, 필요한 문서 digest를 계산한 뒤, 서명자 인증서, 중복 DER 인증서가 없는 매칭 체인, signed attribute를 담은 CMS SignedData(RFC 5652) DER blob을 만듭니다. RSA와 ECDSA는 attribute digest에 서명하고, Ed25519와 Ed448은 PureEdDSA 모드에서 전체 DER SET OF attribute에 서명합니다. Ed25519는 SHA-512를, Ed448은 512비트 출력의 SHAKE256과 id-shake256-len을 사용합니다

5. CMS DER을 16진수로 인코딩하고, AddSignedSignatureField가 예약해 둔 /Contents 공간에 들어가는지 확인(기본 8 KB로 1024 / 2048비트 RSA를 수용)한 뒤 플레이스홀더에 삽입

6. 패치된 바이트를 출력 경로 또는 스트림에 기록

성공하면 True를 반환합니다. 암호가 틀렸거나, 지원되지 않는 암호화 또는 개인 키 프로파일이거나, PFX 형식이 잘못되었거나, ID나 발급자가 모호하거나, 인증서 체인에 순환이 있으면 EHPDFPFXError를 발생시킵니다. 입력 PDF에 필요한 플레이스홀더가 없거나, 선택적 EdDSA provider를 사용할 수 없거나, 서명에 실패하거나, CMS DER이 예약된 /Contents 공간을 넘치면 EHPDFCMSError를, RSA 키가 일치하지 않으면 EHPDFRSAError를 발생시킵니다

Typical workflow

Doc := THotPDF.Create(nil);

Doc.FileName := 'unsigned.pdf';

Doc.BeginDoc;

Doc.CurrentPage.AddSignedSignatureField(

'Sig1', Rect(60, 60, 260, 90), 8192,

'adbe.pkcs7.detached', 'Approved', 'Brussels', '', []);

Doc.EndDoc;

Doc.Free;

THotPDF.SignPDFWithPFX('unsigned.pdf', 'signed.pdf', 'mykey.pfx', 'mypassword');

Multi-identity PFX files

편의 오버로드는 일치하는 인증서와 개인 키가 둘 이상 들어 있는 PFX를 의도적으로 거부합니다. HPDFEnumeratePFXIdentities를 호출하면 결정적 순서의 ID 목록과 각 항목의 LocalKeyID, FriendlyName 필드를 확인할 수 있고, 선택한 키 자료만 필요하다면 HPDFParsePFXByLocalKeyID를 호출하면 됩니다

엔드 투 엔드 서명을 하려면 THPDFCMSSignOptions를 HPDFCMSDefaultSignOptions로 초기화하고, 선택한 옥텟 값을 그대로 Options.PFXLocalKeyID에 복사한 다음, 이 옵션을 받는 HPDFCMSSignPDFStream 오버로드를 호출합니다. 선택된 리프 인증서, 사용 가능한 중간 인증서와 루트 인증서는 자동으로 포함되며, 호출자가 넘긴 Options.AdditionalCertsDER 값은 DER이 완전히 같은 항목의 중복을 제거한 뒤 병합됩니다

Notes

RSA와 ECDSA PFX 서명은 HotPDF 내장 경로와 Windows 암호화 경로를 사용합니다. Ed25519와 Ed448 PFX 서명에는 OpenSSL 3 libcrypto가 필요합니다. HPDFCMSSignPDFStream을 직접 호출하는 경우 THPDFCMSSignOptions.OpenSSLLibraryPath를 지정할 수 있고, 편의 오버로드는 플랫폼 기본 라이브러리 검색 경로를 사용합니다

서명 알고리즘은 RSA + SHA-256(1.2.840.113549.1.1.1 + 2.16.840.1.101.3.4.2.1)입니다. 서명자 식별자는 X.509 인증서에서 추출한 IssuerAndSerialNumber이고, encapContentInfo는 분리형(eContent 생략)입니다. 서명된 속성은 해시하기 전에 RFC 5652 5.4절에 따라 DER 바이트 문자열의 오름차순으로 정렬됩니다

RFC 3161 타임스탬프, DSS 딕셔너리, 문서 타임스탬프 서명이 필요한 PAdES B-T / B-LT / B-LTA 워크플로에서는 producer 쪽 헬퍼(AddPAdESSignatureField, AddPAdESDSSCertificate, AddDocumentTimestampSignature)를 그대로 사용합니다. SignPDFWithPFX 자체는 기본적인 CMS 전용 서명(PAdES-B-B에 해당)만 생성합니다

스트림 오버로드는 완성된 PDF 사본을 메모리에 통째로 두지 않습니다. 패치된 출력을 제한된 크기의 구간 단위로 해시하고, 파일 길이를 바꾸지 않은 채 16진수 CMS 값을 seek 방식으로 패치합니다. 고정 폭 10진수 오프셋을 쓰므로 10,000,000,000바이트 미만의 준비된 PDF를 지원합니다