서명자 플러그인

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

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

구성 요소사용 시
DocumentSigner (C#)서버에서 서명하며, 브라우저를 사용하지 않습니다
드롭인 위젯 (doconutSigner.js)페이지에 바로 사용할 수 있는 업로드, 서명 및 다운로드 화면을 원할 때
HTTP 엔드포인트 (?sign=open|run|download)문서화된 서버 계약에 따라 자체 서명 UI를 구축하고자 할 때

각 서명은 한 페이지에 한 번만 삽입됩니다. 서명자의 이름, 이유 및 위치는 서명과 함께 저장될 수 있습니다.

패키지 설치

최신 안정 버전 Signer 플러그인을 설치합니다:

bash
dotnet add package Doconut.NET8.Signer

이 문서에서 설명하는 릴리스에 플러그인을 고정하려면, 버전을 별도로 지정하세요:

bash
dotnet add package Doconut.NET8.Signer --version 26.10.0

Signer 패키지를 Doconut.NET8와 동일한 버전으로 유지하십시오. 패키지 ID는 Doconut.NET8.Signer이며, .<version>는 다운로드된 .nupkg 파일 이름에만 나타납니다.

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

플랫폼. 플러그인은 Doconut.NET8가 실행되는 모든 환경에서 동작합니다: Windows와 x64용 glibc 기반 Linux (Alpine이나 기타 musl 기반 배포판 제외). Linux에서는 첫 번째 문서를 열기 전에 글꼴 구성 라이브러리를 설치하십시오:

bash
apt-get update && apt-get install -y libfontconfig1

RHEL, Fedora 및 유사 배포판에서는 패키지가 fontconfig입니다. 이를 설치하지 않으면 문서 열기에 실패하고 The system library libfontconfig1 is missing. Install it (Debian/Ubuntu: apt-get install -y libfontconfig1) and see the Linux section of the Doconut documentation. 오류가 발생합니다.

플러그인 등록

모든 Doconut 플러그인과 마찬가지로, Signer는 AddPlugin<TPlugin>()를 AddDoconut() 내부에 등록합니다:

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
});

C# 파사드에 필요한 것은 이것뿐입니다. 위젯과 해당 HTTP 엔드포인트는 별도의 선택적 옵션이며, AddSignerWidget() (참조: 드롭인 위젯).

플러그인은 Signer 기능을 부여하는 라이선스가 필요합니다. 라이선스가 없으면, AddDoconut()가 시작 시에 예외를 발생시켜 애플리케이션이 요청을 처리하기 전에 중단됩니다:

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.

라이선스가 없거나, 레거시 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가 없는 라이선스, 또는 버전 범위 외의 유료 라이선스AddDoconut() 예외 발생——

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

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

C#에서 사용하기

DocumentSigner 은(는) AddDoconut() 에 의해 등록되고 의존성 주입으로 해결됩니다. 생성자는 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, ct);
            return output.ToArray();
        }
    }
}

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

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

시각 서명은 이미지에만 스탬프를 찍으며 인증서가 필요하지 않습니다:

csharp
var signer = app.Services.GetRequiredService<DocumentSigner>();
byte[] signaturePng = File.ReadAllBytes("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(stream, ".pdf", request, ct: ct);

Word 소스는 Word 출력이 요청되지 않는 한 PDF로 서명됩니다. 결과는 result.Extension 로 명명하세요:

csharp
var signer = app.Services.GetRequiredService<DocumentSigner>();
byte[] signaturePng = File.ReadAllBytes("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눈에 보이는 서명만절대 필요 없음아니오: 그림입니다

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

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

워드 문서

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

출력무슨 일이 일어나는가검증자 지원
WordOutput.Pdf (기본)문서가 PDF로 변환된 뒤 서명 및 봉인됩니다광범위: 서명된 PDF는 모든 곳에서 검증됩니다
WordOutput.Docx문서는 워드 형식 그대로 유지되며, 서명 이미지가 삽입되고 OOXML 패키지 서명이 추가됩니다제한적: 모든 뷰어가 OOXML 패키지 서명을 표시하는 것은 아닙니다

수신자가 편집 가능한 워드 파일이 필요하고 제한된 검증자 지원을 수용하는 경우가 아니면 PDF를 유지하십시오.

인증서 설정

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

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
    options.AddSignerWidget(widget =>
    {
        widget.SigningCertificate = new SigningCertificate
        {
            PfxBytes = File.ReadAllBytes("/secure/signing.pfx"),
            Password = builder.Configuration["Signing:PfxPassword"],
        };
    });
});
csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
    options.AddSignerWidget(widget =>
    {
        widget.SigningCertificate = new SigningCertificate
        {
            PfxPath = "/secure/signing.pfx",
            Password = builder.Configuration["Signing:PfxPassword"],
        };
    });
});

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

요구 사항:

  • PFX / PKCS#12 번들 개인 키 포함. 공개키만 있는 파일(.cer, .crt)은 서명할 수 없습니다. 발급자 체인을 함께 내보내어 PDF 봉인이 이를 포함하도록 하십시오.
  • 올바른 비밀번호.
  • 유효 기간 내에 있어야 합니다. 만료되었거나 아직 유효하지 않은 인증서는 애플리케이션을 중단시키지 않으며, 시작 시 경고로 로그에 기록되고, 교체될 때까지 인증된 서명이 거부됩니다. 시각적 서명은 영향을 받지 않습니다.
  • 문서 서명을 위해 발급됨: 디지털 서명 또는 부인 방지 키 사용과, 존재한다면 문서 서명, 이메일 보호 또는 클라이언트 인증을 허용하는 확장 키 사용이 포함되어야 합니다. 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 에 있는 인증서를 한 번, AddDoconut() 내부에서 검사하므로 잘못 구성된 PFX는 첫 서명 시점이 아니라 시작 시점에 실패합니다. 세 가지 문제는 InvalidOperationException 를 발생시킵니다:

메시지해결 방법
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를 다시 내보내십시오

그 외의 경우 호스트는 시작 시 로그에 한 줄을 기록합니다. 인증서가 준비되었을 때의 정보:

text
Doconut Signer: using certificate '{subject}' (valid until yyyy-MM-dd). Signatures are digitally sealed.

만료되었거나 아직 유효하지 않거나 문서 서명을 위해 발급되지 않은 경우 경고:

text
Doconut Signer: the signing certificate '{subject}' expired on yyyy-MM-dd. Certified signatures will be refused until it is replaced.
Doconut Signer: the signing certificate '{subject}' is not valid before yyyy-MM-dd. Certified signatures will be refused until then.
Doconut Signer: the signing certificate '{subject}' is not issued for document signing (its key usage excludes it). PDF readers will flag these signatures.

인증서가 구성되지 않은 경우 정보:

text
Doconut Signer: no signing certificate configured — output uses the built-in demo certificate and is watermarked. Set SignerWidgetOptions.SigningCertificate to sign with your own certificate.

마지막 줄은 모든 라이선스에서 동일합니다. 유료 라이선스에서는 데모 인증서를 사용하지 않으며, 인증서가 없을 경우 시각적 서명만 작동합니다.

C# 파사드는 시작 시점에 검사되지 않습니다. 서명 시 SignAsync 에 전달한 인증서를 읽으며, 경로 또는 비밀번호가 잘못되면 해당 호출이 실패합니다.

드롭인 위젯

엔드포인트 활성화

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

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
    options.AddSignerWidget(widget =>
    {
        widget.MaxUploadMb = 25;           // 기본값
        widget.MaxSignatureImageKb = 512;  // 기본값
        // widget.SigningCertificate: Certificate 설정을 참조하십시오; 데모(워터마크) 서명을 위해 null로 두세요
    });
});

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

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.

AddSignerWidget() 없이, 모든 ?sign= 요청은 404 로 응답합니다. 스크립트 자체는 계속 제공되므로 위젯은 로드되어 드롭 영역을 그린 뒤, 첫 번째 요청에서 Signing is not enabled on this server. 를 보고합니다.

삽입하기

UseDoconutResources() 은(는) 스크립트를 {ResourcesPath}/js/doconutSigner.js (기본값 /doconut-res/js/doconutSigner.js) 에서 제공합니다. 이는 의존성이 없는 단일 독립 파일입니다:

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

Doconut.signer(selectorOrElement, options) 은(는) CSS 선택자 또는 요소를 받아, 마운트를 찾지 못하면 예외를 발생시키고 핸들을 반환합니다.

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

옵션

옵션유형기본값비고
basePathstring'/doconut'?sign= 엔드포인트와 미리보기 이미지가 제공되는 위치
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: '/doconut', licenseUrl: '/pricing' });
javascript
// 시각적 표시만, 토글 없음: 디지털 서명이 제공되지 않는 간단한 스탬프.
Doconut.signer('#host', {
  basePath: '/doconut',
  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: '/doconut',
  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 폰트, 그리고 필기 서명 폰트.

직접 프런트엔드 구축

위젯은 이 HTTP 계약의 클라이언트입니다. 세 개의 라우트 모두 UseDoconut()가 마운트된 경로(보통 /doconut) 아래에 위치하며, AddSignerWidget()이 호출될 때까지 404에 응답합니다. 오류는 JSON 본문({ "error": "..." })을 포함하지만, 표에 "status only"라고 명시된 경우는 제외합니다. 알 수 없는 ?sign= 값은 400에 응답합니다.

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

ext는 open 응답에 선행 점(".docx")을 포함합니다. 페이지 미리보기는 표준 뷰어 이미지 경로인 {basePath}?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.payloaddata: 접두사가 없는 순수 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잘못된 HTTP 메서드(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를 초과함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: data: 접두사가 없는 순수 base64 PNG 서명,
// 예를 들어 canvas.toDataURL('image/png').split(',')[1].
async function signFile(file, pngBase64) {
  const base = '/doconut';

  // 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와 위젯 스크립트를 Doconut과 동일한 출처에서 제공하거나, UI의 출처 아래에서 두 /doconut 경로(미들웨어 경로와 리소스 경로)를 역프록시하십시오.

프로덕션에서

  1. 플러그인 설치 코어 패키지와 같은 위치에, 동일한 버전으로: dotnet add package Doconut.NET8.Signer.

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

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

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

    json
    "DoconutSigner": { "PfxPath": "certs/your-certificate.pfx" }
    csharp
    var signerSettings = builder.Configuration.GetSection("DoconutSigner");
    
    builder.Services.AddDoconut(options =>
    {
        options.LicensePath = "Doconut.Viewer.lic";
        options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
        options.AddSignerWidget(widget => widget.SigningCertificate = new SigningCertificate
        {
            PfxPath = Path.Combine(builder.Environment.ContentRootPath, signerSettings["PfxPath"]),
            Password = signerSettings["Password"] ?? "",
        });
    });

    .pfx를 wwwroot 외부에 보관하고, 비밀번호는 appsettings.json에 두지 마세요: 개발 시 사용자 비밀(dotnet user-secrets set "DoconutSigner:Password" "<password>"), 환경 변수(DoconutSigner__Password) 또는 프로덕션의 금고에 보관합니다.

  5. 시작 로그를 확인하세요. 로그에 using certificate '{subject}' (valid until …). Signatures are digitally sealed.가 표시되어야 합니다. 경고가 나타난다면 인증서가 만료되었거나 아직 유효하지 않거나 문서 서명을 위해 발급되지 않은 것입니다.

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

웹 팜

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

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

builder.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);
}

의존성 주입으로 해결됩니다; 생성자는 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 및 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 및 WordOutput (서명 모드 및 Word 출력)

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도 설정합니다.

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 서명만 가능합니다.

문제 해결

증상원인해결 방법
AddDoconut() throws The Signer plugin is registered via AddPlugin but no active license grants Signer.라이선스가 없거나, TRIAL 파일이 있거나, Signer가 없는 라이선스이거나, 버전 기간을 벗어난 유료 라이선스Signer을 부여하는 라이선스를 설치하거나, AddPlugin<SignerPlugin>()을 제거하십시오.
AddDoconut() throws AddSignerWidget() was called but the Signer plugin is not registered.위젯이 플러그인 없이 활성화되었습니다options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>()을 추가하십시오.
AddDoconut() throws Doconut Signer: the certificate file was not found at '{path}'.PfxPath이(가) 누락된 파일을 가리킵니다경로를 수정하고, 앱 계정이 읽을 수 있는 위치에 파일을 배포하십시오.
AddDoconut() throws Doconut Signer: the signing certificate could not be opened — the password is incorrect or the file is not a valid .pfx.잘못된 비밀번호이거나 PKCS#12 파일이 아닙니다비밀번호를 확인하고, 실제 .pfx을 사용하십시오.
AddDoconut() throws Doconut Signer: the signing certificate has no private key. Re-export the .pfx INCLUDING the private key.PFX가 개인 키 없이 내보내졌습니다개인 키와 함께 다시 내보내십시오.
Resolving DocumentSigner throws No IDocumentSigner is registered.SignerPlugin가 등록되지 않았습니다AddDoconut() 안에 AddPlugin<SignerPlugin>()을 추가하십시오.
The output is watermarked라이선스가 임시(Demo/NFR)입니다Signer을 부여하는 유료 라이선스를 사용하십시오.
run answers 400 No signing certificate configured.유료 라이선스, Certified 모드, 그리고 인증서가 없습니다SigningCertificate을 구성하거나 Visual 모드로 서명하십시오.
run answers 400 The signing certificate expired on yyyy-MM-dd.인증서가 오래되었습니다교체하십시오; 그 사이 Visual 서명은 계속 작동합니다.
The log says the output "uses the built-in demo certificate", yet a paid license refuses Certified signatures라이선스와 관계없이 인증서가 구성되지 않으면 해당 문구가 기록됩니다SigningCertificate을 구성하십시오.
The widget loads but says Signing is not enabled on this server.AddSignerWidget()이 호출되지 않았거나, UseDoconut()이 마운트된 위치와 basePath이 일치하지 않습니다AddSignerWidget()을 호출하고, basePath을 수정하십시오.
run answers 400 The signature image must be a PNG., Signature image is not valid base64. or Signature image is too large.맞춤 UI가 data: URL, JPG, 또는 MaxSignatureImageKb보다 큰 파일을 보냈습니다제한 내에서 순수 base64 PNG를 전송하십시오.
open answers 413 File is too large.업로드가 MaxUploadMb를 초과했습니다AddSignerWidget에서 MaxUploadMb을 올리고, 위젯의 maxUploadMb은 클라이언트 측 검사에 불과합니다.
run or download answers 404 Upload expired — please re-open the file.30분 창이 지나갔거나, 웹 팜 노드에 업로드가 없습니다파일을 다시 열고; 팜 환경에서는 AddDoconutDistributedWidgets을 등록하십시오.
A signed .docx shows no signature in some viewersWord 출력에 OOXML 패키지 서명이 포함되어 있어 일부 뷰어에서 서명이 표시되지 않습니다기본값인 PDF로 서명하십시오.
PDF readers say the signer's identity is unknown리더가 인증서 루트를 신뢰하지 않음(데모 인증서는 절대 신뢰되지 않음)리더가 신뢰하는 루트의 인증서를 사용하십시오.
The widget fails when the UI is on another origin엔드포인트에 CORS 지원이 없습니다UI를 동일한 오리진에서 제공하거나, Doconut 경로를 역프록시하십시오.
The theme does not apply셀렉터가 마운트 내부 요소를 대상으로 합니다마운트 자체를 대상으로 하세요: #host.dsw 또는 #host.

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