HSM을 사용하여 C#으로 PDF에 디지털 서명하는 방법

IronPDF는 PKCS#11 API를 통해 하드웨어 보안 모듈(HSM)을 사용하여 안전한 PDF 서명을 지원합니다. 개인 키는 물리적 장치를 벗어나지 않으므로 변조 방지 디지털 서명이 필요한 핵심 애플리케이션에 은행 수준의 보안을 제공합니다.

빠른 시작: C#에서 HSM을 사용하여 PDF에 서명하기

1. NuGet을 통해 IronPDF를 설치하세요: Install-Package IronPdf
2. HSM 장치를 구성하십시오(또는 SoftHSM을 사용하여 테스트하십시오).
3. HSM 자격 증명을 사용하여 UsbPkcs11HsmSigner를 생성하십시오.

   지금 바로 NuGet을 사용하여 PDF 만들기를 시작하세요.

   1. NuGet 패키지 관리자를 사용하여 IronPDF를 설치하세요.

      PM > Install-Package IronPdf

   2. 다음 코드 조각을 복사하여 실행하세요.

      var hsmSigner = new UsbPkcs11HsmSigner(libraryPath, pin, tokenLabel, keyLabel);

   3. 실제 운영 환경에서 테스트할 수 있도록 배포하세요.

      지금 바로 무료 체험판을 통해 프로젝트에서 IronPDF를 사용해 보세요.

      

      30일 무료 체험
4. PDF 파일을 생성하고 서명하세요.

   var pdf = renderer.RenderHtmlAsPdf("<h1>Document</h1>");
   pdf.SignAndSave("signed.pdf", hsmSigner);

   var pdf = renderer.RenderHtmlAsPdf("<h1>Document</h1>");
   pdf.SignAndSave("signed.pdf", hsmSigner);

   $vbLabelText   $csharpLabel
5. PDF 뷰어에서 서명을 확인하십시오.

PDF 문서에 서명을 추가하는 것은 많은 애플리케이션에서 흔히 요구되는 사항입니다. 하지만 핵심 임무 수행에 필수적인 애플리케이션은 키를 변조할 수 없는 더욱 높은 수준의 보안이 필요합니다. .pfx 파일을 사용한 일반적인 서명 작업은 마치 집에 마스터 키를 가지고 있는 것과 같습니다. 애플리케이션은 문서에 서명하기 위해 키를 메모리에 로드합니다. 컴퓨터가 해킹당하면 키가 도난당할 수 있습니다.

보다 안전한 대안은 하드웨어 보안 모듈(HSM)을 사용하는 것입니다. HSM(예: USB 토큰)의 경우 개인 키는 장치 내부에서 생성되며 장치 외부로 유출될 수 없습니다.

이 과정은 마치 서류를 은행에 가져가는 것과 같습니다. 애플리케이션이 PIN을 제공하면 HSM이 문서를 금고로 가져가 키로 도장을 찍고 도장이 찍힌 문서를 반환합니다. 열쇠는 절대 금고 밖으로 나가지 않는다. 이는 키를 복제하거나 도난당할 수 없으므로 추가적인 보안을 제공합니다.

:path=/static-assets/pdf/content-code-examples/how-to/signing-with-hsm.cs

using IronPdf;
using IronPdf.Signing;
using IronSoftware.Pdfium.Signing;
using System.Drawing;

ChromePdfRenderer renderer = new ChromePdfRenderer();
PdfDocument pdf = renderer.RenderHtmlAsPdf("<h1>Testing</h1>");

// Define Paths and Credentials
string softhsmLibraryPath = @"D:\SoftHSM2\lib\softhsm2-x64.dll";
// These MUST match what you created
string hsmTokenLabel = "MyTestToken";
string hsmPin = "123456";
string hsmKeyLabel = "my-key"; // The label for the key *inside* the token

// Create the HsmSigner object.
UsbPkcs11HsmSigner hsmSigner = new UsbPkcs11HsmSigner(
    softhsmLibraryPath,
    hsmPin,
    hsmTokenLabel,
    hsmKeyLabel
);

// Create the Signature Image
string signatureImagePath = "IronSoftware.png";
PdfSignatureImage sigImage = new PdfSignatureImage(signatureImagePath, 0, new Rectangle(50, 50, 150, 150));

// Sign PDF with HSM
pdf.SignAndSave("signedWithHSM.pdf", hsmSigner);

// Configure with custom algorithms
var customHsmSigner = new UsbPkcs11HsmSigner(
    hsmLibraryPath,
    hsmPin,
    hsmTokenLabel,
    hsmKeyLabel,
    digestAlgorithm: IronPdf.Signing.DigestAlgorithm.SHA512,
    signingAlgorithm: IronPdf.Signing.SigningAlgorithm.RSA
);

// Apply signature with custom location and reason
var signatureOptions = new SignatureOptions
{
    SignerName = "Corporate Signing Authority",
    Location = "Company Headquarters",
    Reason = "Contract Approval"
};

// Load existing PDF for signing
var existingPdf = PdfDocument.FromFile("contract.pdf");
existingPdf.SignAndSave("contract-signed.pdf", customHsmSigner, signatureOptions);

// Configure with custom algorithms
var customHsmSigner = new UsbPkcs11HsmSigner(
    hsmLibraryPath,
    hsmPin,
    hsmTokenLabel,
    hsmKeyLabel,
    digestAlgorithm: IronPdf.Signing.DigestAlgorithm.SHA512,
    signingAlgorithm: IronPdf.Signing.SigningAlgorithm.RSA
);

// Apply signature with custom location and reason
var signatureOptions = new SignatureOptions
{
    SignerName = "Corporate Signing Authority",
    Location = "Company Headquarters",
    Reason = "Contract Approval"
};

// Load existing PDF for signing
var existingPdf = PdfDocument.FromFile("contract.pdf");
existingPdf.SignAndSave("contract-signed.pdf", customHsmSigner, signatureOptions);

HSM 구성에서 흔히 발생하는 문제는 무엇입니까?

코드 예제를 실행하는 동안 아래와 같은 오류가 발생하는 경우, 다음 문제 해결 단계를 따라 디버깅하고 구성을 확인하십시오. 디지털 서명 관련 문제에 대한 추가 지원이 필요하시면 디지털 서명 문제 해결 가이드를 참조하십시오.

이 CKR_GENERAL_ERROR 오류는 일반적으로 프로그램이 SoftHSM 구성 파일을 찾을 수 없거나 .NET 애플리케이션이 32비트 프로세스로 실행되는 반면 SoftHSM 라이브러리는 64비트인 경우에 발생합니다.

플랫폼 대상 변경

이 오류의 일반적인 원인은 아키텍처 불일치입니다. C# 애플리케이션은 64비트 SoftHSM 라이브러리(softhsm2-x64.dll)와 호환되도록 64비트 프로세스로 실행되어야 합니다. Visual Studio 프로젝트 속성에서 플랫폼 대상을 '모든 CPU' 또는 'x86'에서 x64로 변경하여 호환성을 확보하십시오.

환경 변수 설정

또 다른 일반적인 원인은 프로그램이 SoftHSM에서 .conf 파일을 찾을 수 없다는 것입니다. 라이브러리가 어디를 찾아야 하는지 시스템 전체 환경 변수를 설정하여 알려줘야 합니다. SOFTHSM2_CONF라는 이름의 새 변수를 생성하고 해당 변수의 값을 구성 파일의 전체 경로(예: D:\SoftHSM2\etc\softhsm2.conf)로 설정하십시오. 변경 사항을 적용한 후에는 Visual Studio를 다시 시작하는 것을 잊지 마세요.

또한, 다음 줄을 추가하여 변수가 발견되었는지 확인할 수 있습니다.

Console.WriteLine($"Verifying variable: {Environment.GetEnvironmentVariable("SOFTHSM2_CONF")}");

Console.WriteLine($"Verifying variable: {Environment.GetEnvironmentVariable("SOFTHSM2_CONF")}");

$vbLabelText   $csharpLabel

콘솔 출력이 비어 있으면 프로그램이 환경 변수를 찾을 수 없는 것입니다. 설정을 변경한 후 Visual Studio 또는 컴퓨터를 다시 시작하고 다시 시도하십시오.

프로덕션 HSM 배포를 위한 모범 사례

HSM으로 서명된 PDF 파일을 운영 환경에 배포할 때는 다음과 같은 추가 보안 조치를 고려하십시오.

1. 감사 로깅 : 규정 준수를 유지하고 접근 권한을 추적하기 위해 모든 HSM 작업에 대한 포괄적인 로깅을 구현합니다.
2. 인증서 관리 : 조직의 보안 정책에 따라 인증서를 정기적으로 업데이트하고 교체하십시오.
3. 백업 절차 : HSM 구성에 대한 적절한 백업 및 복구 절차를 수립하십시오.
4. 성능 최적화 : 서명 성능을 모니터링하고 자주 액세스하는 인증서에 대한 캐싱 전략을 구현합니다.

이러한 관행은 표준 PDF 서명 워크플로를 보완하고 문서 보안 인프라가 견고하고 업계 표준을 준수하도록 보장합니다.