Plugin Signer
Firma documenti PDF e Word con una firma visibile e un sigillo digitale
Il plugin Signer posiziona una firma visibile su un documento e, per impostazione predefinita, lo sigilla con una firma digitale che un lettore PDF può verificare. Firma file PDF e Word (.docx). La firma visibile è sempre un'immagine PNG: disegnata, digitata o caricata dal firmatario.
| Superficie | Quando usarlo |
|---|---|
DocumentSigner (C#) | Firma sul server, senza coinvolgere il browser |
Drop-in widget (doconutSigner.js) | Desideri una schermata pronta per il caricamento, la firma e il download nella tua pagina |
HTTP endpoints (?sign=open|run|download) | Costruisci la tua interfaccia di firma contro un contratto server documentato |
Ogni firma viene posizionata una sola volta, su una pagina. Il nome del firmatario, il motivo e la posizione possono accompagnarla.
Installa il pacchetto
Installa l'ultimo plugin Signer stabile:
dotnet add package Doconut.NET6.SignerPer fissare il plugin alla versione descritta in questa documentazione, passa la versione separatamente:
dotnet add package Doconut.NET6.Signer --version 26.10.0Mantieni il pacchetto Signer alla stessa versione di Doconut.NET6. L'ID del pacchetto è Doconut.NET6.Signer; .<version> appare solo nel nome file scaricato .nupkg.
Il file di licenza del plugin, Doconut.Viewer.Signer.lic, va nella stessa cartella di Doconut.Viewer.lic; viene letto insieme alla licenza del visualizzatore.
Piattaforme. Il plugin funziona ovunque Doconut.NET6 funzioni: Windows e Linux basato su glibc su x64 (non Alpine o altre distribuzioni basate su musl). Su Linux, installa la libreria di configurazione dei font prima che il primo documento si apra:
apt-get update && apt-get install -y libfontconfig1Su RHEL, Fedora e distribuzioni simili il pacchetto è fontconfig. Senza di esso, l'apertura di un documento fallisce con The system library libfontconfig1 is missing. Install it (Debian/Ubuntu: apt-get install -y libfontconfig1) and see the Linux section of the Doconut documentation.
Registra il plugin
Come ogni plugin Doconut, Signer si registra con AddPlugin<TPlugin>() all'interno di AddDoconut():
builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
});Questo è tutto ciò di cui ha bisogno la facciata C#. Il widget e i suoi endpoint HTTP sono un'opzione separata, AddSignerWidget() (vedi Widget incorporato).
Il plugin necessita di una licenza che conceda la capacità Signer. Senza di essa, AddDoconut() genera un'eccezione all'avvio, prima che l'app risponda a una richiesta:
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.Genera un'eccezione per assenza di licenza, un file legacy TRIAL, una licenza senza Signer, e una licenza a pagamento usata al di fuori della sua finestra di versione. Le licenze Demo/NFR temporanee sono accettate. Vedi Configurazione licenza per come vengono caricate le licenze.
Licenze e filigrana
| Stato licenza | Avvio | Firma certificata | Firma visiva |
|---|---|---|---|
Licenza a pagamento che concede Signer, certificato configurato | Avvia | Sigillata con il tuo certificato, pulita (watermarked: false) | Pulita |
Licenza a pagamento che concede Signer, senza certificato | Avvia | Refused: No signing certificate configured. | Pulita |
| Licenza a pagamento, certificato scaduto o non ancora valido | Avvia (con il widget abilitato, viene registrato un Avviso) | Refused: The signing certificate expired on yyyy-MM-dd. | Pulita |
| Licenza Demo/NFR temporanea, attiva o scaduta | Avvia | Sigillata con il certificato demo integrato, con filigrana (watermarked: true) | Con filigrana |
Nessuna licenza, un file legacy TRIAL, una licenza senza Signer, o una licenza a pagamento fuori dalla sua finestra di versione | AddDoconut() genera un'eccezione | — | — |
La regola è la stessa per la facciata C# e per il widget: l'output è contrassegnato da filigrana quando la licenza non è una licenza viewer a pagamento o è temporanea. Con una licenza temporanea il plugin firma sempre con il suo certificato demo integrato, e qualsiasi certificato tu configuri non viene utilizzato.
Il certificato demo produce un sigillo genuino, ma i lettori PDF non lo considerano affidabile. Un'integrazione può essere costruita e testata end-to-end su una licenza di valutazione; per ottenere un output pulito e affidabile è necessaria sia una licenza a pagamento sia il tuo certificato di firma.
Utilizzo da C#
DocumentSigner è registrato da AddDoconut() e risolto tramite iniezione delle dipendenze. Il suo costruttore è interno, quindi non new mai. Risolverlo senza AddPlugin<SignerPlugin>() genera 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 predefinito a Certified (firma visibile \u002B sigillo digitale); WordOutput predefinito a 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 prende lo stream di origine, la sua estensione (".pdf" o ".docx"), la richiesta e il certificato per questa chiamata. La facciata non legge SignerWidgetOptions.SigningCertificate; quella impostazione è per il widget. Passa null con una licenza demo, o in modalità Visuale.
SignResult contiene il documento firmato come stream ricercabile, più il suo Extension (".pdf" o ".docx") così puoi nominare il file. Possiedi lo stream: eliminalo quando hai finito.
Una firma Visual stampa solo l'immagine e non richiede alcun certificato:
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);Una sorgente Word viene firmata in PDF a meno che non richiedi un output Word. Assegna un nome al risultato da 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 genera un'eccezione invece di restituire quando la chiamata non può avere successo:
| Eccezione | Messaggio | Quando |
|---|---|---|
InvalidOperationException | No signing certificate configured. | Modalità certificata, una licenza a pagamento, e nessun certificato fornito |
InvalidOperationException | The signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd. | Modalità certificata con un certificato al di fuori della sua finestra di validità |
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. | Byte PNG vuoti, o un posizionamento non valido |
NotSupportedException | The signer supports PDF and Word (.docx) documents; got '{extension}'. | Qualsiasi altro tipo di sorgente |
Modalità di firma, output Word e certificati
Modalità di firma
SignRequest.Mode sceglie se la firma è sigillata.
| Modalità | Cosa produce | Certificato | Verificabile |
|---|---|---|---|
SignatureMode.Certified (predefinito) | La firma visibile più un sigillo digitale | Richiesto con una licenza a pagamento | Sì |
SignatureMode.Visual | Solo la firma visibile | Mai necessario | No: è un'immagine |
Usa Certified quando la firma deve essere dimostrabile: approvazioni, contratti, qualsiasi cosa un verificatore debba controllare per identità e integrità. Usa Visual quando ti serve solo l'aspetto di una firma, o non hai alcun certificato. Una licenza temporanea aggiunge filigrane a entrambe.
I sigilli PDF sono firme PKCS#7 separate (adbe.pkcs7.detached) con SHA-256, per chiavi RSA o ECDSA. Trasportano i certificati dell'emittente trovati nel tuo PFX, così un lettore che si fida della tua radice può costruire la catena. I sigilli nativi di Word sono firme di pacchetti OOXML e trasportano solo il certificato del firmatario.
Documenti Word
Per una fonte .docx, SignRequest.WordOutput sceglie l'output. Viene ignorato per le fonti PDF, che producono sempre un PDF.
| Output | Cosa succede | Supporto del verificatore |
|---|---|---|
WordOutput.Pdf (default) | Il documento viene convertito in PDF, poi firmato e sigillato | Ampio: un PDF firmato verifica ovunque |
WordOutput.Docx | Il documento rimane Word: l'immagine della firma viene inserita, più una firma del pacchetto OOXML | Limitato: non tutti i visualizzatori mostrano le firme del pacchetto OOXML |
Mantieni il PDF a meno che il destinatario non abbia bisogno di un file Word modificabile e accetti il supporto limitato del verificatore.
Configurazione del certificato
Per sigillare con la tua identità, fornisci al plugin un file PFX (PKCS#12) che includa la chiave privata. Per il widget, imposta SignerWidgetOptions.SigningCertificate; per la facciata C#, passa il certificato a SignAsync. Fornisci i byte o un percorso, più la password:
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"],
};
});
});Il certificato è mantenuto solo in memoria. Non viene mai registrato, restituito a un client o salvato, e la password non compare mai in una riga di log o in un messaggio di errore.
Requisiti:
- Un bundle PFX / PKCS#12 con la sua chiave privata. Un file solo con chiave pubblica (
.cer,.crt) non può firmare. Esporta la catena dell'emittente con esso, così i sigilli PDF possono includerla. - La password corretta.
- All'interno della sua finestra di validità. Un certificato scaduto o non ancora valido non interrompe l'app: viene registrato come Avviso all'avvio, e le firme Certified vengono rifiutate finché non viene sostituito. Le firme Visual non sono influenzate.
- Emesso per la firma di documenti: un uso della chiave con firma digitale o non ripudio, e un uso esteso della chiave, se presente, che consenta la firma di documenti, protezione e‑mail o autenticazione client. Un certificato emesso per altro, come un certificato server TLS, firma comunque, ma viene registrato come Avviso e i lettori PDF segnalano la firma.
- I token hardware, le smart card, gli HSM e l'archivio certificati di Windows non sono supportati. Esporta il certificato, con la sua chiave privata e catena, in un PFX.
Crea un PFX da un certificato e dalla sua chiave privata con OpenSSL:
openssl pkcs12 -export -out signing.pfx -inkey private.key -in certificate.crt
# La password di esportazione richiesta è SigningCertificate.Password.Esporta uno dall'archivio certificati di Windows: apri certmgr.msc e trova il certificato (la sua icona mostra una chiave quando la chiave privata è presente). Fai clic destro, scegli All Tasks → Export…, seleziona Yes, export the private key, scegli Personal Information Exchange – PKCS #12 (.PFX), e imposta una password.
Controlli all'avvio
Quando il widget è abilitato, il certificato in SignerWidgetOptions.SigningCertificate viene controllato una volta, all'interno di AddDoconut(), così un PFX configurato in modo errato fallisce all'avvio anziché alla prima firma. Tre problemi generano un InvalidOperationException:
| Messaggio | Correzione |
|---|---|
Doconut Signer: the certificate file was not found at '{path}'. | Correggi PfxPath; assicurati che il file sia distribuito e leggibile dall'account dell'app. |
Doconut Signer: the signing certificate could not be opened — the password is incorrect or the file is not a valid .pfx. | Verifica la password; assicurati che il file sia un vero .pfx, non un .cer o un .pem. |
Doconut Signer: the signing certificate has no private key. Re-export the .pfx INCLUDING the private key. | Esporta nuovamente il PFX con la chiave privata. |
Altrimenti l'host scrive una riga nel log quando si avvia. Informazioni quando il certificato è pronto:
Doconut Signer: using certificate '{subject}' (valid until yyyy-MM-dd). Signatures are digitally sealed.Un Avviso quando è scaduto, non ancora valido, o non emesso per la firma di documenti:
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 Informazione quando nessun certificato è configurato:
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.Quell'ultima riga è la stessa per tutte le licenze. Con una licenza a pagamento il certificato demo non viene mai usato: senza certificato, funzionano solo le firme Visual.
La facciata C# non viene controllata all'avvio. Il certificato che passi a SignAsync viene letto quando firmi, quindi un percorso o una password errati falliscono quella chiamata.
Widget integrabile
Abilita gli endpoint
Gli endpoint ?sign=open|run|download del widget sono disattivati per impostazione predefinita. Abilitale accanto alla registrazione del plugin:
builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
options.AddSignerWidget(widget =>
{
widget.MaxUploadMb = 25; // predefinito
widget.MaxSignatureImageKb = 512; // predefinito
// widget.SigningCertificate: vedi configurazione del certificato; lascia null per la firma demo (con filigrana)
});
});AddSignerWidget() senza argomento abilita il widget con le impostazioni predefinite. Non concede la firma da solo: richiede AddPlugin<SignerPlugin>(), altrimenti AddDoconut() genera un'eccezione:
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.Senza AddSignerWidget(), ogni richiesta ?sign= risponde con 404. Lo script stesso viene comunque servito, quindi il widget si carica e disegna la sua zona di rilascio, poi segnala Signing is not enabled on this server. alla prima richiesta.
Incorporalo
UseDoconutResources() fornisce lo script su {ResourcesPath}/js/doconutSigner.js (predefinito /doconut-res/js/doconutSigner.js). È un unico file autonomo senza dipendenze:
<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) accetta un selettore CSS o un elemento, genera un'eccezione se il mount non viene trovato e restituisce un handle.
Il firmatario carica un file PDF o .docx, crea una firma (Disegna su una canvas, Digita un nome con un font di firma, o Immagine da un PNG, JPG o GIF), la trascina e ridimensiona sulla pagina, quindi firma e scarica il risultato. Il widget invia sempre la firma come PNG; un’immagine caricata viene convertita nel browser in PNG che si adatta a 520×160.
Opzioni
| Opzione | Tipo | Predefinito | Note |
|---|---|---|---|
basePath | string | '/doconut' | Dove gli endpoint ?sign= e le immagini di anteprima vengono serviti |
resPath | string | '/doconut-res' | Riservato; il widget include il proprio CSS |
maxUploadMb | number | 25 | Solo controllo lato client, quindi un file troppo grande fallisce rapidamente. Il limite del server è MaxUploadMb in AddSignerWidget |
maxSignatureKb | number | 512 | Limite lato client per la modalità Immagine. Mantenerlo uguale al MaxSignatureImageKb del server |
previewWidth | number | 560 | Larghezza in pixel dell’anteprima della pagina |
licenseUrl | string | null | null | Trasforma l’avviso di demo-watermark in un collegamento a questo URL |
signatureMode | string | 'certified' | Tipo di firma iniziale: 'certified' o 'visual'. Qualsiasi altro valore diventa 'certified' |
showSignatureModeToggle | boolean | true | Mostra la scelta Firma digitale / Solo visuale. Con false, il widget firma con signatureMode |
wordOutput | string | 'pdf' | Output iniziale per le sorgenti .docx: 'pdf' o 'docx'. Qualsiasi altro valore diventa 'pdf' |
showOutputFormatToggle | boolean | true | Mostra la scelta PDF / Word, solo per sorgenti .docx. Con false, il widget utilizza wordOutput |
labels | object | {} | Sovrascrive qualsiasi sottoinsieme delle stringhe in inglese |
Nascondere un interruttore non disabilita la funzionalità; fissa il valore. Due configurazioni comuni:
// Entrambi gli interruttori mostrati, firma digitale per impostazione predefinita: un firmatario self-service completo
Doconut.signer('#host', { basePath: '/doconut', licenseUrl: '/pricing' });// Solo visuale, nessun interruttore: un semplice timbro senza firma digitale offerta
Doconut.signer('#host', {
basePath: '/doconut',
signatureMode: 'visual',
showSignatureModeToggle: false
});Callback
| Callback | Quando si attiva | Dati |
|---|---|---|
onReady | Una volta, al montaggio (non di nuovo su reset()) | — |
onSourceLoaded | Il file è aperto e la sua anteprima mostrata | { file: { token, name, pages, ext } } |
onSigned | La firma ha successo | { downloadToken, downloadName, watermarked } |
onDownload | Ad ogni clic su Download | { downloadName, downloadToken } |
onError | Un passaggio di apertura, firma o download fallisce, o un file in modalità Immagine è troppo grande | { message } |
Un callback che genera un'eccezione viene catturato e registrato; non interrompe mai il flusso del widget.
Gestione imperativa
| Metodo | Comportamento |
|---|---|
reset() | Ritorna alla schermata di rilascio e pulisce il flusso corrente. Non attiva nuovamente onReady. Nessuna operazione dopo destroy() |
loadFile(file) | Avvia il flusso con un File. Nessuna operazione a meno che il widget non sia nella sua schermata di rilascio; chiama reset() prima se necessario |
destroy() | Rimuove gli ascoltatori, svuota il mount e congela l'istanza |
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());Etichette
Ogni stringa ha un valore predefinito in inglese; labels sovrascrive qualsiasi sottoinsieme e il resto rimane in inglese. I frammenti che cambiano a runtime usano {placeholders}, come uploading: 'Uploading {name}…' e pages: '{n} pages'.
| Chiave | Valore predefinito in inglese |
|---|---|
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 |
Altri chiavi coprono la fase di posizionamento, la schermata di errore, il modulo collegato dell'avviso demo (demoNoticePrefix, demoNoticeLink, demoNoticeSuffix) e gli annunci aria-live.
Quando open o run rispondono a 404 senza errore JSON, il widget mostra signingNotEnabled. Un errore JSON dal server ha sempre la precedenza, quindi messaggi come un caricamento scaduto rimangono visibili.
Tematizzazione
Il widget aggiunge la classe dsw al suo elemento di mount e legge i suoi colori, raggio e font dalle proprietà personalizzate CSS, così puoi tematizzarlo senza toccare gli internali:
#host.dsw {
--dsw-accent: #b0522b; /* collegamenti, focus, modalità attiva */
--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; /* la modalità Tipo */
}Predefiniti: --dsw-accent: #2b6cb0, --dsw-bg: #ffffff, --dsw-fg: #1a202c, --dsw-muted: #718096, --dsw-border: #cbd5e0, --dsw-radius: 8px, un font di sistema UI e un font corsivo per la firma.
Costruisci il tuo frontend
Il widget è un client per questo contratto HTTP. Tutte e tre le rotte si trovano sotto il percorso dove UseDoconut() è montato (normalmente /doconut), e rispondono 404 finché non viene chiamato AddSignerWidget(). Gli errori includono un corpo JSON, { "error": "..." }, tranne dove la tabella indica "solo stato". Un valore ?sign= sconosciuto risponde 400.
| Rotta | Scopo | Risposta di successo |
|---|---|---|
POST ?sign=open (multipart, one file) | Carica un PDF o .docx e aprilo per l'anteprima | 200 — { token, name, pages, ext } |
POST ?sign=run (JSON body) | Firma il file caricato | 200 — { downloadToken, downloadName, watermarked } |
GET ?sign=download&token=<downloadToken> | Trasmetti in streaming il file firmato | 200 — il file, Content-Disposition: attachment, Cache-Control: no-store |
ext nella risposta open include il punto iniziale (".docx"). L'anteprima della pagina usa la rotta immagine del visualizzatore standard, {basePath}?token={token}&page={n}&thumb=1&width={px}; la pagina mostrata diventa placement.page.
Il 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 | Note |
|---|---|
token | Il token da open |
signature.kind | Drawn, Typed o Image, case-insensitive; qualsiasi altro valore diventa Drawn. Solo un suggerimento: il payload è sempre un PNG |
signature.payload | Un PNG base64 nudo, senza prefisso data:. Deve essere un PNG reale e non più grande di MaxSignatureImageKb una volta decodificato |
placement.page | Indicizzato da 1 |
placement.x / y / w / h | 0..1 normalizzato dall'angolo in alto a sinistra, con x + w ≤ 1 e y + h ≤ 1 |
meta.signerName / reason / location | Opzionale. Ognuno è trimmato, un valore vuoto è scartato, e ognuno è tagliato a 256 caratteri |
wordOutput | pdf (predefinito) o docx; ignorato per sorgenti PDF. Qualsiasi altro valore diventa pdf |
mode | certified (predefinito) o visual. Qualsiasi altro valore diventa certified |
downloadName segue l'output: <source>-signed.pdf o <source>-signed.docx, e download invia il Content-Type corrispondente.
La sorgente caricata e il risultato firmato sono conservati ciascuno per 30 minuti. Dopo ciò, run e download rispondono 404 e il file deve essere riaperto. Tutti i token sono GUID.
| Rotta | Stato | Quando | Corpo |
|---|---|---|---|
| any | 404 | Il widget non è abilitato | solo stato |
| any | 405 | Verbo errato (open e run richiedono POST, download richiede GET) | solo stato |
open | 400 | Non è un upload multipart | Expected a multipart file upload. |
open | 400 | Nessun file, o un file vuoto | No file uploaded. |
open | 400 | Qualsiasi cosa diversa da .pdf o .docx | Signing supports PDF and Word (.docx) files only. |
open | 413 | L'upload supera MaxUploadMb | File is too large. |
run | 400 | Il corpo non è un JSON valido, o è vuoto | Malformed request. / Empty request. |
run | 400 | Il token è mancante o non è un GUID | Invalid token. |
run | 404 | L'upload è scaduto o non è mai stato aperto | Upload expired — please re-open the file. |
run | 400 | Nessuna firma, o nessun posizionamento | No signature supplied. / No placement supplied. |
run | 400 | Il payload non è base64, è vuoto, troppo grande, o non è un 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 | Il posizionamento è fuori dalla pagina | The signature or its placement is invalid. |
run | 400 | Modalità certificata, licenza a pagamento e nessun certificato | No signing certificate configured. |
run | 400 | Modalità certificata con un certificato fuori dalla finestra di validità | The signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd. |
open, run | 500 | Elaborazione fallita | Un messaggio sanificato |
download | 400 | Il token è mancante o non è un GUID | solo stato |
download | 404 | Token sconosciuto o scaduto | solo stato |
Un ciclo completo con fetch:
// file: il File da firmare; pngBase64: la firma come PNG base64 puro, senza prefisso data:,
// ad esempio canvas.toDataURL(\u0027image/png\u0027).split(\u0027,\u0027)[1].
async function signFile(file, pngBase64) {
const base = '/doconut';
// 1. open: carica il file
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: firmalo
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: scarica il file firmato
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);
}Gli endpoint sono same-origin: questa versione non supporta CORS. Servi la tua UI e lo script del widget dalla stessa origine di Doconut, oppure fai il reverse-proxy di entrambi i percorsi /doconut (il percorso del middleware e il percorso delle risorse) sotto l'origine della tua UI.
In produzione
-
Installa il plugin accanto al pacchetto core, alla stessa versione:
dotnet add package Doconut.NET6.Signer. -
Aggiungi il file di licenza. Metti
Doconut.Viewer.Signer.licnella stessa cartella diDoconut.Viewer.lic. -
Ottieni il tuo certificato come PFX con la sua chiave privata e la catena dell'emittente, da un'autorità di certificazione o dalla PKI della tua organizzazione. Per provare prima, usa una licenza demo (il certificato demo integrato, con filigrana) o un PFX autofirmato.
-
Leggi il certificato dalla configurazione, così modificarlo non richiede mai una modifica al codice:
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"] ?? "", }); });Mantieni
.pfxal di fuori diwwwroot, e tieni la password fuori daappsettings.json: segreti utente in sviluppo (dotnet user-secrets set "DoconutSigner:Password" "<password>"), una variabile d'ambiente (DoconutSigner__Password) o un vault in produzione. -
Controlla il log di avvio. Dovrebbe leggere
using certificate '{subject}' (valid until …). Signatures are digitally sealed.Un avviso invece indica che il certificato è scaduto, non ancora valido, o non è stato emesso per la firma di documenti.
Fiducia nei lettori PDF. Un lettore mostra la firma come valida quando si fida della radice del certificato. Con la PKI della tua organizzazione, ciò vale per ogni macchina che si fida della tua radice, che di solito è ogni macchina all'interno dell'organizzazione. I certificati che Adobe si fida su qualsiasi macchina (l'Adobe Approved Trust List) sono, per quanto ne sappiamo, emessi con la chiave privata su un token hardware o HSM, che questo plugin non può utilizzare: firma solo da un PFX. Conferma con il tuo fornitore di certificati prima di fare affidamento su questo tipo di fiducia.
Web farm
Il widget conserva ogni caricamento e il relativo risultato in memoria sul nodo che ha servito open. Dietro un bilanciatore di carico senza sessioni sticky, una successiva richiesta run, download o di anteprima può raggiungere un altro nodo e non trovare il caricamento. Registra il negozio widget condiviso e crittografato una sola volta, dopo AddDoconut():
byte[] farmKey = Convert.FromBase64String(builder.Configuration["Doconut:FarmKey"]);
builder.Services.AddDoconutDistributedWidgets(store =>
{
store.RootPath = @"\\fileshare\doconut"; // una cartella che ogni nodo può leggere e scrivere
store.FarmKey = farmKey; // almeno 32 byte, identico su ogni nodo
// store.Ttl = TimeSpan.FromMinutes(30); // quanto tempo viene conservato un upload (il valore predefinito)
});- Un singolo server non ha bisogno di nulla: senza questa chiamata viene usato il negozio in memoria.
- I caricamenti e i risultati sono crittografati a riposo sulla condivisione (AES-256, encrypt-then-MAC), e ogni file è legato al suo token, così un token non può mai leggere il file di un altro.
FarmKeydeve essere di almeno 32 byte e lo stesso su ogni nodo. Caricalo da un secret store; non codificarlo mai direttamente. La registrazione genera unArgumentExceptionquandoRootPathè mancante oFarmKeyè più corto di 32 byte.- Imposta
RootPathsulla stessa posizione condivisa usata dal visualizzatore distribuito, e fornisci a ogni nodo lo stesso certificato di firma.
Riferimento API
La facciata e le opzioni del widget si trovano nello spazio dei nomi Doconut; i tipi di richiesta e risultato sono in Doconut.Core.Models.Signing. SignerPlugin è in Doconut.Plugins.Signer.
DocumentSigner
public sealed class DocumentSigner
{
public Task<SignResult> SignAsync(
Stream source, string sourceExtension, SignRequest request,
SigningCertificate? cert = null, CancellationToken ct = default);
}Risolto tramite iniezione delle dipendenze; il costruttore è interno. sourceExtension è ".pdf" o ".docx". Con una licenza a pagamento cert viene utilizzato e l'output è pulito; con una licenza temporanea viene usato il certificato demo integrato, cert viene ignorato e l'output è contrassegnato da filigrana.
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
}Una firma visibile posizionata una volta, più i metadati opzionali del firmatario.
VisibleSignature e SignatureKind
public sealed record VisibleSignature(SignatureKind Kind, byte[] PngBytes)
{
public bool IsValid { get; } // PngBytes non è vuoto
}
public enum SignatureKind { Drawn, Typed, Image }PngBytes è un PNG per ogni tipo. Una firma disegnata o digitata è trasparente; un'immagine caricata mantiene la trasparenza che aveva, quindi un JPG opaco rimane opaco. Kind è solo un suggerimento.
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 è basato su 1; X, Y, W e H sono 0..1 normalizzati dall'angolo in alto a sinistra.
SignatureMode e WordOutput
public enum SignatureMode { Certified, Visual } // Certified è il valore predefinito
public enum WordOutput { Pdf, Docx } // Pdf è il valore predefinito; ignorato per le sorgenti PDFSignResult
public sealed record SignResult(Stream Stream, string Extension);Il documento firmato come stream ricercabile, e la sua estensione con il punto (".pdf" o ".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 non è vuoto, o PfxPath non è vuoto
}Imposta PfxBytes o PfxPath, più Password.
SignerWidgetOptions
public sealed class SignerWidgetOptions
{
public int MaxUploadMb { get; set; } = 25;
public int MaxSignatureImageKb { get; set; } = 512;
public SigningCertificate? SigningCertificate { get; set; }
}Impostato tramite DoconutOptions.AddSignerWidget(Action<SignerWidgetOptions>? configure = null), che restituisce il DoconutOptions così le chiamate possono essere concatenate. Un SigningCertificate nullo indica il certificato demo con licenza temporanea, e firme Visual solo con una licenza a pagamento.
Risoluzione dei problemi
| Sintomo | Causa | Correzione |
|---|---|---|
AddDoconut() lancia The Signer plugin is registered via AddPlugin but no active license grants Signer. | Nessuna licenza, un file TRIAL, una licenza senza Signer, o una licenza a pagamento al di fuori della sua finestra di versione | Installa una licenza che concede Signer, o rimuovi AddPlugin<SignerPlugin>() |
AddDoconut() lancia AddSignerWidget() was called but the Signer plugin is not registered. | Il widget è abilitato senza il suo plugin | Aggiungi options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>() |
AddDoconut() lancia Doconut Signer: the certificate file was not found at '{path}'. | PfxPath punta a un file mancante | Correggi il percorso; distribuisci il file dove l'account dell'app può leggerlo |
AddDoconut() lancia Doconut Signer: the signing certificate could not be opened — the password is incorrect or the file is not a valid .pfx. | Password errata, o non è un file PKCS#12 | Verifica la password; usa un vero .pfx |
AddDoconut() lancia Doconut Signer: the signing certificate has no private key. Re-export the .pfx INCLUDING the private key. | Il PFX è stato esportato senza la chiave privata | Esportalo di nuovo con la chiave privata |
Risoluzione di DocumentSigner lancia No IDocumentSigner is registered. | SignerPlugin non è registrato | Aggiungi AddPlugin<SignerPlugin>() dentro AddDoconut() |
| L'output è contrassegnato da filigrana | La licenza è temporanea (Demo/NFR) | Usa una licenza a pagamento che concede Signer |
run risponde 400 No signing certificate configured. | Una licenza a pagamento, modalità Certified, e nessun certificato | Configura SigningCertificate, o firma in modalità Visual |
run risponde 400 The signing certificate expired on yyyy-MM-dd. | Il certificato è scaduto | Sostituiscilo; le firme Visual continuano a funzionare nel frattempo |
| Il log dice che l'output "usa il certificato demo integrato", ma una licenza a pagamento rifiuta le firme Certified | Quella riga viene scritta ogni volta che nessun certificato è configurato, indipendentemente dalla licenza | Configura SigningCertificate |
Il widget si carica ma dice Signing is not enabled on this server. | AddSignerWidget() non è stato chiamato, o basePath non corrisponde a dove UseDoconut() è montato | Chiama AddSignerWidget(); correggi basePath |
run risponde 400 The signature image must be a PNG., Signature image is not valid base64. o Signature image is too large. | Una UI personalizzata ha inviato un URL data:, un JPG, o più di MaxSignatureImageKb | Invia un PNG base64 nudo entro il limite |
open risponde 413 File is too large. | Il caricamento supera MaxUploadMb | Genera MaxUploadMb in AddSignerWidget; il maxUploadMb del widget è solo un controllo client-side |
run o download risponde 404 Upload expired — please re-open the file. | La finestra di 30 minuti è scaduta, o un nodo della web-farm non ha il caricamento | Apri di nuovo il file; in una farm, registra AddDoconutDistributedWidgets |
Un .docx firmato non mostra la firma in alcuni visualizzatori | L'output Word contiene una firma del pacchetto OOXML, che molti visualizzatori non mostrano | Firma in PDF, il valore predefinito |
| I lettori PDF dicono che l'identità del firmatario è sconosciuta | Il lettore non si fida della radice del certificato (il certificato demo non è mai affidabile) | Usa un certificato da una radice di cui i tuoi lettori si fidano |
| Il widget fallisce quando l'UI è su un'origine diversa | Gli endpoint non hanno supporto CORS | Fornisci l'UI dalla stessa origine, o usa un reverse-proxy per i percorsi Doconut |
| Il tema non viene applicato | Il selettore punta a un elemento dentro il mount | Punta al mount stesso: #host.dsw o #host |
Questa pagina è stata utile?