Plugin di firma

Firma documenti PDF e Word con una firma visibile e un sigillo digitale

Il plugin Signer inserisce 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 on DocImage.axd (?sign=open|run|download)Costruisci la tua interfaccia di firma contro un contratto server documentato

Ogni firma viene inserita una sola volta, su una pagina. Il nome del firmatario, il motivo e la posizione possono accompagnarla.

Installa il pacchetto

powershell
Install-Package Doconut.NETFramework.Signer

Per fissare il plugin alla versione descritta in questa documentazione:

powershell
Install-Package Doconut.NETFramework.Signer -Version 26.10.0

Mantieni il pacchetto Signer alla stessa versione di Doconut.NETFramework.

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.

Registra il plugin

Come ogni plugin Doconut, Signer si registra con AddPlugin<TPlugin>() in DoconutHost.Initialize, chiamato da Application_Start:

csharp
Doconut.DoconutHost.Initialize(options =>
{
    options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
    options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
});

Aggiungi Doconut.DoconutHost.Shutdown() a Application_End affinché il lavoro in background si fermi correttamente quando il pool di applicazioni viene riciclato.

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, DoconutHost.Initialize genera un'eccezione da Application_Start:

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.

In System.Web ciò significa che ogni richiesta restituisce un 500 vuoto, e il motivo è registrato solo nel registro eventi di Windows (origine ASP.NET). Genera un'eccezione per mancanza 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 temporanee Demo/NFR sono accettate. Vedi Configurazione licenza.

Licenze e filigrana

Stato licenzaAvvioFirma certificataFirma visiva
Licenza a pagamento che concede Signer, certificato configuratoAvviaSigillato con il tuo certificato, pulito (watermarked: false)Pulita
Licenza a pagamento che concede Signer, senza certificatoAvviaRefused: No signing certificate configured.Pulita
Licenza a pagamento, certificato scaduto o non ancora validoAvviaRefused: The signing certificate expired on yyyy-MM-dd.Pulita
Licenza temporanea Demo/NFR, attiva o scadutaAvviaSigillato 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 versioneApplication_Start genera un'eccezione; ogni richiesta restituisce un 500 vuoto——

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

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 hai bisogno sia di una licenza a pagamento sia del tuo proprio certificato di firma.

Utilizzo da C#

DocumentSigner è registrato da DoconutHost.Initialize; risolvilo da DoconutHost.Services. 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 ha come valore predefinito Certified (firma visibile + sigillo digitale); WordOutput ha come valore predefinito Pdf.

        SignResult result = await _signer.SignAsync(pdf, ".pdf", request, certificate, ct);
        using (result.Stream)
        using (var output = new MemoryStream())
        {
            await result.Stream.CopyToAsync(output, 81920, 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à Visual.

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.

In un controller MVC 5

Rendi l'azione asincrona e await la firma. Questa appone una firma Visual, che non richiede certificato:

csharp
[HttpPost]
public async Task<ActionResult> Sign(HttpPostedFileBase file)
{
    var signer = Doconut.DoconutHost.Services.GetRequiredService<DocumentSigner>();
    byte[] signaturePng = System.IO.File.ReadAllBytes(Server.MapPath("~/App_Data/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(
        file.InputStream, Path.GetExtension(file.FileName), request, ct: Response.ClientDisconnectedToken);
    string contentType = result.Extension == ".pdf"
        ? "application/pdf"
        : "application/vnd.openxmlformats-officedocument.wordprocessingml.document";
    return File(result.Stream, contentType, Path.GetFileNameWithoutExtension(file.FileName) + "-signed" + result.Extension);
}

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

csharp
var signer = Doconut.DoconutHost.Services.GetRequiredService<DocumentSigner>();
byte[] signaturePng = File.ReadAllBytes(HostingEnvironment.MapPath("~/App_Data/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 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 sorgente .docx, SignRequest.WordOutput sceglie l'output. Viene ignorato per le sorgenti 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 viene verificato ovunque
WordOutput.DocxIl documento rimane Word: l'immagine della firma viene inserita, più una firma di pacchetto OOXMLLimitato: non tutti i visualizzatori mostrano le firme di 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. App_Data è un buon posto per il file, perché IIS non lo serve mai:

csharp
Doconut.DoconutHost.Initialize(options =>
{
    options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
    options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
    options.AddSignerWidget(widget =>
    {
        widget.SigningCertificate = new SigningCertificate
        {
            PfxBytes = File.ReadAllBytes(HostingEnvironment.MapPath("~/App_Data/signing.pfx")),
            Password = System.Configuration.ConfigurationManager.AppSettings["DoconutSigner:Password"] ?? "",
        };
    });
});
csharp
Doconut.DoconutHost.Initialize(options =>
{
    options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
    options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
    options.AddSignerWidget(widget =>
    {
        widget.SigningCertificate = new SigningCertificate
        {
            PfxPath = HostingEnvironment.MapPath("~/App_Data/signing.pfx"),
            Password = System.Configuration.ConfigurationManager.AppSettings["DoconutSigner:Password"] ?? "",
        };
    });
});

Le proprietà di SigningCertificate sono solo init, cosa che C# 7.3 (il valore predefinito per i progetti .NET Framework) non può impostare. Imposta <LangVersion> su 9.0 o versioni successive nel file di progetto.

Il certificato è mantenuto solo in memoria. Non viene mai registrato, restituito a un client o salvato, e la password non compare mai 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 trasportarla.
  • La password corretta.
  • All'interno della sua finestra di validità. Un certificato scaduto o non ancora valido non interrompe l'app, ma 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 digital signature o non-repudiation, e un uso 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 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 su di esso, 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 DoconutHost.Initialize, così un PFX configurato in modo errato fallisce all'avvio anziché alla prima firma. Tre problemi generano un InvalidOperationException da Application_Start, e ogni richiesta risponde poi con un 500 vuoto; il messaggio è nel registro eventi di Windows:

MessaggioCorrezione
Doconut Signer: the certificate file was not found at '{path}'.Correggi PfxPath; assicurati che il file sia distribuito e leggibile dall'account del pool dell'applicazione
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

Su ASP.NET Core l'host registra anche una riga all'avvio indicando il certificato, o avvertendo che è scaduto o non emesso per la firma. DoconutHost non scrive quella riga, quindi su .NET Framework verifica un nuovo certificato firmando un documento di prova in modalità Certified.

La facciata C# non viene controllata all'avvio. Il certificato che passi a SignAsync viene letto al momento della firma, quindi un percorso o una password errati provocano il fallimento di quella chiamata.

Widget integrabile

Abilita gli endpoint

Gli endpoint ?sign=open|run|download del widget sono serviti da DocImage.axd e sono disattivati per impostazione predefinita. Abilitali accanto alla registrazione del plugin:

csharp
Doconut.DoconutHost.Initialize(options =>
{
    options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
    options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
    options.AddSignerWidget(widget =>
    {
        widget.MaxUploadMb = 25;           // predefinito
        widget.MaxSignatureImageKb = 512;  // predefinito
        // widget.SigningCertificate: vedere la configurazione del certificato; lasciarlo null per la firma demo (con filigrana)
    });
});
// System.Web legge l'intero upload prima che Doconut lo veda: mantenere maxRequestLength (KB) e
// maxAllowedContentLength (bytes) in Web.config sopra il MaxUploadMb del widget.

AddSignerWidget() senza argomenti abilita il widget con le impostazioni predefinite. Non concede la firma da solo: richiede AddPlugin<SignerPlugin>(), oppure DoconutHost.Initialize genera:

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.

Gli endpoint e lo script sono serviti dal gestore e dal modulo registrati in Web.config:

xml
<system.webServer>
  <handlers>
    <add name="DocImage" verb="GET,HEAD,POST" path="DocImage.axd" type="Doconut.DocImageHandler, Doconut" />
  </handlers>
  <modules>
    <add name="DoconutResources" type="Doconut.DoconutResourceModule, Doconut" />
  </modules>
</system.webServer>

Il modulo serve lo script indipendentemente dal fatto che il widget sia abilitato o meno. Senza AddSignerWidget(), il widget si carica e disegna la sua zona di rilascio, e la sua prima richiesta risponde con 404: il widget quindi segnala Signing is not enabled on this server.

Limiti di upload

ASP.NET legge l'intero corpo della richiesta prima che DocImage.axd venga eseguito. Un upload superiore a MaxUploadMb ma inferiore ai limiti dell'host ottiene il JSON 413 del widget (File is too large.). Un upload superiore ai limiti dell'host viene prima rifiutato da IIS, con una pagina di errore che il widget non può leggere. Mantieni entrambi i limiti dell'host al di sopra del limite del widget:

xml
<system.web>
  <httpRuntime maxRequestLength="30720" />           <!-- KILOBYTES: 30 MB -->
</system.web>
<system.webServer>
  <security>
    <requestFiltering>
      <requestLimits maxAllowedContentLength="31457280" />  <!-- BYTES: 30 MB -->
    </requestFiltering>
  </security>
</system.webServer>

Un upload inviato senza un Content-Length (chunked) che supera i limiti dell'host ottiene comunque la pagina di errore di IIS; non esiste una soluzione alternativa per quel caso.

Incorporamento

Lo script è servito a /doconut-res/js/doconutSigner.js. È un unico file autonomo senza dipendenze. Puntare basePath al gestore:

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

Doconut.signer(selectorOrElement, options) accetta un selettore CSS o un elemento, genera un'eccezione se il mount non è trovato, e restituisce un handle. Il basePath predefinito del widget, /doconut, è l'endpoint ASP.NET Core; in questo pacchetto deve essere '/DocImage.axd'.

Il firmatario carica un file PDF o .docx, crea una firma (Draw su una tela, Type un nome in un font di firma, o Image da un PNG, JPG o GIF), la trascina e ridimensiona sulla pagina, e 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. Imposta '/DocImage.axd' su questo pacchetto
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 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 le sorgenti .docx. Con false, il widget utilizza wordOutput
labelsobject{}Sovrascrive qualsiasi sottoinsieme delle stringhe inglesi

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

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

Richiamate

RichiamataScatta quandoCarico
onReadyUna volta, al mount (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 lancia un'eccezione viene catturato e registrato; non interrompe mai il flusso del widget.

Gestore imperativo

MetodoComportamento
reset()Ritorna alla schermata di drop e pulisce il flusso corrente. Non lancia più onReady. Nessuna operazione dopo destroy()
loadFile(file)Avvia il flusso con un File. Nessuna operazione a meno che il widget non sia nella schermata di drop; chiamare reset() prima se necessario
destroy()Rimuove i listener, svuota il mount e congela l'istanza
javascript
const signerWidget = Doconut.signer('#host', {
  basePath: '/DocImage.axd',
  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 ad esempio 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

Altri tasti 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 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 montaggio e legge i suoi colori, raggio e caratteri dalle proprietà personalizzate CSS, così puoi tematizzarlo senza toccare il suo interno:

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 carattere UI di sistema e un carattere corsivo per la firma.

Costruisci il tuo frontend

Il widget è un client per questo contratto HTTP su DocImage.axd. Le rotte rispondono 404 fino a quando 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 /DocImage.axd?sign=open (multipart, one file)Carica un PDF o .docx e aprilo per l'anteprima200 — { token, name, pages, ext }
POST /DocImage.axd?sign=run (JSON body)Firma il file caricato200 — { downloadToken, downloadName, watermarked }
GET /DocImage.axd?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 utilizza la rotta immagine del visualizzatore standard, /DocImage.axd?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, senza distinzione tra maiuscole e minuscole; 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 è troncato, un valore vuoto viene scartato e ognuno è limitato a 256 caratteri
wordOutputpdf (predefinito) o docx; ignorato per le fonti 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 MaxUploadMb (ma non i limiti IIS)File 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 sua 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 sanitizzato
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('image/png').split(',')[1].
async function signFile(file, pngBase64) {
  const base = '/DocImage.axd';

  // 1. apri: 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. esegui: 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. scarica: recupera 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 dell'applicazione, oppure fai il reverse-proxy di DocImage.axd e /doconut-res sotto l'origine della tua UI.

In produzione

  1. Installa il plugin accanto al pacchetto core, alla stessa versione: Install-Package Doconut.NETFramework.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:

    xml
    <appSettings>
      <add key="DoconutSigner:PfxPath" value="~/App_Data/your-certificate.pfx" />
    </appSettings>
    csharp
    var settings = System.Configuration.ConfigurationManager.AppSettings;
    
    Doconut.DoconutHost.Initialize(options =>
    {
        options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
        options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
        options.AddSignerWidget(widget => widget.SigningCertificate = new SigningCertificate
        {
            PfxPath = HostingEnvironment.MapPath(settings["DoconutSigner:PfxPath"]),
            Password = settings["DoconutSigner:Password"] ?? "",
        });
    });

    Mantieni il .pfx in App_Data, che IIS non serve mai, e tieni la password fuori da un Web.config in chiaro: usa una sezione di configurazione crittografata, o un secret store che il tuo deployment legge.

  5. Firma un documento di prova in modalità Certified. Un certificato scaduto o non ancora valido viene rifiutato con The signing certificate expired on yyyy-MM-dd. (o is not valid before), e un lettore PDF mostra se la firma è attendibile.

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 su 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 suo risultato in memoria sul server che ha servito open. Dietro un bilanciatore di carico senza sessioni sticky, una successiva richiesta run, download o di anteprima può raggiungere un altro server e non trovare il caricamento. Registra lo store condiviso e crittografato del widget tramite il secondo argomento di DoconutHost.Initialize:

csharp
byte[] farmKey = Convert.FromBase64String(System.Configuration.ConfigurationManager.AppSettings["Doconut:FarmKey"]);

Doconut.DoconutHost.Initialize(
    options =>
    {
        options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
        options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
        options.AddSignerWidget();
    },
    services => services.AddDoconutDistributedWidgets(store =>
    {
        store.RootPath = @"\\fileshare\doconut";   // una cartella che ogni server può leggere e scrivere
        store.FarmKey = farmKey;                   // almeno 32 bytes, identico su ogni server
        // store.Ttl = TimeSpan.FromMinutes(30);   // per quanto tempo viene conservato un upload (il valore predefinito)
    }));
  • Un singolo server non ha bisogno di nulla: senza questa chiamata viene usato lo store 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 server. 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 server 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 da DoconutHost.Services; 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ù i metadati opzionali del firmatario.

VisibleSignature and 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 originale, 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 and 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. I setter sono solo init: il progetto richiede C# 9.0 o successivo.

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
Ogni richiesta restituisce un 500 vuoto dopo aver aggiunto il plugin; il registro eventi mostra 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 fuori dalla sua finestra di versioneInstalla una licenza che conceda Signer, o rimuovi AddPlugin<SignerPlugin>()
Il registro eventi mostra AddSignerWidget() was called but the Signer plugin is not registered.Il widget è abilitato senza il suo pluginAggiungi options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>()
Il registro eventi mostra Doconut Signer: the certificate file was not found at '{path}'.PfxPath punta a un file mancanteCorreggi il percorso; distribuisci il file dove l'account del pool dell'app può leggerlo
Il registro eventi mostra Doconut Signer: the signing certificate could not be opened — the password is incorrect or the file is not a valid .pfx.Password errata, o file non PKCS#12Verifica la password; usa un vero .pfx
Il registro eventi mostra 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
new SigningCertificate { … } non compilaIl progetto usa C# 7.3, che non può impostare proprietà init-onlyImposta <LangVersion> a 9.0 o successivo
Risoluzione di DocumentSigner genera No IDocumentSigner is registered.SignerPlugin non è registratoAggiungi AddPlugin<SignerPlugin>() in DoconutHost.Initialize
L'output è contrassegnato da filigranaLa licenza è temporanea (Demo/NFR)Usa una licenza a pagamento che conceda 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 widget si carica ma dice Signing is not enabled on this server.AddSignerWidget() non è stato chiamato, o basePath non è '/DocImage.axd'Chiama AddSignerWidget(); imposta basePath: '/DocImage.axd'
Un caricamento grande mostra una pagina di errore IIS invece del messaggio del widgetmaxRequestLength / maxAllowedContentLength sono al di sotto di MaxUploadMbAumenta entrambi i limiti host sopra MaxUploadMb
run risponde 400 The signature image must be a PNG., Signature image is not valid base64. o Signature image is too large.Un'interfaccia personalizzata ha inviato un URL data:, un JPG, o più di MaxSignatureImageKbInvia un PNG base64 semplice entro il limite
open risponde 413 File is too large.Il caricamento supera MaxUploadMbAumenta MaxUploadMb in AddSignerWidget; il maxUploadMb del widget è solo un controllo lato client
run o download risponde 404 Upload expired — please re-open the file.La finestra di 30 minuti è scaduta, o un altro server nel farm non ha il caricamentoApri nuovamente 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, 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 fidato)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 CORSServi l'UI dalla stessa origine, o usa un reverse-proxy per DocImage.axd e /doconut-res
Il tema non viene applicatoIl selettore punta a un elemento dentro il mountPunta al mount stesso: #host.dsw o #host

Note sul framework

Confrontato con i pacchetti ASP.NET Core, questo pacchetto differisce solo per l'hosting; l'API, il contratto dell'endpoint, lo script del widget e le regole di licenza sono gli stessi.

  • Registrazione è in Application_Start, tramite DoconutHost.Initialize, invece di builder.Services.AddDoconut. Servizi come AddDoconutDistributedWidgets vanno nel suo secondo argomento.
  • Endpoint sono serviti da DocImage.axd e lo script da DoconutResourceModule, entrambi registrati in Web.config, invece di UseDoconut() e UseDoconutResources(). Il widget richiede basePath: '/DocImage.axd'.
  • Errori di avvio si manifestano come un 500 vuoto in ogni richiesta, con la ragione nel registro eventi di Windows.
  • Caricamenti vengono letti completamente da ASP.NET prima che Doconut li veda, quindi i limiti di IIS devono essere superiori a MaxUploadMb.
  • Nessuna riga di log di avvio sul certificato: i tre errori del certificato vengono comunque lanciati, ma la riga che nomina il certificato non viene scritta.
  • C# 9.0 o successivo è necessario per impostare le proprietà init-only di SigningCertificate.
  • Solo Windows, come il resto del pacchetto .NET Framework.

Questa pagina è stata utile?