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ícieQuando usar
DocumentSigner (C#)Você assina no servidor, sem navegador envolvido
Widget incorporado (doconutSigner.js)Você quer uma tela pronta de upload, assinatura e download na sua página
Endpoints HTTP (?sign=open|run|download)Você cria sua própria UI 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 acompanhar a assinatura.

Instalar o pacote

Instale o plugin Signer estável mais recente:

bash
dotnet add package Doconut.NET8.Signer

Para fixar o plugin na versão que esta documentação descreve, passe a versão separadamente:

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

Mantenha o pacote Signer na mesma versão que Doconut.NET8. O ID do pacote é Doconut.NET8.Signer; .<version> aparece apenas no nome de arquivo .nupkg baixado.

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

Plataformas. O plugin funciona onde Doconut.NET8 funciona: Windows e Linux baseado em glibc em x64 (não Alpine ou outras distribuições baseadas em musl). No Linux, instale a biblioteca de configuração de fontes antes que o primeiro documento seja aberto:

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

Em RHEL, Fedora e distribuições semelhantes o pacote é fontconfig. Sem ele, abrir um documento falha com The system library libfontconfig1 is missing. Install it (Debian/Ubuntu: apt-get install -y libfontconfig1) and see the Linux section of the Doconut documentation.

Registrar o plugin

Como todo plugin Doconut, o Signer registra-se com AddPlugin<TPlugin>() dentro de AddDoconut():

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

Isso é tudo que a fachada C# precisa. O widget e seus endpoints 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, AddDoconut() lança uma exceção na inicialização, antes que o aplicativo atenda a uma requisição:

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.

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 para como as licenças são carregadas.

Licenciamento & 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álidoInicia (com o widget habilitado, um Aviso é registrado)Recusado: The signing certificate expired on yyyy-MM-dd.Limpo
Licença temporária Demo/NFR, ativa ou expiradaIniciaSelado com o certificado demo embutido, com 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ãoAddDoconut() lança exceção——

A regra é a mesma para a fachada C# e o widget: a saída tem 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 embutido, 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 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 AddDoconut() e resolvido por injeção de dependência. Seu construtor é interno, portanto nunca new ele. Resolvê-lo 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 defaults to Certified (assinatura visível + selo digital); WordOutput defaults to 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 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ê é o proprietário do fluxo: descarte‑o quando terminar.

Uma assinatura Visual carimba apenas a imagem e não precisa de certificado:

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

Uma fonte Word é assinada para PDF, a menos que você solicite saída Word. Nomeie o resultado de 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 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, uma 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 Word e certificados

Modos de assinatura

SignRequest.Mode escolhe se a assinatura é selada.

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

Use Certified quando a assinatura precisa 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. Eles 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 (default)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:

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

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

Requisitos:

  • Um pacote PFX / PKCS#12 com sua chave privada. Um arquivo apenas com chave pública (.cer, .crt) não pode assinar. Exporte a cadeia do emissor junto, para que os selos PDF a carreguem.
  • A senha correta.
  • Dentro de sua janela de validade. Um certificado expirado ou ainda não válido não interrompe o aplicativo: ele é registrado como Aviso na inicialização, e assinaturas Certificadas são recusadas até que seja substituído. Assinaturas Visuais não são afetadas.
  • Emitido para assinatura de documentos: um uso de chave com assinatura digital ou não-repúdio, 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 é registrado como Aviso e leitores de 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 a partir 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 AddDoconut(), de modo que um PFX mal configurado falha na inicialização em vez de na primeira assinatura. Três problemas geram um InvalidOperationException:

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 aplicativo
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

Caso contrário, o host grava uma linha no log ao iniciar. Informação quando o certificado está pronto:

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

Um Aviso quando está expirado, ainda não válido ou não emitido para assinatura de documentos:

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.

E Informação quando nenhum certificado está configurado:

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.

Essa última linha é a mesma em todas as licenças. Sob uma licença paga o certificado de demonstração nunca é usado: sem certificado, apenas assinaturas Visuais funcionam.

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

Widget incorporável

Ativar os endpoints

Os endpoints ?sign=open|run|download do widget estão desativados por padrão. Ative-os ao lado do registro do plugin:

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath = "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: ver configuração do Certificate; deixe nulo para assinatura de demonstração (com marca d'água)
    });
});

AddSignerWidget() sem argumento habilita o widget com os padrões. Ele não concede assinatura por si só: ele precisa de AddPlugin<SignerPlugin>(), ou AddDoconut() 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.

Sem AddSignerWidget(), toda requisição ?sign= responde com 404. O script ainda é servido, portanto o widget carrega e pinta sua zona de arraste, então relata Signing is not enabled on this server. na primeira requisição.

Incorporá-lo

UseDoconutResources() serve o script em {ResourcesPath}/js/doconutSigner.js (padrão /doconut-res/js/doconutSigner.js). É um único arquivo autônomo sem dependências:

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) aceita um seletor CSS ou um elemento, lança erro se a montagem não for encontrada e retorna um manipulador.

O assinante faz upload de um PDF ou arquivo .docx, cria uma assinatura (Desenhar em um canvas, Digitar um nome em uma fonte de assinatura, ou Imagem a partir de 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 cabe em 520×160.

Opções

OpçãoTipoPadrãoObservações
basePathstring'/doconut'Onde os endpoints ?sign= e as imagens de pré‑visualização são servidos
resPathstring'/doconut-res'Reservado; o widget inclui seu próprio CSS
maxUploadMbnumber25Verificação apenas no cliente, portanto um arquivo muito grande falha rapidamente. O limite do servidor é MaxUploadMb em AddSignerWidget
maxSignatureKbnumber512Limite no cliente para o modo Imagem. Mantenha‑lo 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 escolha Assinatura digital / Apenas visual. 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 escolha PDF / Word, apenas para fontes .docx. Com false, o widget usa wordOutput
labelsobject{}Substitui qualquer subconjunto das strings em inglês

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

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

Retornos de chamada

Retorno de chamadaDispara quandoCarga
onReadyUma vez, ao montar (não novamente em reset())—
onSourceLoadedO arquivo é aberto e sua pré‑visualização exibida{ 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 erro é capturado e registrado; ele nunca interrompe o fluxo do widget.

Manipulador imperativo

MétodoComportamento
reset()Retorna à tela de queda 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 sua tela de queda; chame reset() primeiro se necessário
destroy()Remove os listeners, esvazia o ponto de montagem e congela a instância
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());

Rótulos

Cada string tem um padrão em inglês; labels substitui qualquer subconjunto e o resto 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 prevalece, 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 UI do sistema e uma fonte cursiva para assinatura.

Construa seu próprio frontend

O widget é um cliente para este contrato HTTP. Todas as três rotas ficam sob o caminho onde UseDoconut() está montado (normalmente /doconut), e elas 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 ?sign=open (multipart, one file)Carrega um PDF ou .docx e abre para visualização200 — { token, name, pages, ext }
POST ?sign=run (JSON body)Assina o arquivo carregado200 — { downloadToken, downloadName, watermarked }
GET ?sign=download&token=<downloadToken>Transmite o arquivo assinado200 — o arquivo, Content-Disposition: attachment, Cache-Control: no-store

ext na resposta open inclui o ponto inicial (".docx"). A pré‑visualização da página usa a rota padrão de imagem do visualizador, {basePath}?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 distinção entre maiúsculas e minúsculas; qualquer outro se torna Drawn. Apenas uma dica: o payload é 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 / h0..1 normalizado a partir do canto superior esquerdo, com x + w ≤ 1 e y + h ≤ 1
meta.signerName / reason / locationOpcional. Cada um é aparado, valores em branco são descartados e cada um é cortado em 256 caracteres
wordOutputpdf (padrão) ou docx; ignorado para fontes PDF. Qualquer outro se torna pdf
modecertified (padrão) ou visual. Qualquer outro se torna 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
any404O widget não está habilitadoapenas status
any405Verbo 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 MaxUploadMbFile 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.
run400Nenhuma assinatura, ou nenhum posicionamentoNo signature supplied. / No placement supplied.
run400O payload não é base64, está vazio, 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 a ser assinado; 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 = '/doconut';

  // 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 que o Doconut, ou faça reverse-proxy de ambos os caminhos /doconut (o caminho do middleware e o caminho dos recursos) sob a origem da sua UI.

Em produção

  1. Instale o plugin ao lado do pacote principal, na mesma versão: dotnet add package Doconut.NET8.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 testar primeiro, use uma licença demo (o certificado de demonstração 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:

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

    Mantenha o .pfx fora do wwwroot, e mantenha a senha fora do appsettings.json: segredos de usuário em desenvolvimento (dotnet user-secrets set "DoconutSigner:Password" "<password>"), uma variável de ambiente (DoconutSigner__Password) ou um cofre em produção.

  5. Verifique o log de inicialização. Ele deve exibir using certificate '{subject}' (valid until …). Signatures are digitally sealed.. Um Aviso, em vez disso, significa que o certificado está expirado, ainda não é válido, ou não foi emitido para assinatura de documentos.

Confiança em leitores de PDF. Um leitor exibe 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. Os 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 o seu provedor de certificados antes de depender desse tipo de confiança.

Fazendas de servidores

O widget mantém cada upload e seu resultado na memória do nó que serviu open. Por trás de um balanceador de carga sem sessões persistentes, uma solicitação posterior de run, download ou de visualização pode alcançar outro nó e não encontrar o upload. Registre o armazenamento compartilhado e criptografado do widget uma única vez, após AddDoconut():

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

builder.Services.AddDoconutDistributedWidgets(store =>
{
    store.RootPath = @"\\fileshare\doconut";   // uma pasta que todo nó pode ler e escrever
    store.FarmKey = farmKey;                   // pelo menos 32 bytes, idêntico em cada nó
    // 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 nós. Carregue‑o de um armazenamento de segredos; nunca o codifique diretamente. O registro lança um ArgumentException quando RootPath está ausente ou FarmKey é menor que 32 bytes.
  • Aponte RootPath para o mesmo local compartilhado que o visualizador distribuído usa, e forneça a cada nó 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.

DocumentSigner

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

Resolvido por injeção de dependência; 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.

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
}

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

VisibleSignature e SignatureKind

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.

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

SignatureMode e WordOutput

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

SignResult

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").

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

Defina PfxBytes ou PfxPath, além de Password.

SignerWidgetOptions

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

Definido 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 apenas sob uma licença paga.

Solução de Problemas

SintomaCausaCorreção
AddDoconut() lança 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>()
AddDoconut() lança AddSignerWidget() was called but the Signer plugin is not registered.O widget está habilitado sem seu pluginAdicione options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>()
AddDoconut() lança 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 aplicativo possa lê-lo
AddDoconut() lança Doconut Signer: the signing certificate could not be opened — the password is incorrect or the file is not a valid .pfx.Senha incorreta, ou não é um arquivo PKCS#12Verifique a senha; use um verdadeiro .pfx
AddDoconut() lança 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-o novamente com a chave privada
Resolver DocumentSigner lança No IDocumentSigner is registered.SignerPlugin não está registradoAdicione AddPlugin<SignerPlugin>() dentro de AddDoconut()
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 log diz que a saída "usa o certificado de demonstração embutido", porém uma licença paga recusa assinaturas CertificadasEssa linha é escrita sempre que nenhum certificado está configurado, independentemente da licençaConfigure SigningCertificate
O widget carrega mas exibe Signing is not enabled on this server.AddSignerWidget() não foi chamado, ou basePath não corresponde ao local onde UseDoconut() está montadoChame AddSignerWidget(); corrija basePath
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 um 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 MaxUploadMbEleve 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 um nó da fazenda web 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 do 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 a partir da mesma origem, ou faça reverse-proxy dos caminhos Doconut
O tema não é aplicadoO seletor aponta para um elemento dentro da montagemAponte para a própria montagem: #host.dsw ou #host

Esta página foi útil?