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.

SuperficieQuando 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:

bash
dotnet add package Doconut.NET6.Signer

Per fissare il plugin alla versione descritta in questa documentazione, passa la versione separatamente:

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

Mantieni 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:

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

Su 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():

csharp
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:

text
The Signer plugin is registered via AddPlugin but no active license grants Signer. Remove the AddPlugin<...>() call or install a license (or trial/demo) that includes Signer.

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 licenzaAvvioFirma certificataFirma visiva
Licenza a pagamento che concede Signer, certificato configuratoAvviaSigillata con il tuo certificato, pulita (watermarked: false)Pulita
Licenza a pagamento che concede Signer, senza certificatoAvviaRefused: No signing certificate configured.Pulita
Licenza a pagamento, certificato scaduto o non ancora validoAvvia (con il widget abilitato, viene registrato un Avviso)Refused: The signing certificate expired on yyyy-MM-dd.Pulita
Licenza Demo/NFR temporanea, attiva o scadutaAvviaSigillata 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 versioneAddDoconut() 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>().

csharp
using Doconut;
using Doconut.Core.Models.Signing;

public sealed class ContractSigning
{
    private readonly DocumentSigner _signer;

    public ContractSigning(DocumentSigner signer) => _signer = signer;

    public async Task<byte[]> SignAsync(Stream pdf, byte[] signaturePng, SigningCertificate certificate, CancellationToken ct)
    {
        var request = new SignRequest(
            new VisibleSignature(SignatureKind.Drawn, signaturePng),
            new SignaturePlacement(Page: 1, X: 0.58, Y: 0.80, W: 0.32, H: 0.12),
            SignerName: "Ada Lovelace",
            Reason: "I approve this document",
            Location: "London, UK");
        // Mode 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:

csharp
var signer = app.Services.GetRequiredService<DocumentSigner>();
byte[] signaturePng = File.ReadAllBytes("signature.png");

var request = new SignRequest(
    new VisibleSignature(SignatureKind.Image, signaturePng),
    new SignaturePlacement(Page: 1, X: 0.58, Y: 0.80, W: 0.32, H: 0.12),
    Mode: SignatureMode.Visual);

SignResult result = await signer.SignAsync(stream, ".pdf", request, ct: ct);

Una sorgente Word viene firmata in PDF a meno che non richiedi un output Word. Assegna un nome al risultato da result.Extension:

csharp
var signer = app.Services.GetRequiredService<DocumentSigner>();
byte[] signaturePng = File.ReadAllBytes("signature.png");

var request = new SignRequest(
    new VisibleSignature(SignatureKind.Drawn, signaturePng),
    new SignaturePlacement(Page: 1, X: 0.58, Y: 0.80, W: 0.32, H: 0.12),
    WordOutput: WordOutput.Docx);

SignResult result = await signer.SignAsync(stream, ".docx", request, ct: ct);
string downloadName = "contract-signed" + result.Extension;   // ".docx"

SignAsync genera un'eccezione invece di restituire quando la chiamata non può avere successo:

EccezioneMessaggioQuando
InvalidOperationExceptionNo signing certificate configured.Modalità certificata, una licenza a pagamento, e nessun certificato fornito
InvalidOperationExceptionThe 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à
ArgumentExceptionThe 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
NotSupportedExceptionThe 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 produceCertificatoVerificabile
SignatureMode.Certified (predefinito)La firma visibile più un sigillo digitaleRichiesto con una licenza a pagamentoSì
SignatureMode.VisualSolo la firma visibileMai necessarioNo: è 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.

OutputCosa succedeSupporto del verificatore
WordOutput.Pdf (default)Il documento viene convertito in PDF, poi firmato e sigillatoAmpio: un PDF firmato verifica ovunque
WordOutput.DocxIl documento rimane Word: l'immagine della firma viene inserita, più una firma del pacchetto OOXMLLimitato: 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:

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
    options.AddSignerWidget(widget =>
    {
        widget.SigningCertificate = new SigningCertificate
        {
            PfxBytes = File.ReadAllBytes("/secure/signing.pfx"),
            Password = builder.Configuration["Signing:PfxPassword"],
        };
    });
});
csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
    options.AddSignerWidget(widget =>
    {
        widget.SigningCertificate = new SigningCertificate
        {
            PfxPath = "/secure/signing.pfx",
            Password = builder.Configuration["Signing:PfxPassword"],
        };
    });
});

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:

bash
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:

MessaggioCorrezione
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:

text
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:

text
Doconut Signer: the signing certificate '{subject}' expired on yyyy-MM-dd. Certified signatures will be refused until it is replaced.
Doconut Signer: the signing certificate '{subject}' is not valid before yyyy-MM-dd. Certified signatures will be refused until then.
Doconut Signer: the signing certificate '{subject}' is not issued for document signing (its key usage excludes it). PDF readers will flag these signatures.

E Informazione quando nessun certificato è configurato:

text
Doconut Signer: no signing certificate configured — output uses the built-in demo certificate and is watermarked. Set SignerWidgetOptions.SigningCertificate to sign with your own certificate.

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:

csharp
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:

text
AddSignerWidget() was called but the Signer plugin is not registered. Add options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>() (the widget needs it), or remove the AddSignerWidget() call.

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:

html
<div id="host"></div>
<script src="/doconut-res/js/doconutSigner.js"></script>
<script>
  const handle = Doconut.signer('#host', { basePath: '/doconut' });
</script>

Doconut.signer(selectorOrElement, options) 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

OpzioneTipoPredefinitoNote
basePathstring'/doconut'Dove gli endpoint ?sign= e le immagini di anteprima vengono serviti
resPathstring'/doconut-res'Riservato; il widget include il proprio CSS
maxUploadMbnumber25Solo controllo lato client, quindi un file troppo grande fallisce rapidamente. Il limite del server è MaxUploadMb in AddSignerWidget
maxSignatureKbnumber512Limite lato client per la modalità Immagine. Mantenerlo uguale al MaxSignatureImageKb del server
previewWidthnumber560Larghezza in pixel dell’anteprima della pagina
licenseUrlstring | nullnullTrasforma l’avviso di demo-watermark in un collegamento a questo URL
signatureModestring'certified'Tipo di firma iniziale: 'certified' o 'visual'. Qualsiasi altro valore diventa 'certified'
showSignatureModeTogglebooleantrueMostra la scelta Firma digitale / Solo visuale. Con false, il widget firma con signatureMode
wordOutputstring'pdf'Output iniziale per le sorgenti .docx: 'pdf' o 'docx'. Qualsiasi altro valore diventa 'pdf'
showOutputFormatTogglebooleantrueMostra la scelta PDF / Word, solo per sorgenti .docx. Con false, il widget utilizza wordOutput
labelsobject{}Sovrascrive qualsiasi sottoinsieme delle stringhe in inglese

Nascondere un interruttore non disabilita la funzionalità; fissa il valore. Due configurazioni comuni:

javascript
// Entrambi gli interruttori mostrati, firma digitale per impostazione predefinita: un firmatario self-service completo
Doconut.signer('#host', { basePath: '/doconut', licenseUrl: '/pricing' });
javascript
// Solo visuale, nessun interruttore: un semplice timbro senza firma digitale offerta
Doconut.signer('#host', {
  basePath: '/doconut',
  signatureMode: 'visual',
  showSignatureModeToggle: false
});

Callback

CallbackQuando si attivaDati
onReadyUna volta, al montaggio (non di nuovo su reset())—
onSourceLoadedIl file è aperto e la sua anteprima mostrata{ file: { token, name, pages, ext } }
onSignedLa firma ha successo{ downloadToken, downloadName, watermarked }
onDownloadAd ogni clic su Download{ downloadName, downloadToken }
onErrorUn 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

MetodoComportamento
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
javascript
const signerWidget = Doconut.signer('#host', {
  basePath: '/doconut',
  onSigned: (result) => console.log('signed', result.downloadName, result.watermarked),
  onError: (error) => console.warn(error.message)
});
document.getElementById('start-over').addEventListener('click', () => signerWidget.reset());

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'.

ChiaveValore predefinito in inglese
dropPromptDrag & drop a PDF or Word file here
dropHintPDF or Word (.docx)
chooseFileChoose file
signatureHeadingYour signature
modeDraw / modeType / modeImageDraw / Type / Image
metaSummarySignature details (optional)
metaSignerName / metaReason / metaLocationSigner name / Reason / Location
signatureTypeSignature type
modeCertified / modeVisualDigital signature / Visual only
modeVisualNoteNo certificate — a visible mark only, not cryptographically verifiable.
outputFormatOutput format
outputPdf / outputWordPDF / Word (.docx)
signActionSign document
downloadDownload
demoNoticeDemo — signed with the Doconut demo certificate; output is watermarked.
signingNotEnabledSigning is not enabled on this server.
page / pages1 page / {n} pages

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:

css
#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.

RottaScopoRisposta di successo
POST ?sign=open (multipart, one file)Carica un PDF o .docx e aprilo per l'anteprima200 — { token, name, pages, ext }
POST ?sign=run (JSON body)Firma il file caricato200 — { downloadToken, downloadName, watermarked }
GET ?sign=download&token=<downloadToken>Trasmetti in streaming il file firmato200 — 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:

json
{
  "token": "GUID-from-open",
  "signature": { "kind": "Drawn", "payload": "<base64 PNG, no data: prefix>" },
  "placement": { "page": 1, "x": 0.58, "y": 0.80, "w": 0.32, "h": 0.12 },
  "meta": { "signerName": "Ada Lovelace", "reason": "I approve", "location": "London, UK" },
  "wordOutput": "pdf",
  "mode": "certified"
}
CampoNote
tokenIl token da open
signature.kindDrawn, Typed o Image, case-insensitive; qualsiasi altro valore diventa Drawn. Solo un suggerimento: il payload è sempre un PNG
signature.payloadUn PNG base64 nudo, senza prefisso data:. Deve essere un PNG reale e non più grande di MaxSignatureImageKb una volta decodificato
placement.pageIndicizzato da 1
placement.x / y / w / h0..1 normalizzato dall'angolo in alto a sinistra, con x + w ≤ 1 e y + h ≤ 1
meta.signerName / reason / locationOpzionale. Ognuno è trimmato, un valore vuoto è scartato, e ognuno è tagliato a 256 caratteri
wordOutputpdf (predefinito) o docx; ignorato per sorgenti PDF. Qualsiasi altro valore diventa pdf
modecertified (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.

RottaStatoQuandoCorpo
any404Il widget non è abilitatosolo stato
any405Verbo errato (open e run richiedono POST, download richiede GET)solo stato
open400Non è un upload multipartExpected a multipart file upload.
open400Nessun file, o un file vuotoNo file uploaded.
open400Qualsiasi cosa diversa da .pdf o .docxSigning supports PDF and Word (.docx) files only.
open413L'upload supera MaxUploadMbFile is too large.
run400Il corpo non è un JSON valido, o è vuotoMalformed request. / Empty request.
run400Il token è mancante o non è un GUIDInvalid token.
run404L'upload è scaduto o non è mai stato apertoUpload expired — please re-open the file.
run400Nessuna firma, o nessun posizionamentoNo signature supplied. / No placement supplied.
run400Il payload non è base64, è vuoto, troppo grande, o non è un PNGSignature image is not valid base64. / Signature image is empty. / Signature image is too large. / The signature image must be a PNG.
run400Il posizionamento è fuori dalla paginaThe signature or its placement is invalid.
run400Modalità certificata, licenza a pagamento e nessun certificatoNo signing certificate configured.
run400Modalità 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, run500Elaborazione fallitaUn messaggio sanificato
download400Il token è mancante o non è un GUIDsolo stato
download404Token sconosciuto o scadutosolo stato

Un ciclo completo con fetch:

javascript
// 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

  1. Installa il plugin accanto al pacchetto core, alla stessa versione: dotnet add package Doconut.NET6.Signer.

  2. Aggiungi il file di licenza. Metti Doconut.Viewer.Signer.lic nella stessa cartella di Doconut.Viewer.lic.

  3. 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.

  4. Leggi il certificato dalla configurazione, così modificarlo non richiede mai una modifica al codice:

    json
    "DoconutSigner": { "PfxPath": "certs/your-certificate.pfx" }
    csharp
    var signerSettings = builder.Configuration.GetSection("DoconutSigner");
    
    builder.Services.AddDoconut(options =>
    {
        options.LicensePath = "Doconut.Viewer.lic";
        options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
        options.AddSignerWidget(widget => widget.SigningCertificate = new SigningCertificate
        {
            PfxPath = Path.Combine(builder.Environment.ContentRootPath, signerSettings["PfxPath"]),
            Password = signerSettings["Password"] ?? "",
        });
    });

    Mantieni .pfx al di fuori di wwwroot, e tieni la password fuori da appsettings.json: segreti utente in sviluppo (dotnet user-secrets set "DoconutSigner:Password" "<password>"), una variabile d'ambiente (DoconutSigner__Password) o un vault in produzione.

  5. 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():

csharp
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.
  • FarmKey deve essere di almeno 32 byte e lo stesso su ogni nodo. Caricalo da un secret store; non codificarlo mai direttamente. La registrazione genera un ArgumentException quando RootPath è mancante o FarmKey è più corto di 32 byte.
  • Imposta RootPath sulla 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

csharp
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

csharp
public sealed record SignRequest(
    VisibleSignature   Signature,
    SignaturePlacement Placement,
    string?            SignerName = null,
    string?            Reason     = null,
    string?            Location   = null,
    WordOutput         WordOutput = WordOutput.Pdf,
    SignatureMode      Mode       = SignatureMode.Certified)
{
    public bool IsValid { get; }   // Signature.IsValid && Placement.IsValid
}

Una firma visibile posizionata una volta, più i metadati opzionali del firmatario.

VisibleSignature e SignatureKind

csharp
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

csharp
public readonly record struct SignaturePlacement(int Page, double X, double Y, double W, double H)
{
    public bool IsValid { get; }   // Page >= 1; X, Y >= 0; W, H > 0; X + W <= 1; Y + H <= 1
}

Page è basato su 1; X, Y, W e H sono 0..1 normalizzati dall'angolo in alto a sinistra.

SignatureMode e WordOutput

csharp
public enum SignatureMode { Certified, Visual }   // Certified è il valore predefinito
public enum WordOutput { Pdf, Docx }              // Pdf è il valore predefinito; ignorato per le sorgenti PDF

SignResult

csharp
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

csharp
public sealed class SigningCertificate
{
    public byte[]? PfxBytes { get; init; }
    public string? PfxPath  { get; init; }
    public string  Password { get; init; } = "";
    public bool    HasMaterial { get; }   // PfxBytes non è vuoto, o PfxPath non è vuoto
}

Imposta PfxBytes o PfxPath, più Password.

SignerWidgetOptions

csharp
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

SintomoCausaCorrezione
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 versioneInstalla 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 pluginAggiungi options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>()
AddDoconut() lancia Doconut Signer: the certificate file was not found at '{path}'.PfxPath punta a un file mancanteCorreggi 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#12Verifica 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 privataEsportalo di nuovo con la chiave privata
Risoluzione di DocumentSigner lancia No IDocumentSigner is registered.SignerPlugin non è registratoAggiungi AddPlugin<SignerPlugin>() dentro AddDoconut()
L'output è contrassegnato da filigranaLa 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 certificatoConfigura SigningCertificate, o firma in modalità Visual
run risponde 400 The signing certificate expired on yyyy-MM-dd.Il certificato è scadutoSostituiscilo; 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 CertifiedQuella riga viene scritta ogni volta che nessun certificato è configurato, indipendentemente dalla licenzaConfigura 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() è montatoChiama 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 MaxSignatureImageKbInvia un PNG base64 nudo entro il limite
open risponde 413 File is too large.Il caricamento supera MaxUploadMbGenera 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 caricamentoApri di nuovo il file; in una farm, registra AddDoconutDistributedWidgets
Un .docx firmato non mostra la firma in alcuni visualizzatoriL'output Word contiene una firma del pacchetto OOXML, che molti visualizzatori non mostranoFirma in PDF, il valore predefinito
I lettori PDF dicono che l'identità del firmatario è sconosciutaIl 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 diversaGli endpoint non hanno supporto CORSFornisci l'UI dalla stessa origine, o usa un reverse-proxy per i percorsi Doconut
Il tema non viene applicatoIl selettore punta a un elemento dentro il mountPunta al mount stesso: #host.dsw o #host

Questa pagina è stata utile?