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, sela‑o 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ície | Quando usar |
|---|---|
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 |
HTTP endpoints (?sign=open|run|download) | Você constrói 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
Instale o plugin Signer estável mais recente:
dotnet add package Doconut.NET6.SignerPara fixar o plugin na versão que esta documentação descreve, passe a versão separadamente:
dotnet add package Doconut.NET6.Signer --version 26.10.0Mantenha o pacote Signer na mesma versão que Doconut.NET6. O ID do pacote é Doconut.NET6.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 quer que Doconut.NET6 funcione: 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:
apt-get update && apt-get install -y libfontconfig1No 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():
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:
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 e marca d'água
| Estado da licença | Inicialização | Assinatura certificada | Assinatura visual |
|---|---|---|---|
Licença paga concedendo Signer, certificado configurado | Inicia | Selado com seu certificado, limpo (watermarked: false) | Limpo |
Licença paga concedendo Signer, sem certificado | Inicia | Recusado: No signing certificate configured. | Limpo |
| Licença paga, certificado expirado ou ainda não válido | Inicia (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 expirada | Inicia | Selado com o certificado de demonstração 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ão | AddDoconut() lança exceção | — | — |
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 de demonstração embutido, e qualquer certificado que você configure não é usado.
O certificado de demonstração 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 AddDoconut() e resolvido por injeção de dependência. Seu construtor é interno, portanto nunca new ele. Resolva‑lo sem AddPlugin<SignerPlugin>() lança No IDocumentSigner is registered. Add the signing plugin: options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>().
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, 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.
Uma assinatura Visual carimba apenas a imagem e não necessita de certificado:
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 em Word. Nomeie o resultado de result.Extension:
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ção | Mensagem | Quando |
|---|---|---|
InvalidOperationException | No signing certificate configured. | Modo Certificado, uma licença paga, e nenhum certificado fornecido |
InvalidOperationException | The 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 |
ArgumentException | The 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 |
NotSupportedException | The 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.
| Modo | O que produz | Certificado | Verificável |
|---|---|---|---|
SignatureMode.Certified (default) | A assinatura visível mais um selo digital | Necessário sob uma licença paga | Sim |
SignatureMode.Visual | Apenas a assinatura visível | Nunca necessário | Não: é uma imagem |
Use Certified quando a assinatura precisar ser comprovável: aprovações, contratos, qualquer coisa que um verificador precise checar para identidade e integridade. Use Visual quando você precisar apenas da aparência de uma assinatura, ou não possuir 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 contêm os certificados do emissor encontrados no seu PFX, de modo que um leitor que confie na sua raiz possa construir a cadeia. Selos nativos do Word são assinaturas de pacote OOXML e contêm 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ída | O que acontece | Suporte do verificador |
|---|---|---|
WordOutput.Pdf (default) | O documento é convertido para PDF, então assinado e selado | Amplo: um PDF assinado verifica em qualquer lugar |
WordOutput.Docx | O documento permanece Word: a imagem da assinatura é inserida nele, além de uma assinatura de pacote OOXML | Limitado: nem todo visualizador mostra assinaturas de pacote OOXML |
Mantenha PDF a menos que o destinatário precise de um arquivo Word editável e aceite o suporte de verificador limitado.
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:
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"],
};
});
});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, devolvido 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:
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 localize o certificado (seu ícone mostra uma chave quando a chave privada está presente). Clique com o botão direito, escolha Todas as Tarefas → Exportar…, selecione Sim, exportar a chave privada, escolha Troca de Informações Pessoais – 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 ao invés de na primeira assinatura. Três problemas lançam um InvalidOperationException:
| Mensagem | Correçã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:
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:
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:
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:
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: veja a configuração do certificado; deixe null para assinatura de demonstração (com marca d'água)
});
});AddSignerWidget() sem argumentos habilita o widget com as configurações padrão. Ele não concede assinatura por si só: precisa de AddPlugin<SignerPlugin>(), ou AddDoconut() lança:
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 solicitação ?sign= responde com 404. O script em si ainda é servido, portanto o widget carrega e pinta sua zona de arraste, então relata Signing is not enabled on this server. na primeira solicitação.
Incorporar
UseDoconutResources() serve o script em {ResourcesPath}/js/doconutSigner.js (padrão /doconut-res/js/doconutSigner.js). É um único arquivo autônomo sem dependências:
<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 um erro se a montagem não for encontrada e retorna um manipulador.
O assinante envia 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 um PNG, JPG ou GIF), arrasta e redimensiona 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ção | Tipo | Padrão | Observações |
|---|---|---|---|
basePath | string | '/doconut' | Onde os endpoints ?sign= e as imagens de visualização são servidos |
resPath | string | '/doconut-res' | Reservado; o widget inclui seu próprio CSS |
maxUploadMb | number | 25 | Verificação apenas no cliente, portanto um arquivo muito grande falha rapidamente. O limite do servidor é MaxUploadMb em AddSignerWidget |
maxSignatureKb | number | 512 | Limite no cliente para o modo Imagem. Mantenha‑lo igual ao MaxSignatureImageKb do servidor |
previewWidth | number | 560 | Largura em pixels da visualização da página |
licenseUrl | string | null | null | Transforma o aviso de marca‑d'água da demonstração em um link para esta URL |
signatureMode | string | 'certified' | Tipo de assinatura inicial: 'certified' ou 'visual'. Qualquer outro valor torna‑se 'certified' |
showSignatureModeToggle | boolean | true | Mostra a opção Assinatura digital / Apenas visual. Com false, o widget assina com signatureMode |
wordOutput | string | 'pdf' | Saída inicial para fontes .docx: 'pdf' ou 'docx'. Qualquer outro valor torna‑se 'pdf' |
showOutputFormatToggle | boolean | true | Mostra a opção PDF / Word, apenas para fontes .docx. Com false, o widget usa wordOutput |
labels | object | {} | Substitui qualquer subconjunto das strings em inglês |
Ocultar um interruptor não desativa a funcionalidade; ele fixa o valor. Duas configurações comuns:
// Ambos os alternadores exibidos, assinatura digital por padrão: um assinante completo de autoatendimento
Doconut.signer('#host', { basePath: '/doconut', licenseUrl: '/pricing' });// Somente visual, sem alternador: um selo simples sem assinatura digital oferecida
Doconut.signer('#host', {
basePath: '/doconut',
signatureMode: 'visual',
showSignatureModeToggle: false
});Retornos de chamada
| Retorno de chamada | Dispara quando | Carga |
|---|---|---|
onReady | Uma vez, ao montar (não novamente em reset()) | — |
onSourceLoaded | O arquivo é aberto e sua visualização mostrada | { file: { token, name, pages, ext } } |
onSigned | A assinatura tem sucesso | { downloadToken, downloadName, watermarked } |
onDownload | Em cada clique em Download | { downloadName, downloadToken } |
onError | Uma etapa de abrir, assinar ou baixar falha, ou um arquivo no modo Imagem é muito grande | { message } |
Um callback que lança uma exceção é capturado e registrado; ele nunca interrompe o fluxo do widget.
Manipulador imperativo
| Método | Comportamento |
|---|---|
reset() | Retorna à tela de descarte 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 descarte; chame reset() primeiro se necessário |
destroy() | Remove os listeners, esvazia o mount e congela a instância |
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 restante permanece em inglês. Fragmentos que mudam em tempo de execução usam {placeholders}, como uploading: 'Uploading {name}…' e pages: '{n} pages'.
| Chave | Padrão em inglês |
|---|---|
dropPrompt | Drag & drop a PDF or Word file here |
dropHint | PDF or Word (.docx) |
chooseFile | Choose file |
signatureHeading | Your signature |
modeDraw / modeType / modeImage | Draw / Type / Image |
metaSummary | Signature details (optional) |
metaSignerName / metaReason / metaLocation | Signer name / Reason / Location |
signatureType | Signature type |
modeCertified / modeVisual | Digital signature / Visual only |
modeVisualNote | No certificate — a visible mark only, not cryptographically verifiable. |
outputFormat | Output format |
outputPdf / outputWord | PDF / Word (.docx) |
signAction | Sign document |
download | Download |
demoNotice | Demo — signed with the Doconut demo certificate; output is watermarked. |
signingNotEnabled | Signing is not enabled on this server. |
page / pages | 1 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 a partir de propriedades customizadas CSS, permitindo que você o tematize sem tocar em seus internos:
#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 deste 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.
| Rota | Propósito | Resposta de sucesso |
|---|---|---|
POST ?sign=open (multipart, one file) | Carregar um PDF ou .docx e abri‑lo para pré‑visualização | 200 — { token, name, pages, ext } |
POST ?sign=run (JSON body) | Assinar o arquivo carregado | 200 — { downloadToken, downloadName, watermarked } |
GET ?sign=download&token=<downloadToken> | Transmitir o arquivo assinado | 200 — o arquivo, Content-Disposition: attachment, Cache-Control: no-store |
O 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:
{
"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"
}| Campo | Observações |
|---|---|
token | O token de open |
signature.kind | Drawn, Typed ou Image, sem distinção entre maiúsculas e minúsculas; qualquer outro valor torna‑se Drawn. Apenas uma dica: o payload é sempre um PNG |
signature.payload | Um PNG base64 puro, sem prefixo data:. Deve ser um PNG real e não maior que MaxSignatureImageKb após decodificado |
placement.page | Baseado em 1 |
placement.x / y / w / h | 0..1 normalizado a partir do canto superior esquerdo, com x + w ≤ 1 e y + h ≤ 1 |
meta.signerName / reason / location | Opcional. Cada um é aparado, valores em branco são descartados e cada um é truncado em 256 caracteres |
wordOutput | pdf (padrão) ou docx; ignorado para fontes PDF. Qualquer outro valor torna‑se pdf |
mode | certified (padrão) ou visual. Qualquer outro valor torna‑se certified |
O 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. Após isso, run e download respondem 404 e o arquivo deve ser aberto novamente. Todos os tokens são GUIDs.
| Rota | Status | Quando | Corpo |
|---|---|---|---|
| qualquer | 404 | O widget não está habilitado | apenas status |
| qualquer | 405 | Verbo errado (open e run precisam de POST, download precisa de GET) | apenas status |
open | 400 | Não é um upload multipart | Expected a multipart file upload. |
open | 400 | Nenhum arquivo, ou um vazio | No file uploaded. |
open | 400 | Qualquer coisa diferente de .pdf ou .docx | Signing supports PDF and Word (.docx) files only. |
open | 413 | O upload excede MaxUploadMb | File is too large. |
run | 400 | O corpo não é JSON válido, ou está vazio | Malformed request. / Empty request. |
run | 400 | O token está ausente ou não é um GUID | Invalid token. |
run | 404 | O upload expirou ou nunca foi aberto | Upload expired — please re-open the file. |
run | 400 | Nenhuma assinatura, ou nenhum posicionamento | No signature supplied. / No placement supplied. |
run | 400 | O payload não é base64, está vazio, muito grande, ou não é um PNG | Signature image is not valid base64. / Signature image is empty. / Signature image is too large. / The signature image must be a PNG. |
run | 400 | O posicionamento está fora da página | The signature or its placement is invalid. |
run | 400 | Modo certificado, licença paga e sem certificado | No signing certificate configured. |
run | 400 | Modo certificado com um certificado fora da janela de validade | The signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd. |
open, run | 500 | Processamento falhou | Uma mensagem sanitizada |
download | 400 | O token está ausente ou não é um GUID | apenas status |
download | 404 | Token desconhecido ou expirado | apenas status |
Um ciclo completo com fetch:
// file: o Arquivo 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: enviar 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
-
Instale o plugin ao lado do pacote principal, na mesma versão:
dotnet add package Doconut.NET6.Signer. -
Adicione o arquivo de licença. Coloque
Doconut.Viewer.Signer.licna mesma pasta queDoconut.Viewer.lic. -
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 de demonstração (o certificado de demonstração embutido, com marca d'água) ou um PFX autoassinado.
-
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" }csharpvar 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
.pfxfora dowwwroot, e mantenha a senha fora doappsettings.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. -
Verifique o log de inicialização. Ele deve exibir
using certificate '{subject}' (valid until …). Signatures are digitally sealed.. Um Aviso, ao invés 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 todas as máquinas que confiam na sua raiz, que geralmente 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 seu fornecedor 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 nó que serviu open. Atrá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 nó e não encontrar o upload. Registre o armazenamento compartilhado e criptografado do widget uma única vez, após AddDoconut():
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 todo 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.
FarmKeydeve 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 umArgumentExceptionquandoRootPathestá ausente ouFarmKeyé mais curto que 32 bytes.- Aponte
RootPathpara 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
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
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 and SignatureKind
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
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 and WordOutput
public enum SignatureMode { Certified, Visual } // Certified é o padrão
public enum WordOutput { Pdf, Docx } // Pdf é o padrão; ignorado para fontes PDFSignResult
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
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
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
| Sintoma | Causa | Correçã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ão | Instale 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 plugin | Adicione options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>() |
AddDoconut() lança Doconut Signer: the certificate file was not found at '{path}'. | PfxPath aponta para um arquivo ausente | Corrija o caminho; implante o arquivo onde a conta do aplicativo pode 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 errada, ou não é um arquivo PKCS#12 | Verifique 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 privada | Exporte novamente com a chave privada |
Resolver DocumentSigner lança No IDocumentSigner is registered. | SignerPlugin não está registrado | Adicione AddPlugin<SignerPlugin>() dentro de AddDoconut() |
| A saída tem marca d'água | A 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 certificado | Configure SigningCertificate, ou assine no modo Visual |
run responde 400 The signing certificate expired on yyyy-MM-dd. | O certificado está desatualizado | Substitua-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 rejeita assinaturas Certificadas | Essa linha é escrita sempre que nenhum certificado está configurado, independentemente da licença | Configure SigningCertificate |
O widget carrega mas diz Signing is not enabled on this server. | AddSignerWidget() não foi chamado, ou basePath não corresponde ao local onde UseDoconut() está montado | Chame 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 uma URL data:, um JPG, ou mais de MaxSignatureImageKb | Envie um PNG base64 puro dentro do limite |
open responde 413 File is too large. | O upload excede MaxUploadMb | Aumente 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 web-farm não tem o upload | Abra o arquivo novamente; em uma farm, registre AddDoconutDistributedWidgets |
Um .docx assinado não mostra assinatura em alguns visualizadores | A saída Word contém uma assinatura de pacote OOXML, que muitos visualizadores não exibem | Assine para PDF, o padrão |
| Leitores de PDF dizem que a identidade do assinante é desconhecida | O 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 origem | Os endpoints não têm suporte a CORS | Sirva a UI da mesma origem, ou faça reverse-proxy dos caminhos Doconut |
| O tema não é aplicado | O seletor aponta para um elemento dentro da montagem | Aponte para a própria montagem: #host.dsw ou #host |
Esta página foi útil?