서명자 플러그인

PDF와 Word 문서를 눈에 보이는 서명과 디지털 봉인으로 서명합니다

Signer 플러그인은 문서에 눈에 보이는 서명을 삽입하고 기본적으로 PDF 리더가 검증할 수 있는 디지털 서명으로 봉인합니다. PDF와 Word (.docx) 파일에 서명합니다. 눈에 보이는 서명은 항상 PNG 이미지이며, 서명자가 직접 그리거나 입력하거나 업로드합니다.

구분사용 상황
DocumentSigner (C#)서버에서 서명하며, 브라우저가 관여하지 않습니다
Drop-in widget (doconutSigner.js)페이지에 바로 사용할 수 있는 업로드, 서명 및 다운로드 화면을 원할 때
HTTP endpoints on DocImage.axd (?sign=open|run|download)문서화된 서버 계약에 맞춰 자체 서명 UI를 구축하고자 할 때

각 서명은 한 페이지에 한 번만 배치됩니다. 서명자의 이름, 사유 및 위치 정보가 함께 저장됩니다.

패키지 설치

powershell
Install-Package Doconut.NETFramework.Signer

이 문서에서 설명하는 릴리스에 플러그인을 고정하려면:

powershell
Install-Package Doconut.NETFramework.Signer -Version 26.10.0

Signer 패키지를 Doconut.NETFramework와 동일한 버전으로 유지하십시오.

플러그인의 라이선스 파일인 Doconut.Viewer.Signer.lic은 Doconut.Viewer.lic와 같은 폴더에 두며, 뷰어 라이선스와 함께 읽힙니다.

플러그인 등록

모든 Doconut 플러그인과 마찬가지로, Signer는 AddPlugin<TPlugin>()를 DoconutHost.Initialize에 등록하고, 이는 Application_Start에서 호출됩니다:

csharp
Doconut.DoconutHost.Initialize(options =>
{
    options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
    options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
});

Doconut.DoconutHost.Shutdown()를 Application_End에 추가하면 앱 풀 재시작 시 백그라운드 작업이 깔끔하게 중지됩니다.

C# 페이사드에 필요한 것은 이것뿐입니다. 위젯과 해당 HTTP 엔드포인트는 별도의 선택 사항이며, AddSignerWidget()입니다 (위젯 삽입 참고).

플러그인은 Signer 기능을 부여하는 라이선스가 필요합니다. 라이선스가 없으면 DoconutHost.Initialize가 Application_Start에서 예외를 발생시킵니다:

text
The Signer plugin is registered via AddPlugin but no active license grants Signer. Remove the AddPlugin<...>() call or install a license (or trial/demo) that includes Signer.

System.Web에서는 모든 요청이 빈 500를 반환하며, 이유는 Windows 이벤트 로그(소스 ASP.NET)에만 기록됩니다. 라이선스가 없거나, 레거시 TRIAL 파일이 있거나, Signer이 없는 라이선스이거나, 버전 기간 외에 사용된 유료 라이선스인 경우 예외가 발생합니다. 임시 Demo/NFR 라이선스도 허용됩니다. 라이선스 설정 을 참고하십시오.

라이선스 및 워터마크

라이선스 상태시작 시인증 서명시각적 서명
Signer를 부여하는 유료 라이선스, 인증서 구성됨시작귀하의 인증서로 봉인, 깨끗함 (watermarked: false)깨끗함
Signer를 부여하는 유료 라이선스, 인증서 없음시작거부: No signing certificate configured.깨끗함
유료 라이선스, 인증서 만료 또는 아직 유효하지 않음시작거부: The signing certificate expired on yyyy-MM-dd.깨끗함
임시 Demo/NFR 라이선스, 활성 또는 만료시작내장 데모 인증서로 봉인, 워터마크 적용 (watermarked: true)워터마크 적용
라이선스 없음, 레거시 TRIAL 파일, Signer이 없는 라이선스, 또는 버전 기간 외의 유료 라이선스Application_Start가 예외 발생; 모든 요청이 빈 500 반환——

C# 페이사드와 위젯 모두 동일한 규칙을 적용합니다: 라이선스가 유료 뷰어 라이선스가 아니거나 임시인 경우 출력에 워터마크가 붙습니다. 임시 라이선스에서는 플러그인이 항상 내장 데모 인증서로 서명하며, 사용자가 설정한 인증서는 사용되지 않습니다.

데모 인증서는 실제 봉인을 생성하지만 PDF 리더에서는 신뢰하지 않습니다. 평가용 라이선스로 통합을 구축하고 끝까지 테스트할 수 있습니다; 깨끗하고 신뢰할 수 있는 출력을 얻으려면 유료 라이선스와 자체 서명 인증서가 모두 필요합니다.

C#에서 사용하기

DocumentSigner 은 DoconutHost.Initialize 에 의해 등록됩니다; DoconutHost.Services 로부터 해결하십시오. 생성자는 internal이므로 절대 new 하지 마세요. AddPlugin<SignerPlugin>() 없이 해결하면 No IDocumentSigner is registered. Add the signing plugin: options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>(). 가 발생합니다.

csharp
using Doconut;
using Doconut.Core.Models.Signing;

public sealed class ContractSigning
{
    private readonly DocumentSigner _signer;

    public ContractSigning(DocumentSigner signer) => _signer = signer;

    public async Task<byte[]> SignAsync(Stream pdf, byte[] signaturePng, SigningCertificate certificate, CancellationToken ct)
    {
        var request = new SignRequest(
            new VisibleSignature(SignatureKind.Drawn, signaturePng),
            new SignaturePlacement(Page: 1, X: 0.58, Y: 0.80, W: 0.32, H: 0.12),
            SignerName: "Ada Lovelace",
            Reason: "I approve this document",
            Location: "London, UK");
        // Mode는 Certified (보이는 서명 + 디지털 씰)으로 기본값이 설정됩니다; WordOutput는 Pdf로 기본값이 설정됩니다.

        SignResult result = await _signer.SignAsync(pdf, ".pdf", request, certificate, ct);
        using (result.Stream)
        using (var output = new MemoryStream())
        {
            await result.Stream.CopyToAsync(output, 81920, ct);
            return output.ToArray();
        }
    }
}

SignAsync 은 소스 스트림, 해당 확장자(".pdf" 또는 ".docx"), 요청 및 인증서 이 호출에 대한 를 받습니다. 파사드는 SignerWidgetOptions.SigningCertificate 을 읽지 않으며; 해당 설정은 위젯용입니다. 데모 라이선스 하에서 또는 Visual 모드에서 null 를 전달하십시오.

SignResult 은 서명된 문서를 탐색 가능한 스트림으로 보관하고, 파일 이름을 지정할 수 있도록 그 Extension (".pdf" 또는 ".docx") 를 포함합니다. 스트림은 여러분이 소유합니다: 사용이 끝나면 폐기하십시오.

MVC 5 컨트롤러에서

액션을 비동기로 만들고 서명을 await 하세요. 이 경우 Visual 서명을 찍으며, 인증서가 필요하지 않습니다:

csharp
[HttpPost]
public async Task<ActionResult> Sign(HttpPostedFileBase file)
{
    var signer = Doconut.DoconutHost.Services.GetRequiredService<DocumentSigner>();
    byte[] signaturePng = System.IO.File.ReadAllBytes(Server.MapPath("~/App_Data/signature.png"));

    var request = new SignRequest(
        new VisibleSignature(SignatureKind.Image, signaturePng),
        new SignaturePlacement(Page: 1, X: 0.58, Y: 0.80, W: 0.32, H: 0.12),
        Mode: SignatureMode.Visual);

    SignResult result = await signer.SignAsync(
        file.InputStream, Path.GetExtension(file.FileName), request, ct: Response.ClientDisconnectedToken);
    string contentType = result.Extension == ".pdf"
        ? "application/pdf"
        : "application/vnd.openxmlformats-officedocument.wordprocessingml.document";
    return File(result.Stream, contentType, Path.GetFileNameWithoutExtension(file.FileName) + "-signed" + result.Extension);
}

Word 소스는 Word 출력 요청이 없으면 PDF로 서명됩니다. 결과 이름을 result.Extension 로부터 지정하십시오:

csharp
var signer = Doconut.DoconutHost.Services.GetRequiredService<DocumentSigner>();
byte[] signaturePng = File.ReadAllBytes(HostingEnvironment.MapPath("~/App_Data/signature.png"));

var request = new SignRequest(
    new VisibleSignature(SignatureKind.Drawn, signaturePng),
    new SignaturePlacement(Page: 1, X: 0.58, Y: 0.80, W: 0.32, H: 0.12),
    WordOutput: WordOutput.Docx);

SignResult result = await signer.SignAsync(stream, ".docx", request, ct: ct);
string downloadName = "contract-signed" + result.Extension;   // ".docx"

SignAsync 은 호출이 성공하지 못할 경우 반환 대신 예외를 발생시킵니다:

예외메시지언제
InvalidOperationExceptionNo signing certificate configured.인증 모드, 유료 라이선스, 그리고 인증서가 전달되지 않은 경우
InvalidOperationExceptionThe signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd.인증 모드이며 인증서가 유효 기간 외인 경우
ArgumentExceptionThe sign request is invalid: the visible signature needs PNG bytes and the placement must be a normalized rectangle on a 1-based page.빈 PNG 바이트이거나, 유효하지 않은 배치인 경우
NotSupportedExceptionThe signer supports PDF and Word (.docx) documents; got '{extension}'.기타 모든 소스 유형

서명 모드, Word 출력 및 인증서

서명 모드

SignRequest.Mode 은(는) 서명이 봉인되는지를 선택합니다.

모드생성 내용인증서검증 가능
SignatureMode.Certified (기본값)보이는 서명과 디지털 봉인유료 라이선스 하에 필요예
SignatureMode.Visual보이는 서명만절대 필요 없음아니오: 그림입니다

서명이 입증 가능해야 할 때는 Certified 를 사용하십시오: 승인, 계약, 검증자가 신원 및 무결성을 확인해야 하는 모든 것. 서명의 외관만 필요하거나 인증서가 없을 때는 Visual 를 사용하십시오. 임시 라이선스는 두 경우 모두에 워터마크를 추가합니다.

PDF 봉인은 RSA 또는 ECDSA 키용 SHA-256을 사용한 PKCS#7 분리 서명(adbe.pkcs7.detached)입니다. 이는 PFX에 포함된 발급자 인증서를 포함하므로, 루트를 신뢰하는 리더가 체인을 구축할 수 있습니다. Word 네이티브 봉인은 OOXML 패키지 서명이며 서명자 인증서만 포함합니다.

Word 문서

.docx 소스에 대해, SignRequest.WordOutput 가 출력 형식을 선택합니다. PDF 소스에 대해서는 무시되며, 항상 PDF가 생성됩니다.

출력무슨 일이 일어나는가검증자 지원
WordOutput.Pdf (기본값)문서가 PDF로 변환된 뒤 서명 및 봉인됩니다광범위: 서명된 PDF가 모든 곳에서 검증됩니다
WordOutput.Docx문서가 Word 형태를 유지합니다: 서명 이미지가 삽입되고 OOXML 패키지 서명이 추가됩니다제한적: 모든 뷰어가 OOXML 패키지 서명을 표시하지는 않습니다

수신자가 편집 가능한 Word 파일이 필요하고 제한된 검증자 지원을 수용한다면 제외하고, 그렇지 않으면 PDF를 유지하십시오.

인증서 설정

자신의 신원으로 봉인하려면, 개인 키를 포함한 PFX (PKCS#12) 파일을 플러그인에 제공하십시오. 위젯의 경우 SignerWidgetOptions.SigningCertificate 를 설정하고, C# 파사드의 경우 인증서를 SignAsync 에 전달합니다. 바이트 배열이나 경로와 비밀번호를 제공하십시오. IIS가 절대 제공하지 않기 때문에 파일을 저장하기에 App_Data 가 좋은 위치입니다:

csharp
Doconut.DoconutHost.Initialize(options =>
{
    options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
    options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
    options.AddSignerWidget(widget =>
    {
        widget.SigningCertificate = new SigningCertificate
        {
            PfxBytes = File.ReadAllBytes(HostingEnvironment.MapPath("~/App_Data/signing.pfx")),
            Password = System.Configuration.ConfigurationManager.AppSettings["DoconutSigner:Password"] ?? "",
        };
    });
});
csharp
Doconut.DoconutHost.Initialize(options =>
{
    options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
    options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
    options.AddSignerWidget(widget =>
    {
        widget.SigningCertificate = new SigningCertificate
        {
            PfxPath = HostingEnvironment.MapPath("~/App_Data/signing.pfx"),
            Password = System.Configuration.ConfigurationManager.AppSettings["DoconutSigner:Password"] ?? "",
        };
    });
});

SigningCertificate 의 속성은 init-only이며, .NET Framework 프로젝트의 기본값인 C# 7.3에서는 설정할 수 없습니다. 프로젝트 파일에서 <LangVersion> 를 9.0 이상으로 설정하십시오.

인증서는 메모리 내에만 보관됩니다. 로그에 기록되거나 클라이언트에 반환되거나 영구 저장되지 않으며, 비밀번호는 오류 메시지에 절대 표시되지 않습니다.

요구 사항:

  • 개인 키가 포함된 PFX / PKCS#12 번들. 공개키 전용 파일(.cer, .crt)은 서명할 수 없습니다. 발급자 체인을 함께 내보내어 PDF 봉인이 이를 포함하도록 하십시오.
  • 올바른 비밀번호.
  • 유효 기간 내에 있어야 합니다. 만료되었거나 아직 유효하지 않은 인증서는 애플리케이션을 중단시키지 않지만, Certified 서명은 교체될 때까지 거부됩니다. Visual 서명은 영향을 받지 않습니다.
  • 문서 서명을 위해 발급된 인증서: digital signature 또는 non-repudiation 키 사용과, 존재한다면 문서 서명, 이메일 보호 또는 클라이언트 인증을 허용하는 확장 키 사용이 포함되어야 합니다. TLS 서버 인증서와 같이 다른 용도로 발급된 인증서도 서명은 가능하지만, PDF 리더는 해당 서명을 표시합니다.
  • 하드웨어 토큰, 스마트 카드, HSM 및 Windows 인증서 저장소는 지원되지 않습니다. 인증서와 개인 키 및 체인을 PFX로 내보내십시오.

OpenSSL을 사용하여 인증서와 개인 키로부터 PFX 만들기:

bash
openssl pkcs12 -export -out signing.pfx -inkey private.key -in certificate.crt
# 프롬프트에서 요청되는 내보내기 비밀번호는 SigningCertificate.Password입니다.

Windows 인증서 저장소에서 내보내기: certmgr.msc 를 열고 인증서를 찾으십시오(개인 키가 있으면 아이콘에 키가 표시됩니다). 오른쪽 클릭하고 All Tasks → Export… 를 선택합니다. Yes, export the private key 를 선택하고, Personal Information Exchange – PKCS #12 (.PFX) 를 선택한 뒤 비밀번호를 설정하십시오.

시작 검사

위젯이 활성화되면, SignerWidgetOptions.SigningCertificate에 있는 인증서가 DoconutHost.Initialize 내부에서 한 번 검사됩니다. 따라서 잘못 구성된 PFX는 첫 서명 시점이 아니라 시작 시점에 실패합니다. 세 가지 문제는 Application_Start에서 InvalidOperationException를 발생시키며, 모든 요청은 빈 500를 반환합니다; 이 메시지는 Windows 이벤트 로그에 기록됩니다:

메시지해결 방법
Doconut Signer: the certificate file was not found at '{path}'.올바른 PfxPath; 파일이 배포되어 있고 앱 풀 계정이 읽을 수 있는지 확인하십시오
Doconut Signer: the signing certificate could not be opened — the password is incorrect or the file is not a valid .pfx.비밀번호를 확인하십시오; 파일이 실제 .pfx인지, .cer 또는 .pem가 아닌지 확인하십시오
Doconut Signer: the signing certificate has no private key. Re-export the .pfx INCLUDING the private key.프라이빗 키와 함께 PFX를 다시 내보내십시오

ASP.NET Core에서는 호스트가 시작 시 인증서 이름을 기록하거나, 인증서가 만료되었거나 서명용으로 발급되지 않았다는 경고를 한 줄 기록합니다. DoconutHost은 해당 줄을 기록하지 않으므로, .NET Framework에서는 인증된 모드로 테스트 문서를 서명하여 새 인증서를 확인하십시오.

C# 파사드는 시작 시 확인되지 않습니다. SignAsync에 전달하는 인증서는 서명 시에 읽히므로, 경로나 비밀번호가 잘못되면 해당 호출이 실패합니다.

드롭인 위젯

엔드포인트 활성화

위젯의 ?sign=open|run|download 엔드포인트는 DocImage.axd에 의해 제공되며 기본적으로 비활성화되어 있습니다. 플러그인 등록 옆에서 이를 활성화하십시오:

csharp
Doconut.DoconutHost.Initialize(options =>
{
    options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
    options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
    options.AddSignerWidget(widget =>
    {
        widget.MaxUploadMb = 25;           // 기본값
        widget.MaxSignatureImageKb = 512;  // 기본값
        // widget.SigningCertificate: Certificate 설정을 참조하세요; 데모(워터마크) 서명을 위해 null로 두세요
    });
});
// System.Web은 Doconut이 보기 전에 전체 업로드를 읽습니다: maxRequestLength (KB)와
// Web.config에서 widget의 MaxUploadMb 위에 있는 maxAllowedContentLength (bytes)를.

AddSignerWidget()은 인자를 제공하지 않을 경우 기본값으로 위젯을 활성화합니다. 이것만으로는 서명을 부여하지 않으며, AddPlugin<SignerPlugin>()가 필요하거나, DoconutHost.Initialize가 예외를 발생시킵니다:

text
AddSignerWidget() was called but the Signer plugin is not registered. Add options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>() (the widget needs it), or remove the AddSignerWidget() call.

엔드포인트와 스크립트는 Web.config에 등록된 핸들러와 모듈에 의해 제공됩니다:

xml
<system.webServer>
  <handlers>
    <add name="DocImage" verb="GET,HEAD,POST" path="DocImage.axd" type="Doconut.DocImageHandler, Doconut" />
  </handlers>
  <modules>
    <add name="DoconutResources" type="Doconut.DoconutResourceModule, Doconut" />
  </modules>
</system.webServer>

모듈은 위젯이 활성화되었든 아니든 스크립트를 제공합니다. AddSignerWidget()가 없으면, 위젯은 로드되어 드롭 영역을 그리며, 첫 번째 요청은 404를 반환합니다: 그 후 위젯은 Signing is not enabled on this server.를 보고합니다

업로드 제한

ASP.NET은 DocImage.axd가 실행되기 전에 전체 요청 본문을 읽습니다. MaxUploadMb를 초과하지만 호스트 제한 이하인 업로드는 위젯 자체의 JSON 413(File is too large.)을 반환합니다. 호스트 제한을 초과하는 업로드는 먼저 IIS에 의해 거부되며, 위젯이 읽을 수 없는 오류 페이지가 반환됩니다. 호스트 제한을 위젯의 상한선보다 높게 유지하십시오:

xml
<system.web>
  <httpRuntime maxRequestLength="30720" />           <!-- KILOBYTES: 30 MB -->
</system.web>
<system.webServer>
  <security>
    <requestFiltering>
      <requestLimits maxAllowedContentLength="31457280" />  <!-- BYTES: 30 MB -->
    </requestFiltering>
  </security>
</system.webServer>

Content-Length(청크) 없이 전송된 업로드가 호스트 제한을 초과하면 역시 IIS 오류 페이지가 반환됩니다; 이 경우에 대한 해결 방법은 없습니다.

임베드하기

스크립트는 /doconut-res/js/doconutSigner.js 에서 제공됩니다. 이는 종속성이 없는 단일, 독립적인 파일입니다. basePath 를 핸들러에 지정하십시오:

html
<div id="host"></div>
<script src="/doconut-res/js/doconutSigner.js"></script>
<script>
  const handle = Doconut.signer('#host', { basePath: '/DocImage.axd' });
</script>

Doconut.signer(selectorOrElement, options) 은(는) CSS 선택자 또는 요소를 받아, 마운트를 찾지 못하면 예외를 발생시키고 핸들을 반환합니다. 위젯의 기본 basePath, /doconut 은 ASP.NET Core 엔드포인트이며; 이 패키지에서는 반드시 '/DocImage.axd' 이어야 합니다.

서명자는 PDF 또는 .docx 파일을 업로드하고, 서명을 생성합니다(Draw 를 캔버스에 그리거나, Type 으로 서명 폰트에 이름을 입력하거나, PNG, JPG 또는 GIF에서 Image 를 가져와서). 페이지에 끌어다 놓고 크기를 조정한 뒤 서명하고 결과를 다운로드합니다. 위젯은 항상 서명을 PNG 형식으로 전송합니다; 업로드된 이미지는 브라우저에서 520×160에 맞는 PNG로 변환됩니다.

옵션

옵션유형기본값비고
basePathstring'/doconut'?sign= 엔드포인트와 미리보기 이미지가 제공되는 위치입니다. 이 패키지에서 '/DocImage.axd' 를 설정하십시오
resPathstring'/doconut-res'예약됨; 위젯은 자체 CSS를 포함합니다
maxUploadMbnumber25클라이언트 측 검사만 수행하므로, 파일이 너무 크면 즉시 실패합니다. 서버 제한은 AddSignerWidget 에서 MaxUploadMb 입니다
maxSignatureKbnumber512이미지 모드에 대한 클라이언트 측 제한입니다. 서버의 MaxSignatureImageKb 와 동일하게 유지하십시오
previewWidthnumber560페이지 미리보기의 픽셀 너비
licenseUrlstring | nullnull데모 워터마크 알림을 이 URL로 연결된 링크로 변환합니다
signatureModestring'certified'초기 서명 유형: 'certified' 또는 'visual'. 다른 값은 'certified' 로 처리됩니다
showSignatureModeTogglebooleantrueDigital signature / Visual only 선택지를 표시합니다. false 를 사용하면 위젯이 signatureMode 로 서명합니다
wordOutputstring'pdf'.docx 소스에 대한 초기 출력: 'pdf' 또는 'docx'. 다른 값은 'pdf' 로 처리됩니다
showOutputFormatTogglebooleantruePDF / Word 선택지를 표시합니다(.docx 소스에만 해당). false 를 사용하면 위젯이 wordOutput 를 사용합니다
labelsobject{}영어 문자열의 일부를 재정의합니다

토글을 숨겨도 기능이 비활성화되는 것은 아니며, 값이 고정됩니다. 일반적인 두 가지 구성:

javascript
// 두 토글이 모두 표시되고, 디지털 서명이 기본값입니다: 완전한 셀프 서비스 서명자.
Doconut.signer('#host', { basePath: '/DocImage.axd', licenseUrl: '/pricing' });
javascript
// 시각적 표시만, 토글 없음: 디지털 서명이 제공되지 않는 간단한 스탬프.
Doconut.signer('#host', {
  basePath: '/DocImage.axd',
  signatureMode: 'visual',
  showSignatureModeToggle: false
});

콜백

콜백발생 시점페이로드
onReady마운트 시 한 번 (reset() 에서는 다시 발생하지 않음)—
onSourceLoaded파일이 열리고 미리보기가 표시될 때{ file: { token, name, pages, ext } }
onSigned서명이 성공했을 때{ downloadToken, downloadName, watermarked }
onDownload다운로드 클릭 시마다{ downloadName, downloadToken }
onError열기, 서명 또는 다운로드 단계가 실패하거나 이미지 모드 파일이 너무 클 때{ message }

예외를 발생시키는 콜백은 잡혀서 로그에 기록되며, 위젯의 흐름을 중단하지 않습니다.

명령형 핸들

메서드동작
reset()드롭 화면으로 돌아가 현재 흐름을 초기화합니다. onReady 를 다시 발생시키지 않습니다. destroy() 이후에는 아무 동작도 하지 않습니다
loadFile(file)File 로 흐름을 시작합니다. 위젯이 드롭 화면에 있지 않으면 아무 동작도 하지 않습니다; 필요하면 먼저 reset() 를 호출하십시오
destroy()리스너를 제거하고, 마운트를 비우며, 인스턴스를 고정합니다
javascript
const signerWidget = Doconut.signer('#host', {
  basePath: '/DocImage.axd',
  onSigned: (result) => console.log('signed', result.downloadName, result.watermarked),
  onError: (error) => console.warn(error.message)
});
document.getElementById('start-over').addEventListener('click', () => signerWidget.reset());

레이블

각 문자열은 영어 기본값을 가지고 있습니다; labels 은(는) 일부를 재정의하고 나머지는 영어 그대로 유지됩니다. 런타임에 변경되는 조각은 {placeholders} 를 사용하며, 예를 들어 uploading: 'Uploading {name}…' 와 pages: '{n} pages' 가 있습니다.

키영어 기본값
dropPromptDrag & drop a PDF or Word file here
dropHintPDF or Word (.docx)
chooseFileChoose file
signatureHeadingYour signature
modeDraw / modeType / modeImageDraw / Type / Image
metaSummarySignature details (optional)
metaSignerName / metaReason / metaLocationSigner name / Reason / Location
signatureTypeSignature type
modeCertified / modeVisualDigital signature / Visual only
modeVisualNoteNo certificate — a visible mark only, not cryptographically verifiable.
outputFormatOutput format
outputPdf / outputWordPDF / Word (.docx)
signActionSign document
downloadDownload
demoNoticeDemo — signed with the Doconut demo certificate; output is watermarked.
signingNotEnabledSigning is not enabled on this server.
page / pages1 page / {n} pages

추가 키는 배치 단계, 오류 화면, 데모 알림의 연결된 양식(demoNoticePrefix, demoNoticeLink, demoNoticeSuffix) 및 aria-live 공지를 포함합니다.

open 또는 run 가 JSON 오류 없이 404 에 응답하면, 위젯은 signingNotEnabled 을 표시합니다. 서버에서 오는 JSON 오류가 항상 우선하므로, 만료된 업로드와 같은 메시지는 계속 표시됩니다.

테마

위젯은 마운트 요소에 dsw 클래스를 추가하고 색상, 반경 및 폰트를 CSS 사용자 정의 속성에서 읽어들여, 내부를 건드리지 않고도 테마를 적용할 수 있습니다:

css
#host.dsw {
  --dsw-accent: #b0522b;       /* 링크, 포커스, 활성 모드 */
  --dsw-bg: #fffaf3;
  --dsw-fg: #3b2a1a;
  --dsw-muted: #8a7a68;
  --dsw-border: #e0cbb0;
  --dsw-radius: 14px;
  --dsw-font: Georgia, "Times New Roman", serif;
  --dsw-signature-font: "Segoe Script", "Brush Script MT", cursive;   /* 타입 모드 */
}

기본값: --dsw-accent: #2b6cb0, --dsw-bg: #ffffff, --dsw-fg: #1a202c, --dsw-muted: #718096, --dsw-border: #cbd5e0, --dsw-radius: 8px, 시스템 UI 폰트, 그리고 필기 서명 폰트.

직접 프런트엔드 구축

위젯은 DocImage.axd 에 대한 HTTP 계약의 클라이언트입니다. 라우트는 AddSignerWidget() 가 호출될 때까지 404 에 응답합니다. 오류는 JSON 본문을 포함하며, { "error": "..." }, 표에 "status only" 라고 명시된 경우를 제외합니다. 알 수 없는 ?sign= 값은 400 로 응답합니다.

라우트목적성공 응답
POST /DocImage.axd?sign=open (멀티파트, 파일 하나)PDF 또는 .docx 를 업로드하고 미리보기 위해 엽니다200 — { token, name, pages, ext }
POST /DocImage.axd?sign=run (JSON 본문)업로드된 파일에 서명200 — { downloadToken, downloadName, watermarked }
GET /DocImage.axd?sign=download&token=<downloadToken>서명된 파일을 스트리밍200 — 파일, Content-Disposition: attachment, Cache-Control: no-store

ext 은(는) open 응답에 선행 점(".docx")을 포함합니다. 페이지 미리보기는 표준 뷰어 이미지 라우트를 사용하며(/DocImage.axd?token={token}&page={n}&thumb=1&width={px}), 표시되는 페이지는 placement.page 로 변합니다.

run 본문:

json
{
  "token": "GUID-from-open",
  "signature": { "kind": "Drawn", "payload": "<base64 PNG, no data: prefix>" },
  "placement": { "page": 1, "x": 0.58, "y": 0.80, "w": 0.32, "h": 0.12 },
  "meta": { "signerName": "Ada Lovelace", "reason": "I approve", "location": "London, UK" },
  "wordOutput": "pdf",
  "mode": "certified"
}
필드비고
tokenopen 로부터 받은 토큰
signature.kindDrawn, Typed 또는 Image, 대소문자 구분 없음; 다른 값은 Drawn 로 변합니다. 힌트: 페이로드는 항상 PNG입니다
signature.payload접두사 data: 없이 순수 base64 PNG입니다. 실제 PNG여야 하며 디코딩 후 크기가 MaxSignatureImageKb 를 초과하면 안 됩니다
placement.page1부터 시작
placement.x / y / w / h좌상단을 기준으로 정규화된 0..1, x + w ≤ 1 및 y + h ≤ 1 포함
meta.signerName / reason / location선택 사항. 각각은 트림되고 빈 값은 삭제되며, 각 항목은 256자까지 잘립니다
wordOutputpdf (기본값) 또는 docx; PDF 소스에서는 무시됩니다. 다른 값은 pdf 로 변합니다
modecertified (기본값) 또는 visual. 다른 값은 certified 로 변합니다

downloadName 은(는) 출력 뒤에 따라옵니다: <source>-signed.pdf 또는 <source>-signed.docx, 그리고 download 은(는) 일치하는 Content-Type 를 전송합니다.

업로드된 원본과 서명된 결과는 각각 30분 동안 보관됩니다. 그 이후에는 run 와 download 가 404 로 응답하고 파일을 다시 열어야 합니다. 모든 토큰은 GUID입니다.

라우트상태상황본문
any404위젯이 활성화되지 않음상태만
any405잘못된 동사 (open 및 run 은 POST 필요, download 은 GET 필요)상태만
open400멀티파트 업로드가 아님Expected a multipart file upload.
open400파일이 없거나 비어 있음No file uploaded.
open400.pdf 또는 .docx 이외의 모든 것Signing supports PDF and Word (.docx) files only.
open413업로드가 MaxUploadMb 를 초과함 (IIS 제한은 아님)File is too large.
run400본문이 유효한 JSON이 아니거나 비어 있음Malformed request. / Empty request.
run400토큰이 없거나 GUID가 아님Invalid token.
run404업로드가 만료되었거나 열리지 않음Upload expired — please re-open the file.
run400서명이 없거나 배치가 없음No signature supplied. / No placement supplied.
run400페이로드가 base64가 아니거나, 비어 있거나, 너무 크거나 PNG가 아님Signature image is not valid base64. / Signature image is empty. / Signature image is too large. / The signature image must be a PNG.
run400배치가 페이지 밖에 있음The signature or its placement is invalid.
run400인증 모드, 유료 라이선스, 인증서 없음No signing certificate configured.
run400인증 모드이지만 인증서가 유효 기간 외The signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd.
open, run500처리 실패정제된 메시지
download400토큰이 없거나 GUID가 아님상태만
download404알 수 없거나 만료된 토큰상태만

fetch 를 사용한 전체 라운드 트립:

javascript
// file: 서명할 파일; pngBase64: 데이터: 접두사 없이 순수 base64 PNG 서명,
// 예를 들어 canvas.toDataURL('image/png').split(',')[1].
async function signFile(file, pngBase64) {
  const base = '/DocImage.axd';

  // 1. open: 파일을 업로드
  const form = new FormData();
  form.append('file', file, file.name);
  const opened = await (await fetch(base + '?sign=open', { method: 'POST', body: form })).json();

  // 2. run: 서명
  const signed = await (await fetch(base + '?sign=run', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      token: opened.token,
      signature: { kind: 'Drawn', payload: pngBase64 },
      placement: { page: 1, x: 0.58, y: 0.80, w: 0.32, h: 0.12 },
      meta: { signerName: 'Ada Lovelace', reason: 'I approve', location: 'London, UK' },
      wordOutput: 'pdf',
      mode: 'certified'
    })
  })).json();

  // 3. download: 서명된 파일을 가져오기
  const blob = await (await fetch(base + '?sign=download&token=' + encodeURIComponent(signed.downloadToken))).blob();
  const link = document.createElement('a');
  link.href = URL.createObjectURL(blob);
  link.download = signed.downloadName;
  link.click();
  URL.revokeObjectURL(link.href);
}

엔드포인트는 same-origin입니다: 이 버전은 CORS를 지원하지 않습니다. UI와 위젯 스크립트를 애플리케이션과 동일한 출처에서 제공하거나, UI의 출처 아래에서 DocImage.axd와 /doconut-res를 역프록시하십시오.

프로덕션 환경

  1. 플러그인을 설치하십시오, 코어 패키지 옆에 동일한 버전으로: Install-Package Doconut.NETFramework.Signer.

  2. 라이선스 파일을 추가하십시오. Doconut.Viewer.Signer.lic를 Doconut.Viewer.lic와 같은 폴더에 넣으세요.

  3. 인증서를 PFX 형식으로 개인 키와 발급자 체인과 함께, 인증 기관이나 조직 자체 PKI에서 받으세요. 먼저 시험해 보려면 데모 라이선스(내장 데모 인증서, 워터마크 포함) 또는 자체 서명된 PFX를 사용하십시오.

  4. 구성에서 인증서를 읽으십시오, 이렇게 하면 변경 시 코드 수정이 필요하지 않습니다:

    xml
    <appSettings>
      <add key="DoconutSigner:PfxPath" value="~/App_Data/your-certificate.pfx" />
    </appSettings>
    csharp
    var settings = System.Configuration.ConfigurationManager.AppSettings;
    
    Doconut.DoconutHost.Initialize(options =>
    {
        options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
        options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
        options.AddSignerWidget(widget => widget.SigningCertificate = new SigningCertificate
        {
            PfxPath = HostingEnvironment.MapPath(settings["DoconutSigner:PfxPath"]),
            Password = settings["DoconutSigner:Password"] ?? "",
        });
    });

    .pfx를 App_Data에 보관하십시오. IIS는 이를 제공하지 않으며, 비밀번호를 평문 Web.config에 두지 마세요: 암호화된 구성 섹션이나 배포가 읽는 비밀 저장소를 사용하십시오.

  5. 인증 모드에서 테스트 문서에 서명하십시오. 만료되었거나 아직 유효하지 않은 인증서는 The signing certificate expired on yyyy-MM-dd.(또는 is not valid before)로 거부되며, PDF 리더는 서명을 신뢰하는지 표시합니다.

PDF 리더에서의 신뢰. 리더는 인증서의 루트를 신뢰할 때 서명을 유효한 것으로 표시합니다. 조직의 PKI를 사용하면 루트를 신뢰하는 모든 머신, 일반적으로 조직 내 모든 머신에서 적용됩니다. Adobe가 어떤 머신에서든 신뢰하는 인증서(Adobe Approved Trust List)는 우리가 알기로는 하드웨어 토큰이나 HSM에 저장된 개인 키로 발급되며, 이 플러그인은 이를 사용할 수 없습니다: PFX만으로 서명합니다. 이러한 신뢰에 의존하기 전에 인증서 제공업체에 확인하십시오.

웹 팜

위젯은 open를 제공한 서버의 메모리에 각 업로드와 그 결과를 보관합니다. 스티키 세션이 없는 로드 밸런서 뒤에서는 이후의 run, download 또는 미리보기 요청이 다른 서버에 도달해 업로드를 찾지 못할 수 있습니다. DoconutHost.Initialize의 두 번째 인수를 통해 공유된 암호화 위젯 저장소를 등록하십시오:

csharp
byte[] farmKey = Convert.FromBase64String(System.Configuration.ConfigurationManager.AppSettings["Doconut:FarmKey"]);

Doconut.DoconutHost.Initialize(
    options =>
    {
        options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
        options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
        options.AddSignerWidget();
    },
    services => services.AddDoconutDistributedWidgets(store =>
    {
        store.RootPath = @"\\fileshare\doconut";   // 모든 서버가 읽고 쓸 수 있는 폴더
        store.FarmKey = farmKey;                   // 최소 32바이트, 모든 서버에서 동일
        // store.Ttl = TimeSpan.FromMinutes(30);   // 업로드가 유지되는 기간 (기본값)
    }));
  • 단일 서버는 별다른 것이 필요 없습니다: 이 호출이 없으면 메모리 내 저장소가 사용됩니다.
  • 업로드와 결과는 공유 영역에 저장될 때 암호화됩니다(AES-256, encrypt-then-MAC), 각 파일은 해당 토큰에 바인딩되어 하나의 토큰이 다른 토큰의 파일을 읽을 수 없습니다.
  • FarmKey는 최소 32바이트이며 모든 서버에서 동일해야 합니다. 비밀 저장소에서 로드하고 절대 하드코딩하지 마세요. RootPath가 없거나 FarmKey가 32바이트보다 짧을 경우 등록 시 ArgumentException가 발생합니다.
  • 분산 뷰어가 사용하는 동일한 공유 위치를 RootPath에 지정하고, 모든 서버에 동일한 서명 인증서를 제공하십시오.

API 참조

Facade와 위젯 옵션은 Doconut 네임스페이스에 있습니다; 요청 및 결과 유형은 Doconut.Core.Models.Signing에 있습니다. SignerPlugin는 Doconut.Plugins.Signer에 있습니다.

DocumentSigner

csharp
public sealed class DocumentSigner
{
    public Task<SignResult> SignAsync(
        Stream source, string sourceExtension, SignRequest request,
        SigningCertificate? cert = null, CancellationToken ct = default);
}

DoconutHost.Services에서 해결됩니다; 생성자는 internal입니다. sourceExtension는 ".pdf" 또는 ".docx"입니다. 유료 라이선스에서는 cert가 사용되어 출력이 깨끗합니다; 임시 라이선스에서는 내장 데모 인증서가 사용되고, cert는 무시되며, 출력에 워터마크가 삽입됩니다.

SignRequest

csharp
public sealed record SignRequest(
    VisibleSignature   Signature,
    SignaturePlacement Placement,
    string?            SignerName = null,
    string?            Reason     = null,
    string?            Location   = null,
    WordOutput         WordOutput = WordOutput.Pdf,
    SignatureMode      Mode       = SignatureMode.Certified)
{
    public bool IsValid { get; }   // Signature.IsValid && Placement.IsValid
}

한 번 배치된 하나의 가시 서명이 있으며, 선택적인 서명자 메타데이터가 추가될 수 있습니다.

VisibleSignature and SignatureKind

csharp
public sealed record VisibleSignature(SignatureKind Kind, byte[] PngBytes)
{
    public bool IsValid { get; }   // PngBytes가 비어 있지 않음
}

public enum SignatureKind { Drawn, Typed, Image }

PngBytes는 모든 종류에 대해 PNG입니다. 그리거나 입력한 서명은 투명합니다; 업로드된 이미지는 기존 투명성을 유지하므로 불투명 JPG는 불투명하게 유지됩니다. Kind는 힌트일 뿐입니다.

SignaturePlacement

csharp
public readonly record struct SignaturePlacement(int Page, double X, double Y, double W, double H)
{
    public bool IsValid { get; }   // Page >= 1; X, Y >= 0; W, H > 0; X + W <= 1; Y + H <= 1
}

Page는 1부터 시작합니다; X, Y, W 및 H는 왼쪽 위 모서리로부터 정규화된 0..1입니다.

SignatureMode and WordOutput

csharp
public enum SignatureMode { Certified, Visual }   // Certified는 기본값입니다
public enum WordOutput { Pdf, Docx }              // Pdf는 기본값이며; PDF 소스에 대해서는 무시됩니다

SignResult

csharp
public sealed record SignResult(Stream Stream, string Extension);

시크 가능한 스트림 형태의 서명된 문서와, 점(.)이 포함된 확장자(".pdf" 또는 ".docx").

SigningCertificate

csharp
public sealed class SigningCertificate
{
    public byte[]? PfxBytes { get; init; }
    public string? PfxPath  { get; init; }
    public string  Password { get; init; } = "";
    public bool    HasMaterial { get; }   // PfxBytes가 비어 있지 않거나, PfxPath가 비어 있지 않음
}

PfxBytes 또는 PfxPath와 함께 Password를 설정합니다. 세터는 init-only이며, 프로젝트는 C# 9.0 이상이 필요합니다.

SignerWidgetOptions

csharp
public sealed class SignerWidgetOptions
{
    public int MaxUploadMb { get; set; } = 25;
    public int MaxSignatureImageKb { get; set; } = 512;
    public SigningCertificate? SigningCertificate { get; set; }
}

DoconutOptions.AddSignerWidget(Action<SignerWidgetOptions>? configure = null)를 통해 설정하면, 호출을 체인할 수 있도록 DoconutOptions를 반환합니다. null SigningCertificate는 임시 라이선스에서 데모 인증서를 의미하며, Visual 서명은 유료 라이선스에서만 가능합니다.

문제 해결

증상원인해결 방법
플러그인을 추가한 후 모든 요청이 빈 500을 반환하고; 이벤트 로그에 The Signer plugin is registered via AddPlugin but no active license grants Signer.가 표시됩니다.라이선스 없음, TRIAL 파일, Signer가 없는 라이선스, 또는 버전 기간을 초과한 유료 라이선스Signer를 부여하는 라이선스를 설치하거나, AddPlugin<SignerPlugin>()를 제거하십시오.
이벤트 로그에 AddSignerWidget() was called but the Signer plugin is not registered.가 표시됩니다.위젯이 플러그인 없이 활성화되었습니다.options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>()를 추가하십시오.
이벤트 로그에 Doconut Signer: the certificate file was not found at '{path}'.가 표시됩니다.PfxPath가 존재하지 않는 파일을 가리키고 있습니다.경로를 수정하고, 애플리케이션 풀 계정이 읽을 수 있는 위치에 파일을 배포하십시오.
이벤트 로그에 Doconut Signer: the signing certificate could not be opened — the password is incorrect or the file is not a valid .pfx.가 표시됩니다.비밀번호가 틀렸거나 PKCS#12 파일이 아닙니다.비밀번호를 확인하고, 실제 .pfx를 사용하십시오.
이벤트 로그에 Doconut Signer: the signing certificate has no private key. Re-export the .pfx INCLUDING the private key.가 표시됩니다.PFX가 개인 키 없이 내보내졌습니다.개인 키와 함께 다시 내보내십시오.
new SigningCertificate { … }가 컴파일되지 않습니다.프로젝트가 C# 7.3을 사용하고 있어 init-only 속성을 설정할 수 없습니다.<LangVersion>를 9.0 이상으로 설정하십시오.
DocumentSigner를 해결하는 중 No IDocumentSigner is registered.가 발생합니다.SignerPlugin가 등록되지 않았습니다.DoconutHost.Initialize에 AddPlugin<SignerPlugin>()를 추가하십시오.
출력에 워터마크가 표시됩니다.라이선스가 임시(Demo/NFR)입니다.Signer를 부여하는 유료 라이선스를 사용하십시오.
run가 400 No signing certificate configured.로 응답합니다.유료 라이선스, Certified 모드, 그리고 인증서가 없음SigningCertificate를 구성하거나 Visual 모드로 서명하십시오.
run가 400 The signing certificate expired on yyyy-MM-dd.로 응답합니다.인증서가 만료되었습니다.교체하십시오; 그 사이 Visual 서명은 계속 작동합니다.
위젯이 로드되었지만 Signing is not enabled on this server.라고 표시됩니다.AddSignerWidget()가 호출되지 않았거나, basePath가 '/DocImage.axd'가 아닙니다.AddSignerWidget()를 호출하고, basePath: '/DocImage.axd'를 설정하십시오.
대용량 업로드 시 위젯 메시지 대신 IIS 오류 페이지가 표시됩니다.maxRequestLength / maxAllowedContentLength가 MaxUploadMb 이하입니다.두 호스트 제한을 MaxUploadMb 이상으로 올리십시오.
run가 400 The signature image must be a PNG., Signature image is not valid base64. 또는 Signature image is too large.로 응답합니다.맞춤 UI가 data: URL, JPG, 혹은 MaxSignatureImageKb보다 큰 파일을 보냈습니다.제한 내에서 순수 base64 PNG를 전송하십시오.
open가 413 File is too large.로 응답합니다.업로드가 MaxUploadMb를 초과했습니다.AddSignerWidget에서 MaxUploadMb를 올리십시오; 위젯의 maxUploadMb는 클라이언트 측 검사에 불과합니다.
run 또는 download가 404 Upload expired — please re-open the file.로 응답합니다.30분 창이 지나갔거나, 팜 내 다른 서버에 업로드가 없습니다.파일을 다시 열고; 팜 환경에서는 AddDoconutDistributedWidgets를 등록하십시오.
서명된 .docx가 일부 뷰어에서 서명이 표시되지 않습니다.Word 출력에는 OOXML 패키지 서명이 포함되어 있으나, 많은 뷰어가 이를 표시하지 않습니다.기본값인 PDF로 서명하십시오.
PDF 리더가 서명자의 신원을 알 수 없다고 표시합니다.리더가 인증서 루트를 신뢰하지 않습니다(데모 인증서는 절대 신뢰되지 않음).리더가 신뢰하는 루트에서 발급된 인증서를 사용하십시오.
UI가 다른 오리진에 있을 때 위젯이 실패합니다.엔드포인트에 CORS 지원이 없습니다.UI를 동일 오리진에서 제공하거나, DocImage.axd와 /doconut-res를 역프록시하십시오.
테마가 적용되지 않습니다.셀렉터가 마운트 내부 요소를 대상으로 합니다.마운트 자체를 대상으로 합니다: #host.dsw 또는 #host.

프레임워크 참고

ASP.NET Core 패키지와 비교했을 때, 이 패키지는 호스팅 부분만 다르며 API, 엔드포인트 계약, 위젯 스크립트 및 라이선스 규칙은 동일합니다.

  • 등록은 Application_Start에 있으며, DoconutHost.Initialize를 통해 이루어지고, builder.Services.AddDoconut 대신 사용됩니다. AddDoconutDistributedWidgets와 같은 서비스는 두 번째 인수에 전달됩니다.
  • 엔드포인트는 DocImage.axd에 의해 제공되고 스크립트는 DoconutResourceModule에 의해 제공되며, 두 경우 모두 Web.config에 등록됩니다. 이는 UseDoconut()와 UseDoconutResources() 대신입니다. 위젯은 basePath: '/DocImage.axd'가 필요합니다.
  • 시작 실패는 모든 요청에서 빈 500 로 나타나며, 원인은 Windows 이벤트 로그에 기록됩니다.
  • 업로드는 Doconut이 보기 전에 ASP.NET에 의해 전체가 읽히므로 IIS 제한은 MaxUploadMb 이상이어야 합니다.
  • 시작 로그 라인 없음(인증서에 관하여): 세 가지 인증서 오류는 여전히 발생하지만, 인증서 이름을 적은 라인은 기록되지 않습니다.
  • C# 9.0 이상은 SigningCertificate의 init-only 속성을 설정하는 데 필요합니다.
  • Windows 전용이며, .NET Framework 패키지의 나머지와 동일합니다.

이 페이지가 도움이 되었나요?