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) | Vuoi una schermata pronta per caricare, firmare e scaricare 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.NET8.SignerPer fissare il plugin alla versione descritta in questa documentazione, passa la versione separatamente:
dotnet add package Doconut.NET8.Signer --version 26.10.0Mantieni il pacchetto Signer alla stessa versione di Doconut.NET8. L'ID del pacchetto è Doconut.NET8.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.NET8 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 integrato).
Il plugin richiede 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 fuori dalla 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 | Rifiutata: No signing certificate configured. | Pulita |
| Licenza a pagamento, certificato scaduto o non ancora valido | Avvia (con il widget abilitato, viene registrato un Avviso) | Rifiutata: 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 configurato 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 con una licenza di valutazione; per ottenere un output pulito e affidabile è necessaria sia una licenza a pagamento sia il proprio 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 su Certified (firma visibile + sigillo digitale); WordOutput predefinito su 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 Visuale appone 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, 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 (default) | La firma visibile più un sigillo digitale | Richiesto con 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 un 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, quindi 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. È 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, quindi firmato e sigillato | Ampio: un PDF firmato viene verificato 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 del verificatore limitato.
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 persisto, e la password non appare 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 contenerla. - La password corretta.
- All'interno della sua finestra di validità. Un certificato scaduto o non ancora valido non interrompe l'app: viene registrato come Warning all'avvio, e le firme Certified sono rifiutate finché non viene sostituito. Le firme Visual non sono influenzate.
- Emesso per la firma di documenti: un utilizzo della chiave con digital signature o non-repudiation, e un utilizzo esteso della chiave, se presente, che consenta la firma di documenti, la protezione e‑mail o l'autenticazione client. Un certificato emesso per altro, come un certificato server TLS, firma comunque, ma viene registrato come Warning e i lettori PDF segnalano la firma.
- Token hardware, smart card, HSM e il Windows certificate store 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 che ti viene richiesta è SigningCertificate.Password.Esporta uno dal Windows certificate store: apri certmgr.msc e trova il certificato (la sua icona mostra una chiave quando la chiave privata è presente). Fai clic destro, scegli Tutte le attività → 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. | Controlla 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 Warning 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 Informazioni 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.Questa ultima riga è la stessa per ogni licenza. 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 fanno fallire quella chiamata.
Widget integrabile
Abilita gli endpoint
Gli endpoint ?sign=open|run|download del widget sono off by default. Abilitali 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 la configurazione del certificato; lasciare null per la firma demo (con filigrana)
});
});AddSignerWidget() senza argomento abilita il widget con le impostazioni predefinite. Non concede la firma da solo: necessita AddPlugin<SignerPlugin>(), oppure 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 dipinge la sua zona di rilascio, poi segnala Signing is not enabled on this server. alla sua 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 (Draw su una canvas, Type un nome con un font di firma, o Image 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 sono serviti |
resPath | string | '/doconut-res' | Riservato; il widget include il proprio CSS |
maxUploadMb | number | 25 | Controllo solo 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 Digital signature / Visual only. 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 predefinita: un firmatario self-service completo
Doconut.signer('#host', { basePath: '/doconut', licenseUrl: '/pricing' });// Solo visuale, nessun interruttore: un semplice timbro senza firma digitale offerto
Doconut.signer('#host', {
basePath: '/doconut',
signatureMode: 'visual',
showSignatureModeToggle: false
});Callback
| Callback | Quando scatta | 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 click 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.
Gestore imperativo
| Metodo | Comportamento |
|---|---|
reset() | Ritorna alla schermata di rilascio e cancella 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 | Predefinito 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 |
Altre 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 prevale sempre, 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à Type */
}Predefiniti: --dsw-accent: #2b6cb0, --dsw-bg: #ffffff, --dsw-fg: #1a202c, --dsw-muted: #718096, --dsw-border: #cbd5e0, --dsw-radius: 8px, un font UI di sistema 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": "..." }, eccetto 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 — the file, Content-Disposition: attachment, Cache-Control: no-store |
ext nella risposta open include il punto iniziale (".docx"). L'anteprima della pagina utilizza 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 puro, 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 ciascuno è limitato 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 | status only |
| any | 405 | Verbo errato (open e run richiedono POST, download richiede GET) | status only |
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 è 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 | A sanitized message |
download | 400 | Il token è mancante o non è un GUID | status only |
download | 404 | Token sconosciuto o scaduto | status only |
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. Fornisci la tua UI e lo script del widget dallo stesso origin di Doconut, oppure fai il reverse-proxy di entrambi i percorsi /doconut (il percorso del middleware e il percorso delle risorse) sotto l'origin della tua UI.
In produzione
-
Installa il plugin accanto al pacchetto core, alla stessa versione:
dotnet add package Doconut.NET8.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 un cambiamento di 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 il
.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 significa che il certificato è scaduto, non ancora valido, o non emesso per la firma dei 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.
Fattorie web
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 una sola volta il negozio widget condiviso e crittografato, 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); // per quanto tempo un upload viene conservato (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 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 usato e l'output è pulito; con una licenza temporanea viene usato il certificato demo integrato, cert è 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ù 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, oppure 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 significa il certificato demo sotto una licenza temporanea, e firme Visual solo con una licenza a pagamento.
Risoluzione dei problemi
| Sintomo | Causa | Correzione |
|---|---|---|
AddDoconut() throws 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() throws 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() throws 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() throws 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() throws 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 |
Resolving DocumentSigner throws 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 answers 400 No signing certificate configured. | Una licenza a pagamento, modalità Certified, e nessun certificato | Configura SigningCertificate, o firma in modalità Visual |
run answers 400 The signing certificate expired on yyyy-MM-dd. | Il certificato è scaduto | Sostituiscilo; le firme Visual continuano a funzionare nel frattempo |
| Il log indica che l'output "usa il certificato demo integrato", ma una licenza a pagamento rifiuta le firme Certified | Quella riga è scritta ogni volta che non è configurato alcun certificato, indipendentemente dalla licenza | Configura SigningCertificate |
Il widget si carica ma mostra Signing is not enabled on this server. | AddSignerWidget() non è stato chiamato, o basePath non corrisponde a dove UseDoconut() è montato | Chiama AddSignerWidget(); correggi basePath |
run answers 400 The signature image must be a PNG., Signature image is not valid base64. or 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 answers 413 File is too large. | Il caricamento supera MaxUploadMb | Aumenta MaxUploadMb in AddSignerWidget; il maxUploadMb del widget è solo un controllo client-side |
run or download answers 404 Upload expired — please re-open the file. | La finestra di 30 minuti è scaduta, o un nodo del web-farm non ha il caricamento | Riapri il file; in un 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, l'impostazione predefinita |
| I lettori PDF indicano che l'identità del firmatario è sconosciuta | Il lettore non si fida della radice del certificato (il certificato demo non è mai fidato) | Usa un certificato da una radice di cui i tuoi lettori si fidano |
| Il widget fallisce quando l'interfaccia è su un'origine diversa | Gli endpoint non hanno supporto CORS | Fornisci la 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 | Mira al mount stesso: #host.dsw o #host |
Questa pagina è stata utile?