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

bash
dotnet add package Doconut.NET8.Signer

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

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

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

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

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 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 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 certificatoAvviaRifiutata: No signing certificate configured.Pulita
Licenza a pagamento, certificato scaduto o non ancora validoAvvia (con il widget abilitato, viene registrato un Avviso)Rifiutata: 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 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>().

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

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, 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 (default)La firma visibile più un sigillo digitaleRichiesto con 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 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.

OutputCosa succedeSupporto del verificatore
WordOutput.Pdf (default)Il documento viene convertito in PDF, quindi firmato e sigillatoAmpio: un PDF firmato viene verificato 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 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:

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

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

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

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

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

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:

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

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

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

OpzioneTipoPredefinitoNote
basePathstring'/doconut'Dove gli endpoint ?sign= e le immagini di anteprima sono serviti
resPathstring'/doconut-res'Riservato; il widget include il proprio CSS
maxUploadMbnumber25Controllo solo 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 Digital signature / Visual only. 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 predefinita: un firmatario self-service completo
Doconut.signer('#host', { basePath: '/doconut', licenseUrl: '/pricing' });
javascript
// Solo visuale, nessun interruttore: un semplice timbro senza firma digitale offerto
Doconut.signer('#host', {
  basePath: '/doconut',
  signatureMode: 'visual',
  showSignatureModeToggle: false
});

Callback

CallbackQuando scattaDati
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 click 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.

Gestore imperativo

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

ChiavePredefinito 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

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:

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

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

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 puro, 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 ciascuno è limitato 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 è abilitatostatus only
any405Verbo errato (open e run richiedono POST, download richiede GET)status only
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 è 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 fallitaA sanitized message
download400Il token è mancante o non è un GUIDstatus only
download404Token sconosciuto o scadutostatus only

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

  1. Installa il plugin accanto al pacchetto core, alla stessa versione: dotnet add package Doconut.NET8.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 un cambiamento di 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 il .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 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():

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);   // 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.
  • FarmKey deve essere 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 usato e l'output è pulito; con una licenza temporanea viene usato il certificato demo integrato, cert è 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ù 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, oppure 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 significa il certificato demo sotto una licenza temporanea, e firme Visual solo con una licenza a pagamento.

Risoluzione dei problemi

SintomoCausaCorrezione
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 versioneInstalla 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 pluginAggiungi options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>()
AddDoconut() throws 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() 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#12Verifica 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 privataEsportalo di nuovo con la chiave privata
Resolving DocumentSigner throws 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 answers 400 No signing certificate configured.Una licenza a pagamento, modalità Certified, e nessun certificatoConfigura SigningCertificate, o firma in modalità Visual
run answers 400 The signing certificate expired on yyyy-MM-dd.Il certificato è scadutoSostituiscilo; 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 CertifiedQuella riga è scritta ogni volta che non è configurato alcun certificato, indipendentemente dalla licenzaConfigura 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() è montatoChiama 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 MaxSignatureImageKbInvia un PNG base64 nudo entro il limite
open answers 413 File is too large.Il caricamento supera MaxUploadMbAumenta 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 caricamentoRiapri il file; in un 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, l'impostazione predefinita
I lettori PDF indicano che l'identità del firmatario è sconosciutaIl 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 diversaGli endpoint non hanno supporto CORSFornisci la 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 mountMira al mount stesso: #host.dsw o #host

Questa pagina è stata utile?