Plugin Signer

Assine documentos PDF e Word com uma assinatura visível e um selo digital

O plugin Signer coloca uma assinatura visível em um documento e, por padrão, o sela com uma assinatura digital que um leitor de PDF pode verificar. Ele assina arquivos PDF e Word (.docx). A assinatura visível é sempre uma imagem PNG: desenhada, digitada ou enviada pelo assinante.

SuperfícieUse quando
DocumentSigner (C#)Você assina no servidor, sem envolvimento do navegador
Drop-in widget (doconutSigner.js)Você quer uma tela pronta de upload, assinatura e download na sua página
Pontos de extremidade HTTP em DocImage.axd (?sign=open|run|download)Você cria sua própria interface de assinatura contra um contrato de servidor documentado

Cada assinatura é colocada uma única vez, em uma página. O nome do assinante, o motivo e o local podem acompanhá‑la.

Instalar o pacote

powershell
Install-Package Doconut.NETFramework.Signer

Para fixar o plugin na versão que esta documentação descreve:

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

Mantenha o pacote Signer na mesma versão que Doconut.NETFramework.

O arquivo de licença do plugin, Doconut.Viewer.Signer.lic, deve ficar na mesma pasta que Doconut.Viewer.lic; ele é lido junto com a licença do visualizador.

Registrar o plugin

Como todo plugin Doconut, o Signer registra‑se com AddPlugin<TPlugin>() em DoconutHost.Initialize, chamado a partir de Application_Start:

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

Adicione Doconut.DoconutHost.Shutdown() a Application_End para que o trabalho em segundo plano pare corretamente quando o pool de aplicativos for reciclado.

Isso é tudo que a fachada C# precisa. O widget e seus pontos de extremidade HTTP são uma opção separada, AddSignerWidget() (veja Widget incorporado).

O plugin precisa de uma licença que conceda a capacidade Signer. Sem ela, DoconutHost.Initialize lança uma exceção a partir de 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.

No System.Web isso significa que cada requisição responde com um 500 vazio, e o motivo está apenas no log de eventos do Windows (fonte ASP.NET). Ele lança exceção por falta de licença, um arquivo legado TRIAL, uma licença sem Signer, e uma licença paga usada fora da sua janela de versão. Licenças temporárias Demo/NFR são aceitas. Veja Configuração de Licença.

Licenciamento e marca d'água

Estado da licençaInicializaçãoAssinatura certificadaAssinatura visual
Licença paga concedendo Signer, certificado configuradoIniciaSelado com seu certificado, limpo (watermarked: false)Limpo
Licença paga concedendo Signer, sem certificadoIniciaRecusado: No signing certificate configured.Limpo
Licença paga, certificado expirado ou ainda não válidoIniciaRecusado: The signing certificate expired on yyyy-MM-dd.Limpo
Licença temporária Demo/NFR, ativa ou expiradaIniciaSelado com o certificado demo incorporado, marca d'água (watermarked: true)Com marca d'água
Sem licença, um arquivo legado TRIAL, uma licença sem Signer, ou uma licença paga fora da sua janela de versãoLança Application_Start; cada requisição responde um 500 vazio——

A regra é a mesma para a fachada C# e o widget: a saída recebe marca d'água quando a licença não é uma licença de visualizador paga ou é temporária. Sob uma licença temporária o plugin sempre assina com seu certificado demo incorporado, e qualquer certificado que você configure não é usado.

O certificado demo produz um selo genuíno, mas os leitores de PDF não o confiam. Uma integração pode ser construída e testada de ponta a ponta com uma licença de avaliação; para obter uma saída limpa e confiável você precisa tanto de uma licença paga quanto do seu próprio certificado de assinatura.

Uso em C#

DocumentSigner é registrado por DoconutHost.Initialize; resolva‑o a partir de DoconutHost.Services. Seu construtor é interno, portanto nunca o new. Resolver sem AddPlugin<SignerPlugin>() lança 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 tem como padrão Certified (assinatura visível + selo digital); WordOutput tem como padrão 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 recebe o fluxo de origem, sua extensão (".pdf" ou ".docx"), a requisição e o certificado para esta chamada. A fachada não lê SignerWidgetOptions.SigningCertificate; essa configuração é para o widget. Passe null sob uma licença demo, ou no modo Visual.

SignResult contém o documento assinado como um fluxo pesquisável, além de seu Extension (".pdf" ou ".docx") para que você possa nomear o arquivo. Você possui o fluxo: descarte‑o quando terminar.

Em um controlador MVC 5

Torne a ação assíncrona e await a assinatura. Esta adiciona uma assinatura Visual, que não requer certificado:

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

Uma fonte Word é assinada para PDF a menos que você solicite saída Word. Nomeie o resultado a partir de 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 lança exceção em vez de retornar quando a chamada não pode ser bem‑sucedida:

ExceçãoMensagemQuando
InvalidOperationExceptionNo signing certificate configured.Modo certificado, licença paga, e nenhum certificado fornecido
InvalidOperationExceptionThe signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd.Modo certificado com um certificado fora da sua janela de validade
ArgumentExceptionThe sign request is invalid: the visible signature needs PNG bytes and the placement must be a normalized rectangle on a 1-based page.Bytes PNG vazios, ou um posicionamento que não é válido
NotSupportedExceptionThe signer supports PDF and Word (.docx) documents; got '{extension}'.Qualquer outro tipo de fonte

Modos de assinatura, saída do Word e certificados

Modos de assinatura

SignRequest.Mode escolhe se a assinatura é selada.

ModoO que produzCertificadoVerificável
SignatureMode.Certified (padrão)A assinatura visível mais um selo digitalObrigatório sob licença pagaSim
SignatureMode.VisualApenas a assinatura visívelNunca necessárioNão: é uma imagem

Use Certified quando a assinatura deve ser comprovável: aprovações, contratos, qualquer coisa que um verificador precise checar para identidade e integridade. Use Visual quando você só precisa da aparência de uma assinatura, ou não tem certificado. Uma licença temporária marca ambas com marca d'água.

Selos PDF são assinaturas PKCS#7 destacadas (adbe.pkcs7.detached) com SHA-256, para chaves RSA ou ECDSA. Elas carregam os certificados do emissor encontrados no seu PFX, de modo que um leitor que confia na sua raiz pode construir a cadeia. Selos nativos do Word são assinaturas de pacote OOXML e carregam apenas o certificado do assinante.

Documentos Word

Para uma fonte .docx, SignRequest.WordOutput escolhe a saída. É ignorado para fontes PDF, que sempre produzem um PDF.

SaídaO que aconteceSuporte do verificador
WordOutput.Pdf (padrão)O documento é convertido para PDF, então assinado e seladoAmplo: um PDF assinado verifica em qualquer lugar
WordOutput.DocxO documento permanece em Word: a imagem da assinatura é inserida nele, além de uma assinatura de pacote OOXMLLimitado: nem todo visualizador exibe assinaturas de pacote OOXML

Mantenha PDF a menos que o destinatário precise de um arquivo Word editável e aceite o suporte limitado do verificador.

Configuração de certificado

Para selar com sua própria identidade, forneça ao plugin um arquivo PFX (PKCS#12) que inclua a chave privada. Para o widget, defina SignerWidgetOptions.SigningCertificate; para a fachada C#, passe o certificado para SignAsync. Forneça os bytes ou um caminho, além da senha. App_Data é um bom local para o arquivo, porque o IIS nunca o serve:

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"] ?? "",
        };
    });
});

As propriedades de SigningCertificate são apenas init, o que o C# 7.3 (o padrão para projetos .NET Framework) não pode definir. Defina <LangVersion> para 9.0 ou posterior no arquivo de projeto.

O certificado é mantido apenas na memória. Nunca é registrado, retornado a um cliente, ou persistido, e a senha nunca aparece em uma mensagem de erro.

Requisitos:

  • Um pacote PFX / PKCS#12 com sua chave privada. Um arquivo somente de chave pública (.cer, .crt) não pode assinar. Exporte a cadeia do emissor com ele, para que os selos PDF possam carregá‑la.
  • A senha correta.
  • Dentro da sua janela de validade. Um certificado expirado ou ainda não válido não interrompe o aplicativo, mas assinaturas Certified são recusadas até que seja substituído. Assinaturas Visual não são afetadas.
  • Emitido para assinatura de documentos: um uso de chave com digital signature ou non-repudiation, e um uso estendido de chave, se presente, que permite assinatura de documentos, proteção de e‑mail ou autenticação de cliente. Um certificado emitido para outra finalidade, como um certificado de servidor TLS, ainda assina, mas leitores PDF sinalizam a assinatura.
  • Tokens de hardware, smart cards, HSMs e o armazenamento de certificados do Windows não são suportados. Exporte o certificado, com sua chave privada e cadeia, para um PFX.

Crie um PFX a partir de um certificado e sua chave privada com OpenSSL:

bash
openssl pkcs12 -export -out signing.pfx -inkey private.key -in certificate.crt
# A senha de exportação solicitada é SigningCertificate.Password.

Exporte um do armazenamento de certificados do Windows: abra certmgr.msc e encontre o certificado (seu ícone mostra uma chave quando a chave privada está presente). Clique com o botão direito, escolha All Tasks → Export…, selecione Yes, export the private key, escolha Personal Information Exchange – PKCS #12 (.PFX) e defina uma senha.

Verificações de inicialização

Quando o widget está habilitado, o certificado em SignerWidgetOptions.SigningCertificate é verificado uma vez, dentro de DoconutHost.Initialize, de modo que um PFX mal configurado falha na inicialização em vez de na primeira assinatura. Três problemas lançam um InvalidOperationException de Application_Start, e cada requisição então responde com um 500 vazio; a mensagem está no log de eventos do Windows:

MensagemCorreção
Doconut Signer: the certificate file was not found at '{path}'.Corrija PfxPath; certifique‑se de que o arquivo está implantado e legível pela conta do pool de aplicativos
Doconut Signer: the signing certificate could not be opened — the password is incorrect or the file is not a valid .pfx.Verifique a senha; certifique‑se de que o arquivo é um .pfx real, não um .cer ou .pem
Doconut Signer: the signing certificate has no private key. Re-export the .pfx INCLUDING the private key.Exporte o PFX novamente com a chave privada

No ASP.NET Core o host também registra uma linha na inicialização nomeando o certificado, ou avisando que ele está expirado ou não emitido para assinatura. DoconutHost não grava essa linha, portanto no .NET Framework verifique um novo certificado assinando um documento de teste no modo Certified.

A fachada C# não é verificada na inicialização. O certificado que você passa para SignAsync é lido quando você assina, de modo que um caminho ou senha incorretos falham nessa chamada.

Widget incorporado

Habilitar os endpoints

Os endpoints ?sign=open|run|download do widget são servidos por DocImage.axd e estão desativados por padrão. Habilite-os ao lado do registro do plugin:

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;           // o padrão
        widget.MaxSignatureImageKb = 512;  // o padrão
        // widget.SigningCertificate: veja a configuração do Certificate; deixe null para assinatura de demonstração (com marca d'água)
    });
});
// System.Web lê todo o upload antes que Doconut o veja: mantenha maxRequestLength (KB) e
// maxAllowedContentLength (bytes) em Web.config acima do MaxUploadMb do widget.

AddSignerWidget() sem argumento habilita o widget com as configurações padrão. Ele não concede assinatura por si só: precisa de AddPlugin<SignerPlugin>(), ou DoconutHost.Initialize lança:

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.

Os endpoints e o script são servidos pelo manipulador e pelo módulo registrado em 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>

O módulo serve o script independentemente de o widget estar habilitado. Sem AddSignerWidget(), o widget carrega e desenha sua zona de arraste, e sua primeira requisição responde 404: o widget então relata Signing is not enabled on this server.

Limites de upload

ASP.NET lê todo o corpo da requisição antes que DocImage.axd seja executado. Um upload acima de MaxUploadMb mas abaixo dos limites do host obtém o JSON próprio do widget 413 (File is too large.). Um upload acima dos limites do host é rejeitado primeiro pelo IIS, com uma página de erro que o widget não consegue ler. Mantenha ambos os limites do host acima do limite do widget:

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>

Um upload enviado sem um Content-Length (chunked) que excede os limites do host também recebe a página de erro do IIS; não há solução alternativa para esse caso.

Incorporar

O script é servido em /doconut-res/js/doconutSigner.js. É um único arquivo autônomo, sem dependências. Aponte basePath para o manipulador:

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) aceita um seletor CSS ou um elemento, lança erro se o ponto de montagem não for encontrado e retorna um manipulador. O basePath padrão do widget, /doconut, é o endpoint ASP.NET Core; neste pacote ele deve ser '/DocImage.axd'.

O assinante envia um PDF ou um arquivo .docx, cria uma assinatura (Draw em um canvas, Type um nome em uma fonte de assinatura, ou Image a partir de um PNG, JPG ou GIF), arrasta e redimensiona‑a na página, e assina e baixa o resultado. O widget sempre envia a assinatura como PNG; uma imagem enviada é convertida no navegador para PNG que se ajusta a 520×160.

Opções

OpçãoTipoPadrãoObservações
basePathstring'/doconut'Onde os endpoints ?sign= e as imagens de pré‑visualização são servidos. Defina '/DocImage.axd' neste pacote
resPathstring'/doconut-res'Reservado; o widget inclui seu próprio CSS
maxUploadMbnumber25Apenas verificação no cliente, portanto um arquivo muito grande falha rapidamente. O limite do servidor é MaxUploadMb em AddSignerWidget
maxSignatureKbnumber512Limite no cliente para o modo Imagem. Mantenha igual ao MaxSignatureImageKb do servidor
previewWidthnumber560Largura em pixels da pré‑visualização da página
licenseUrlstring | nullnullTransforma o aviso de marca d'água da demonstração em um link para esta URL
signatureModestring'certified'Tipo de assinatura inicial: 'certified' ou 'visual'. Qualquer outro valor torna‑se 'certified'
showSignatureModeTogglebooleantrueExibe a opção Digital signature / Visual only. Com false, o widget assina com signatureMode
wordOutputstring'pdf'Saída inicial para fontes .docx: 'pdf' ou 'docx'. Qualquer outro valor torna‑se 'pdf'
showOutputFormatTogglebooleantrueExibe a opção PDF / Word, apenas para fontes .docx. Com false, o widget usa wordOutput
labelsobject{}Sobrescreve qualquer subconjunto das strings em inglês

Ocultar um alternador não desativa a funcionalidade; ele fixa o valor. Duas configurações comuns:

javascript
// Ambos os alternadores são exibidos, assinatura digital por padrão: um assinante completo de autoatendimento.
Doconut.signer('#host', { basePath: '/DocImage.axd', licenseUrl: '/pricing' });
javascript
// Apenas visual, sem alternador: um selo simples sem assinatura digital oferecida.
Doconut.signer('#host', {
  basePath: '/DocImage.axd',
  signatureMode: 'visual',
  showSignatureModeToggle: false
});

Retornos de chamada

RetornoDispara quandoCarga
onReadyUma vez, ao montar (não novamente em reset())—
onSourceLoadedO arquivo é aberto e sua pré‑visualização é mostrada{ file: { token, name, pages, ext } }
onSignedA assinatura tem sucesso{ downloadToken, downloadName, watermarked }
onDownloadEm cada clique em Download{ downloadName, downloadToken }
onErrorUma etapa de abrir, assinar ou baixar falha, ou um arquivo no modo Imagem é muito grande{ message }

Um retorno de chamada que lança exceção é capturado e registrado; nunca interrompe o fluxo do widget.

Manipulador imperativo

MétodoComportamento
reset()Retorna à tela de arraste e limpa o fluxo atual. Não dispara onReady novamente. Não faz nada após destroy()
loadFile(file)Inicia o fluxo com um File. Não faz nada a menos que o widget esteja na tela de arraste; chame reset() primeiro se necessário
destroy()Remove os ouvintes, esvazia o ponto de montagem e congela a instância
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());

Rótulos

Cada string tem um padrão em inglês; labels substitui qualquer subconjunto e o restante permanece em inglês. Fragmentos que mudam em tempo de execução usam {placeholders}, como uploading: 'Uploading {name}…' e pages: '{n} pages'.

ChavePadrão em inglês
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

Outras chaves cobrem a etapa de posicionamento, a tela de erro, o formulário vinculado do aviso de demonstração (demoNoticePrefix, demoNoticeLink, demoNoticeSuffix) e os anúncios aria-live.

Quando open ou run respondem 404 sem erro JSON, o widget exibe signingNotEnabled. Um erro JSON do servidor sempre tem precedência, portanto mensagens como um upload expirado permanecem visíveis.

Tematização

O widget adiciona a classe dsw ao seu elemento de montagem e lê suas cores, raio e fontes das propriedades personalizadas CSS, para que você possa tematizá‑lo sem tocar em seus internos:

css
#host.dsw {
  --dsw-accent: #b0522b;       /* links, foco, modo ativo */
  --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;   /* o modo Type */
}

Padrões: --dsw-accent: #2b6cb0, --dsw-bg: #ffffff, --dsw-fg: #1a202c, --dsw-muted: #718096, --dsw-border: #cbd5e0, --dsw-radius: 8px, uma fonte de interface do sistema e uma fonte cursiva para assinatura.

Construa seu próprio frontend

O widget é um cliente para este contrato HTTP em DocImage.axd. As rotas respondem 404 até que AddSignerWidget() seja chamado. Erros carregam um corpo JSON, { "error": "..." }, exceto onde a tabela indica “apenas status”. Um valor desconhecido de ?sign= responde 400.

RotaPropósitoResposta de sucesso
POST /DocImage.axd?sign=open (multipart, um arquivo)Carregue um PDF ou .docx e abra‑o para visualização200 — { token, name, pages, ext }
POST /DocImage.axd?sign=run (corpo JSON)Assine o arquivo carregado200 — { downloadToken, downloadName, watermarked }
GET /DocImage.axd?sign=download&token=<downloadToken>Transmita o arquivo assinado200 — o arquivo, Content-Disposition: attachment, Cache-Control: no-store

ext na resposta open inclui o ponto inicial (".docx"). A visualização da página usa a rota padrão de imagem do visualizador, /DocImage.axd?token={token}&page={n}&thumb=1&width={px}; a página exibida torna‑se placement.page.

O corpo 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"
}
CampoObservações
tokenO token de open
signature.kindDrawn, Typed ou Image, sem diferenciação de maiúsculas/minúsculas; qualquer outro valor torna‑se Drawn. Apenas uma dica: a carga útil é sempre um PNG
signature.payloadUm PNG base64 puro, sem prefixo data:. Deve ser um PNG real e não maior que MaxSignatureImageKb após decodificado
placement.pageBaseado em 1
placement.x / y / w / hNormalizado 0..1 a partir do canto superior esquerdo, com x + w ≤ 1 e y + h ≤ 1
meta.signerName / reason / locationOpcional. Cada um é aparado, um valor em branco é descartado, e cada um é truncado em 256 caracteres
wordOutputpdf (padrão) ou docx; ignorado para fontes PDF. Qualquer outro valor torna‑se pdf
modecertified (padrão) ou visual. Qualquer outro valor torna‑se certified

downloadName segue a saída: <source>-signed.pdf ou <source>-signed.docx, e download envia o Content-Type correspondente.

A fonte carregada e o resultado assinado são mantidos cada um por 30 minutos. Depois disso, run e download respondem 404 e o arquivo deve ser aberto novamente. Todos os tokens são GUIDs.

RotaStatusQuandoCorpo
qualquer404O widget não está habilitadoapenas status
qualquer405Verbo errado (open e run precisam de POST, download precisa de GET)apenas status
open400Não é um upload multipartExpected a multipart file upload.
open400Nenhum arquivo, ou um vazioNo file uploaded.
open400Qualquer coisa diferente de .pdf ou .docxSigning supports PDF and Word (.docx) files only.
open413O upload excede MaxUploadMb (mas não os limites do IIS)File is too large.
run400O corpo não é JSON válido, ou está vazioMalformed request. / Empty request.
run400O token está ausente ou não é um GUIDInvalid token.
run404O upload expirou ou nunca foi abertoUpload expired — please re-open the file.
run400Sem assinatura, ou sem posicionamentoNo signature supplied. / No placement supplied.
run400A carga útil não é base64, está vazia, muito grande, ou não é um PNGSignature image is not valid base64. / Signature image is empty. / Signature image is too large. / The signature image must be a PNG.
run400O posicionamento está fora da páginaThe signature or its placement is invalid.
run400Modo certificado, licença paga e sem certificadoNo signing certificate configured.
run400Modo certificado com um certificado fora da janela de validadeThe signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd.
open, run500Processamento falhouUma mensagem sanitizada
download400O token está ausente ou não é um GUIDapenas status
download404Token desconhecido ou expiradoapenas status

Um ciclo completo com fetch:

javascript
// file: o File para assinar; pngBase64: a assinatura como um PNG base64 puro, sem prefixo data:,
// por exemplo canvas.toDataURL('image/png').split(',')[1].
async function signFile(file, pngBase64) {
  const base = '/DocImage.axd';

  // 1. open: carregar o arquivo
  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: assiná-lo
  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: obter o arquivo assinado
  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);
}

Os endpoints são same-origin: esta versão não tem suporte a CORS. Sirva sua UI e o script do widget a partir da mesma origem da aplicação, ou faça reverse-proxy de DocImage.axd e /doconut-res sob a origem da sua UI.

Em produção

  1. Instale o plugin ao lado do pacote core, na mesma versão: Install-Package Doconut.NETFramework.Signer.

  2. Adicione o arquivo de licença. Coloque Doconut.Viewer.Signer.lic na mesma pasta que Doconut.Viewer.lic.

  3. Obtenha seu certificado como um PFX com sua chave privada e cadeia de emissor, de uma autoridade certificadora ou da PKI própria da sua organização. Para experimentar primeiro, use uma licença demo (o certificado demo embutido, com marca d'água) ou um PFX autoassinado.

  4. Leia o certificado a partir da configuração, de modo que alterá‑lo nunca exija mudança de código:

    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"] ?? "",
        });
    });

    Mantenha o .pfx em App_Data, que o IIS nunca serve, e mantenha a senha fora de um Web.config simples: use uma seção de configuração criptografada, ou um repositório secreto que sua implantação lê.

  5. Assine um documento de teste no modo Certified. Um certificado que está expirado ou ainda não é válido é recusado com The signing certificate expired on yyyy-MM-dd. (ou is not valid before), e um leitor de PDF mostra se ele confia na assinatura.

Confiança em leitores de PDF. Um leitor mostra a assinatura como válida quando confia na raiz do certificado. Com a PKI da sua organização, isso vale para cada máquina que confia na sua raiz, que normalmente são todas as máquinas dentro da organização. Certificados que a Adobe confia em qualquer máquina (a Adobe Approved Trust List) são, até onde sabemos, emitidos com a chave privada em um token de hardware ou HSM, o que este plugin não pode usar: ele assina apenas a partir de um PFX. Confirme com seu provedor de certificados antes de confiar nesse tipo de confiança.

Fazendas web

O widget mantém cada upload e seu resultado na memória no servidor que serviu open. Por trás de um balanceador de carga sem sessões persistentes, uma solicitação posterior de run, download ou de pré‑visualização pode alcançar outro servidor e não encontrar o upload. Registre o armazenamento compartilhado e criptografado do widget através do segundo argumento de 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";   // uma pasta que todo servidor pode ler e gravar
        store.FarmKey = farmKey;                   // pelo menos 32 bytes, idêntico em todo servidor
        // store.Ttl = TimeSpan.FromMinutes(30);   // quanto tempo um upload é mantido (o padrão)
    }));
  • Um único servidor não precisa de nada: sem esta chamada, o armazenamento em memória é usado.
  • Uploads e resultados são criptografados em repouso no compartilhamento (AES-256, encrypt-then-MAC), e cada arquivo está vinculado ao seu token, de modo que um token nunca pode ler o arquivo de outro.
  • FarmKey deve ter pelo menos 32 bytes e ser o mesmo em todos os servidores. Carregue-o de um repositório secreto; nunca o codifique diretamente. O registro lança um ArgumentException quando RootPath está ausente ou FarmKey tem menos de 32 bytes.
  • Aponte RootPath para o mesmo local compartilhado que o visualizador distribuído usa, e forneça a cada servidor o mesmo certificado de assinatura.

Referência da API

A fachada e as opções do widget estão no namespace Doconut; os tipos de solicitação e resultado estão em Doconut.Core.Models.Signing. SignerPlugin está em Doconut.Plugins.Signer.

AssinadorDeDocumento

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

Resolvido a partir de DoconutHost.Services; o construtor é interno. sourceExtension é ".pdf" ou ".docx". Sob uma licença paga, cert é usado e a saída é limpa; sob uma licença temporária, o certificado de demonstração embutido é usado, cert é ignorado, e a saída recebe marca d'água.

SolicitaçãoDeAssinatura

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
}

Uma assinatura visível colocada uma vez, mais metadados opcionais do assinante.

AssinaturaVisível e TipoDeAssinatura

csharp
public sealed record VisibleSignature(SignatureKind Kind, byte[] PngBytes)
{
    public bool IsValid { get; }   // PngBytes não está vazio
}

public enum SignatureKind { Drawn, Typed, Image }

PngBytes é um PNG para cada tipo. Uma assinatura desenhada ou digitada é transparente; uma imagem enviada mantém a transparência que tinha, portanto um JPG opaco permanece opaco. Kind é apenas uma dica.

PosicionamentoDeAssinatura

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 é baseado em 1; X, Y, W e H são 0..1 normalizados a partir do canto superior esquerdo.

ModoDeAssinatura e SaídaWord

csharp
public enum SignatureMode { Certified, Visual }   // Certified é o padrão
public enum WordOutput { Pdf, Docx }              // Pdf é o padrão; ignorado para fontes PDF

ResultadoDaAssinatura

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

O documento assinado como um fluxo buscável, e sua extensão com o ponto (".pdf" ou ".docx").

CertificadoDeAssinatura

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 não está vazio, ou PfxPath não está em branco
}

Defina ou PfxBytes ou PfxPath, além de Password. Os setters são apenas init: o projeto requer C# 9.0 ou posterior.

OpçõesDoWidgetDeAssinante

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

Defina através de DoconutOptions.AddSignerWidget(Action<SignerWidgetOptions>? configure = null), que retorna o DoconutOptions para que as chamadas possam ser encadeadas. Um SigningCertificate nulo significa o certificado de demonstração sob uma licença temporária, e assinaturas Visuais somente sob uma licença paga.

Solução de Problemas

SintomaCausaCorreção
Todas as solicitações retornam um 500 vazio após adicionar o plugin; o log de eventos mostra The Signer plugin is registered via AddPlugin but no active license grants Signer.Sem licença, um arquivo TRIAL, uma licença sem Signer, ou uma licença paga fora da sua janela de versãoInstale uma licença que conceda Signer, ou remova AddPlugin<SignerPlugin>()
O log de eventos mostra AddSignerWidget() was called but the Signer plugin is not registered.O widget está habilitado sem seu pluginAdicione options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>()
O log de eventos mostra Doconut Signer: the certificate file was not found at '{path}'.PfxPath aponta para um arquivo ausenteCorrija o caminho; implante o arquivo onde a conta do pool de aplicativos possa lê-lo
O log de eventos mostra Doconut Signer: the signing certificate could not be opened — the password is incorrect or the file is not a valid .pfx.Senha errada, ou não é um arquivo PKCS#12Verifique a senha; use um verdadeiro .pfx
O log de eventos mostra Doconut Signer: the signing certificate has no private key. Re-export the .pfx INCLUDING the private key.O PFX foi exportado sem sua chave privadaExporte novamente com a chave privada
new SigningCertificate { … } não compilaO projeto usa C# 7.3, que não pode definir propriedades somente initDefina <LangVersion> para 9.0 ou posterior
Resolver DocumentSigner lança No IDocumentSigner is registered.SignerPlugin não está registradoAdicione AddPlugin<SignerPlugin>() em DoconutHost.Initialize
A saída tem marca d'águaA licença é temporária (Demo/NFR)Use uma licença paga que conceda Signer
run responde 400 No signing certificate configured.Uma licença paga, modo Certificado, e sem certificadoConfigure SigningCertificate, ou assine no modo Visual
run responde 400 The signing certificate expired on yyyy-MM-dd.O certificado está desatualizadoSubstitua-o; assinaturas Visuais continuam funcionando enquanto isso
O widget carrega mas diz Signing is not enabled on this server.AddSignerWidget() não foi chamado, ou basePath não está '/DocImage.axd'Chame AddSignerWidget(); defina basePath: '/DocImage.axd'
Um upload grande mostra uma página de erro IIS ao invés da mensagem do widgetmaxRequestLength / maxAllowedContentLength estão abaixo de MaxUploadMbAumente ambos os limites de host acima de MaxUploadMb
run responde 400 The signature image must be a PNG., Signature image is not valid base64. ou Signature image is too large.Uma UI personalizada enviou uma URL data:, um JPG, ou mais de MaxSignatureImageKbEnvie um PNG base64 puro dentro do limite
open responde 413 File is too large.O upload excede MaxUploadMbAumente MaxUploadMb em AddSignerWidget; o maxUploadMb do widget é apenas uma verificação do lado do cliente
run ou download responde 404 Upload expired — please re-open the file.A janela de 30 minutos expirou, ou outro servidor na fazenda não tem o uploadAbra o arquivo novamente; em uma fazenda, registre AddDoconutDistributedWidgets
Um .docx assinado não mostra assinatura em alguns visualizadoresA saída Word contém uma assinatura de pacote OOXML, que muitos visualizadores não exibemAssine para PDF, o padrão
Leitores de PDF dizem que a identidade do assinante é desconhecidaO leitor não confia na raiz do certificado (o certificado de demonstração nunca é confiável)Use um certificado de uma raiz que seus leitores confiem
O widget falha quando a UI está em outra origemOs endpoints não têm suporte a CORSSirva a UI da mesma origem, ou faça reverse-proxy de DocImage.axd e /doconut-res
O tema não é aplicadoO seletor aponta para um elemento dentro da montagemAponte para a própria montagem: #host.dsw ou #host

Notas do framework

Comparado aos pacotes ASP.NET Core, este pacote difere apenas na hospedagem; a API, o contrato de endpoint, o script do widget e as regras de licenciamento são os mesmos.

  • Registro está em Application_Start, através de DoconutHost.Initialize, em vez de builder.Services.AddDoconut. Serviços como AddDoconutDistributedWidgets vão em seu segundo argumento.
  • Endpoints são servidos por DocImage.axd e o script por DoconutResourceModule, ambos registrados em Web.config, em vez de UseDoconut() e UseDoconutResources(). O widget precisa de basePath: '/DocImage.axd'.
  • Falhas de inicialização aparecem como um 500 vazio em cada requisição, com a razão no log de eventos do Windows.
  • Uploads são lidos completamente pelo ASP.NET antes que o Doconut os veja, portanto os limites do IIS devem estar acima de MaxUploadMb.
  • Nenhuma linha de log de inicialização sobre o certificado: os três erros de certificado ainda são lançados, mas a linha que nomeia o certificado não é escrita.
  • C# 9.0 ou posterior é necessário para definir as propriedades somente de inicialização de SigningCertificate.
  • Somente Windows, como o resto do pacote .NET Framework.

Esta página foi útil?