💡 전체 작업 예제가 GitHub에 있습니다: sign-pdf-with-vault-managed-key-java

이전 방식은 고통스러웠다

Java 서명 서비스용 런북에는 아무도 적고 싶어 하지 않는 단계가 포함되는 경우가 많습니다: signing.pfx를 새 호스트에 복사하고 비밀번호를 환경 변수에 넣는 것입니다. 그 순간부터 개인 키는 의도한 것보다 최소 세 곳에 존재하게 됩니다. 이미지 레이어, 호스트 백업, 그리고 로드하는 JVM 메모리 안에 있으며, 힙 덤프를 통해 덤프를 가진 사람에게 쉽게 노출됩니다.

External signing은 GroupDocs.Signature가 Java용으로 제공하는 기능으로, 애플리케이션이 로드하는 개인 키로 서명하는 대신 제공한 콜백에 문서 다이제스트를 전달합니다. 이는 런북 단계를 삭제할 수 있게 해주는 요소입니다. 서명 키는 HashiCorp Vault로 이동하고, 서비스는 키 대신 토큰을 보관하며, 서명 중에 와이어를 통과하는 유일한 값은 32바이트 해시입니다.

팀은 리뷰에서 “누가 당신을 대신해 서명할 수 있나요?”라는 명백한 질문을 받을 때 이 방법을 사용합니다. 정직한 답은 “그 파일에 접근한 적이 있는 사람이라면 누구든지”입니다. 파일을 권한과 암호화된 볼륨으로 잠그면 위험 창이 좁아지지만 복사를 제거하지는 못합니다.

더 나은 방법이 있다

Vault의 Transit 엔진은 암호화를 서비스 형태로 제공합니다. 값을 보내면 Vault가 보유한 키로 서명하고 결과를 반환합니다. Transit 내부에서 생성된 키는 내보낼 수 없도록 표시할 수 있어, 처음부터 호스트에 복사할 것이 전혀 없으며 Vault는 전송된 데이터를 저장하지도 않습니다.

이는 서명 라이브러리가 위임할 수 있을 때만 도움이 되며, 바로 GroupDocs.Signature가 등장합니다. DigitalSignOptions.setCustomSignHash는 콜백을 받습니다. 라이브러리는 암호화 이전의 모든 작업을 수행합니다: PDF를 열고, 서명이 차지하는 바이트 범위를 계산하고, 해시를 만든 뒤, 다이제스트와 함께 콜백을 호출하고, 반환된 바이트를 인증서와 함께 삽입합니다.

JDK 8 이상, Maven, 로컬 Vault용 Docker, 그리고 인증서를 위한 BouncyCastle이 필요합니다. 샘플은 GroupDocs.Signature for Java 26.10으로 실행됩니다; 라이선스 없이 평가 모드에서는 최대 2페이지 문서를 허용합니다.

새로운 방법: 키 파일 대신 콜백

단계 1 - Vault에서 키 읽기

서비스는 사용이 허가된 키를 요청하고 공개 키와 함께 버전 번호를 받습니다. 개인 키 절반은 응답에 절대 포함되지 않습니다.

VaultKey key = vault.readKey(KEY_NAME);
if (key == null) {
    vault.enableTransit();
    vault.createKey(KEY_NAME, "rsa-2048");
    key = vault.readKey(KEY_NAME);
}

Vault에서 404가 반환되면 키 또는 Transit 마운트가 없다는 의미이므로 샘플에서는 이를 첫 실행 설정으로 처리합니다. 실제 운영에서는 관리자가 미리 Transit을 활성화하고 키를 생성하며, 애플리케이션 토큰은 두 작업을 수행할 권한이 없습니다.

버전을 한 번 읽어두고 유지하십시오. 인증서는 정확히 하나의 공개 키만 보유하므로 인증서와 모든 서명은 동일한 버전에서 나와야 합니다.

단계 2 - 공개 키를 기반으로 인증서 만들기

PDF 서명은 검증자가 공개 키를 찾을 수 있도록 X.509 인증서를 포함합니다. JDK에는 외부 서명을 사용해 인증서를 만드는 방법이 없지만 BouncyCastle은 가능합니다: X509v3CertificateBuilder가 ContentSigner에 위임하고, Vault를 백엔드로 하는 ContentSigner는 약 15줄 정도입니다.

@Override
public byte[] getSignature() {
    try {
        byte[] digest =
            MessageDigest.getInstance("SHA-256").digest(data.toByteArray());
        return vault.signHash(keyName, keyVersion, digest, "sha2-256");
    } catch (IOException e) {
        throw new UncheckedIOException(e);
    }
}

BouncyCastle은 서명될 바이트를 서명자 스트림에 기록한 뒤 서명을 요청합니다. 바이트는 로컬에서 해시되고 다이제스트만 Vault로 전송됩니다. 인터페이스는 체크 예외를 선언하지 않으므로 Vault 오류가 발생하면 래핑되어 호출자에게 전달되어야 합니다. 이를 무시하면 Vault의 403 오류가 난해한 런타임 오류로 나타납니다.

단계 3 - 서명하고 같은 실행에서 검증

DigitalSignature digitalSignature = new DigitalSignature();
digitalSignature.setX509Certificate(certificate);

DigitalSignOptions options = new DigitalSignOptions();
options.setSignature(digitalSignature);
options.setCustomSignHash(signer::customSignHash);
options.setHashAlgorithm(HashAlgorithm.Sha256);

ByteArrayOutputStream signedPdf = new ByteArrayOutputStream();
signature.sign(signedPdf, options);
Files.write(outputPdf, trimTrailingZeros(signedPdf.toByteArray()));

콜백 내부에서 다이제스트는 transit/sign으로 전송되며, 두 필드가 결과의 유효성을 결정합니다: prehashed = true(입력이 이미 해시이기 때문)와 signature_algorithm = pkcs1v15(Vault는 RSA 키에 대해 기본적으로 PSS를 사용하지만 PDF 서명은 sha256WithRSAEncryption이기 때문).

파일이 어디든 전송되기 전에 검증하십시오. 한 번의 실행에서 서명과 검증을 수행하면 유일한 무음 실패 모드가 즉시 오류로 전환됩니다.

비교: 이전 vs. 이후

호스트의 PFX Vault Transit 콜백
개인 키 복사본 호스트당 하나, 이미지와 백업에 하나, Vault 내부에
서비스가 보유하는 것 키와 비밀번호 두 작업에 제한된 토큰
새 호스트 배포 단계 PFX 복사, 비밀번호 설정 없음
각 서명의 기록 애플리케이션 로그(작성된 경우) Vault 감사 항목 하나
누출 의심 후 키 폐기, 재발급, 전부 재배포 Vault에서 회전, 한 번 재발급
누가 당신을 대신해 서명할 수 있는가 파일과 비밀번호를 가진 사람 유효한 Vault 토큰을 가진 사람

마지막 행은 명확히 말할 가치가 있습니다: 이는 비밀을 없애는 것이 아니라 이동시키는 것입니다. 차이점은 토큰이 단명하고, 한 곳에서 폐기 가능하며, 하나의 키를 읽고 서명 호출만 할 수 있도록 제한되고, 사용될 때마다 로그가 남는다는 점입니다.

실제 사례: 명세서 서비스

서비스는 월간 명세서를 생성하고 고객 포털에 배포하기 전에 각각 서명합니다. 이전 방식에서는 컨테이너 이미지에 인증서가 포함되고, 파일을 회전시켜야 했기 때문에 세 사람이 비밀번호를 가지고 있었습니다. 콜백을 사용하면 이미지에 비밀이 전혀 포함되지 않습니다: 포드는 시작 시 AppRole 토큰을 받고, vault/sample-signer.hcl 정책이 키 읽기와 서명을 허용하며, 토큰이 다른 작업을 시도하면 403 permission denied가 반환됩니다.

감사자가 3월에 몇 개의 문서가 서명되었고 어떤 키 버전으로 서명되었는지 물으면, 답은 Vault 감사 장치에서 나오며 애플리케이션 로그를 검색할 필요가 없습니다.

회전은 이 설계가 가치를 발휘하는 동시에 위험이 될 수 있는 부분입니다. transit/keys/:name/rotate 이후 Vault는 별도로 지정하지 않는 한 최신 버전으로 서명합니다. 따라서 버전 1용으로 만든 인증서와 버전 2 서명을 조합하면 오류가 없고 검증도 통과하는 PDF가 생성됩니다. 서명자는 하나의 버전으로만 구성되므로 여기서는 실수로 발생하지 않습니다: 명세서 서비스는 인증서가 속한 버전으로 계속 서명하고, 누군가 새 버전용 인증서를 발행할 때까지는 그렇습니다. 이후 키에 min_encryption_version을 설정하면 이전 버전은 사용할 수 없게 되고, Vault는 서명을 거부한다는 형태로 응답합니다.

버전 26.10에서 예상되는 특이 사항은 무엇인가요?

네 가지가 모두 이 빌드를 실행하면서 발견되었습니다. ICustomSignHash 메서드 이름이 JAR에서 난독화되어 있으므로 인터페이스를 구현하기보다 메서드 레퍼런스를 전달하십시오. 서명된 출력에는 서명 외부에 뒤쪽에 0 바이트가 포함되므로 이를 제거해야 합니다. DigitalVerifyOptions는 스트림이 아니라 인증서 파일을 요구합니다. 그리고 보이는 서명 박스는 Arial 폰트가 설치되어 있어야 합니다.

GroupDocs.Signature로 할 수 있는 다른 일은 무엇인가요?

콜백은 뒤에 무엇이 있는지 알 수 없으므로 동일한 세 단계를 하드웨어 모듈, 스마트 카드 또는 클라우드 KMS에서도 사용할 수 있습니다. 저는 이 샘플을 .NET 및 Python 버전에서 포팅했으며, Vault 요청 본문은 그대로 전달되었습니다; 인증서 구성과 위 네 가지 특이 사항만이 진정한 Java 전용 부분입니다. 디지털 서명 외에도 이 라이브러리는 PDF, Word, Excel, PowerPoint 및 이미지 형식 전반에 걸쳐 텍스트, 이미지, 바코드, QR 코드 및 메타데이터 서명을 추가하고 검색할 수 있습니다.

결론

Java에서 개인 키를 보관하지 않고 PDF에 서명하려면 콜백, 공개 키 기반 인증서, 두 가지 권한을 가진 토큰이 필요합니다. 샘플은 개발 모드 Vault를 두 명령으로 실행하며, VAULT_ADDR와 VAULT_TOKEN을 변경하면 동일한 코드가 프로덕션 Vault를 가리키게 됩니다.

추가 자료