Plugin Signataire

Signez des documents PDF et Word avec une signature visible et un sceau numérique

Le plugin Signer place une signature visible sur un document et, par défaut, le scelle avec une signature numérique qu'un lecteur PDF peut vérifier. Il signe les fichiers PDF et Word (.docx). La signature visible est toujours une image PNG : dessinée, tapée ou téléchargée par le signataire.

SurfaceUtilisez‑le lorsque
DocumentSigner (C#)Vous signez sur le serveur, sans navigateur impliqué
Drop‑in widget (doconutSigner.js)Vous voulez un écran d'upload, de signature et de téléchargement prêt à l'emploi dans votre page
HTTP endpoints on DocImage.axd (?sign=open|run|download)Vous construisez votre propre interface de signature en vous basant sur un contrat serveur documenté

Chaque signature est placée une seule fois, sur une page. Le nom du signataire, le motif et le lieu peuvent l'accompagner.

Installer le paquet

powershell
Install-Package Doconut.NETFramework.Signer

Pour fixer le plugin à la version décrite dans cette documentation :

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

Conservez le paquet Signer à la même version que Doconut.NETFramework.

Le fichier de licence du plugin, Doconut.Viewer.Signer.lic, se place dans le même dossier que Doconut.Viewer.lic ; il est lu avec la licence du visualiseur.

Enregistrer le plugin

Comme tout plugin Doconut, Signer s'enregistre avec AddPlugin<TPlugin>() dans DoconutHost.Initialize, appelé depuis Application_Start :

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

Ajoutez Doconut.DoconutHost.Shutdown() à Application_End afin que le travail en arrière‑plan s'arrête proprement lorsque le pool d'applications se recycle.

C'est tout ce dont la façade C# a besoin. Le widget et ses points de terminaison HTTP sont une option séparée, AddSignerWidget() (voir Widget intégré).

Le plugin nécessite une licence qui accorde la capacité Signer. Sans celle‑ci, DoconutHost.Initialize lève une exception depuis 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.

Dans System.Web, cela signifie que chaque requête renvoie un 500 vide, et la raison n'apparaît que dans le journal d'événements Windows (source ASP.NET). Une exception est levée en l'absence de licence, avec un fichier TRIAL hérité, une licence sans Signer, ou une licence payante utilisée en dehors de sa fenêtre de version. Les licences temporaires Démo/NFR sont acceptées. Voir Configuration de la licence.

Licence et filigrane

État de la licenceDémarrageSignature certifiéeSignature visuelle
Licence payante accordant Signer, certificat configuréDémarreScellé avec votre certificat, propre (watermarked: false)Propre
Licence payante accordant Signer, aucun certificatDémarreRefusée : No signing certificate configured.Propre
Licence payante, certificat expiré ou pas encore valideDémarreRefusée : The signing certificate expired on yyyy-MM-dd.Propre
Licence temporaire Démo/NFR, active ou expiréeDémarreScellé avec le certificat de démonstration intégré, filigrané (watermarked: true)Filigrané
Pas de licence, un fichier TRIAL hérité, une licence sans Signer, ou une licence payante hors de sa fenêtre de versionApplication_Start lève une exception ; chaque requête renvoie un 500 vide——

La règle est la même pour la façade C# et le widget : la sortie est filigranée lorsque la licence n'est pas une licence de visualiseur payante ou qu'elle est temporaire. Sous une licence temporaire, le plugin signe toujours avec son certificat de démonstration intégré, et tout certificat que vous configurez n'est pas utilisé.

Le certificat de démonstration produit un sceau authentique, mais les lecteurs PDF ne le font pas confiance. Une intégration peut être construite et testée de bout en bout avec une licence d'évaluation ; pour obtenir une sortie propre et fiable, vous avez besoin à la fois d'une licence payante et de votre propre certificat de signature.

Utilisation depuis C#

DocumentSigner est enregistré par DoconutHost.Initialize ; résolvez‑le depuis DoconutHost.Services. Son constructeur est interne, donc ne new jamais. Le résoudre sans AddPlugin<SignerPlugin>() lève 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 par défaut Certified (signature visible + sceau numérique) ; WordOutput par défaut 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 prend le flux source, son extension (".pdf" ou ".docx"), la requête et le certificat pour cet appel. La façade ne lit pas SignerWidgetOptions.SigningCertificate ; ce paramètre est destiné au widget. Passez null sous une licence de démonstration, ou en mode Visual.

SignResult contient le document signé sous forme de flux recherchable, ainsi que son Extension (".pdf" ou ".docx") afin que vous puissiez nommer le fichier. Vous possédez le flux : libérez‑le lorsque vous avez terminé.

Dans un contrôleur MVC 5

Rendez l'action asynchrone et await la signature. Celle‑ci appose une signature Visual, qui ne nécessite aucun certificat :

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);
}

Une source Word est signée en PDF sauf si vous demandez une sortie Word. Nommez le résultat depuis 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 lève une exception au lieu de retourner lorsque l'appel ne peut pas réussir :

ExceptionMessageQuand
InvalidOperationExceptionNo signing certificate configured.Mode certifié, une licence payante, et aucun certificat fourni
InvalidOperationExceptionThe signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd.Mode certifié avec un certificat hors de sa période de 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.Octets PNG vides, ou un placement qui n'est pas valide
NotSupportedExceptionThe signer supports PDF and Word (.docx) documents; got '{extension}'.Tout autre type de source

Modes de signature, sortie Word et certificats

Modes de signature

SignRequest.Mode choisit si la signature est scellée.

ModeCe qu'il produitCertificatVérifiable
SignatureMode.Certified (default)La signature visible plus un sceau numériqueRequis sous licence payanteOui
SignatureMode.VisualSeulement la signature visibleJamais nécessaireNon : c'est une image

Utilisez Certified lorsque la signature doit être prouvable : approbations, contrats, tout ce qu'un vérificateur doit vérifier pour l'identité et l'intégrité. Utilisez Visual lorsque vous avez seulement besoin de l'apparence d'une signature, ou que vous n'avez pas de certificat. Une licence temporaire ajoute un filigrane aux deux.

Les sceaux PDF sont des signatures détachées PKCS#7 (adbe.pkcs7.detached) avec SHA-256, pour les clés RSA ou ECDSA. Ils contiennent les certificats de l'émetteur trouvés dans votre PFX, de sorte qu'un lecteur qui fait confiance à votre racine peut construire la chaîne. Les sceaux natifs Word sont des signatures de paquet OOXML et ne contiennent que le certificat du signataire.

Documents Word

Pour une source .docx, SignRequest.WordOutput choisit la sortie. Elle est ignorée pour les sources PDF, qui produisent toujours un PDF.

SortieCe qui se passeSupport du vérificateur
WordOutput.Pdf (default)Le document est converti en PDF, puis signé et scelléÉtendu : un PDF signé est vérifié partout
WordOutput.DocxLe document reste Word : l'image de la signature y est placée, plus une signature de paquet OOXMLLimité : tous les visionneurs n'affichent pas les signatures de paquet OOXML

Conservez le PDF sauf si le destinataire a besoin d'un fichier Word éditable et accepte le support limité du vérificateur.

Configuration du certificat

Pour sceller avec votre propre identité, fournissez au plugin un fichier PFX (PKCS#12) qui inclut la clé privée. Pour le widget, définissez SignerWidgetOptions.SigningCertificate ; pour la façade C#, transmettez le certificat à SignAsync. Fournissez soit les octets soit un chemin, plus le mot de passe. App_Data est un bon emplacement pour le fichier, car IIS ne le sert jamais :

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"] ?? "",
        };
    });
});

Les propriétés de SigningCertificate sont uniquement init, ce que C# 7.3 (la valeur par défaut pour les projets .NET Framework) ne peut pas définir. Définissez <LangVersion> sur 9.0 ou une version ultérieure dans le fichier projet.

Le certificat n'est conservé qu'en mémoire. Il n'est jamais journalisé, renvoyé à un client, ou persistant, et le mot de passe n'apparaît jamais dans un message d'erreur.

Exigences :

  • Un bundle PFX / PKCS#12 avec sa clé privée. Un fichier contenant uniquement la clé publique (.cer, .crt) ne peut pas signer. Exportez la chaîne de l'émetteur avec, afin que les sceaux PDF puissent la porter.
  • Le mot de passe correct.
  • Dans sa fenêtre de validité. Un certificat expiré ou pas encore valide n'arrête pas l'application, mais les signatures Certified sont refusées jusqu'à son remplacement. Les signatures Visual ne sont pas affectées.
  • Émis pour la signature de documents : une utilisation de clé avec signature numérique ou non‑repudiation, et une utilisation étendue de clé, si présente, qui autorise la signature de documents, la protection des e‑mails ou l'authentification client. Un certificat émis pour autre chose, comme un certificat de serveur TLS, signe toujours, mais les lecteurs PDF signalent la signature.
  • Les jetons matériels, cartes à puce, HSM et le magasin de certificats Windows ne sont pas pris en charge. Exportez le certificat, avec sa clé privée et sa chaîne, vers un PFX.

Créer un PFX à partir d'un certificat et de sa clé privée avec OpenSSL :

bash
openssl pkcs12 -export -out signing.pfx -inkey private.key -in certificate.crt
# Le mot de passe d'exportation que vous êtes invité à saisir est SigningCertificate.Password.

Exporter un depuis le magasin de certificats Windows : ouvrez certmgr.msc et trouvez le certificat (son icône montre une clé lorsque la clé privée est présente). Faites un clic droit, choisissez Toutes les tâches → Exporter…, sélectionnez Oui, exporter la clé privée, choisissez Échange d'informations personnelles – PKCS #12 (.PFX), et définissez un mot de passe.

Vérifications de démarrage

Lorsque le widget est activé, le certificat dans SignerWidgetOptions.SigningCertificate est vérifié une fois, à l'intérieur de DoconutHost.Initialize, de sorte qu'un PFX mal configuré échoue au démarrage plutôt qu'à la première signature. Trois problèmes déclenchent un InvalidOperationException depuis Application_Start, et chaque requête répond alors avec un 500 vide ; le message apparaît dans le journal d'événements Windows :

MessageFix
Doconut Signer: the certificate file was not found at '{path}'.Corrigez PfxPath ; assurez‑vous que le fichier est déployé et lisible par le compte du pool d’applications
Doconut Signer: the signing certificate could not be opened — the password is incorrect or the file is not a valid .pfx.Vérifiez le mot de passe ; assurez‑vous que le fichier est un vrai .pfx, pas un .cer ou .pem
Doconut Signer: the signing certificate has no private key. Re-export the .pfx INCLUDING the private key.Exportez à nouveau le PFX avec la clé privée

Sur ASP.NET Core, l’hôte consigne également une ligne au démarrage indiquant le certificat, ou avertissant qu’il est expiré ou non délivré pour la signature. DoconutHost n’écrit pas cette ligne, donc sous .NET Framework il faut vérifier un nouveau certificat en signant un document de test en mode Certified.

La façade C# n’est pas vérifiée au démarrage. Le certificat que vous transmettez à SignAsync est lu lors de la signature, de sorte qu’un chemin ou un mot de passe incorrect provoque l’échec de cet appel.

Widget intégrable

Activer les points de terminaison

Les points de terminaison ?sign=open|run|download du widget sont servis par DocImage.axd et sont désactivés par défaut. Activez‑les à côté de l’enregistrement du 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;           // la valeur par défaut
        widget.MaxSignatureImageKb = 512;  // la valeur par défaut
        // widget.SigningCertificate : voir la configuration du certificat ; laisser null pour la signature de démonstration (filigrane)
    });
});
// System.Web lit l'intégralité du téléchargement avant que Doconut ne le voie : conserver maxRequestLength (KB) et
// maxAllowedContentLength (bytes) dans Web.config au-dessus du MaxUploadMb du widget.

AddSignerWidget() sans argument active le widget avec les valeurs par défaut. Il ne confère pas la signature en soi : il nécessite AddPlugin<SignerPlugin>(), ou DoconutHost.Initialize déclenche :

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.

Les points de terminaison et le script sont servis par le gestionnaire et le module enregistrés dans 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>

Le module sert le script que le widget soit activé ou non. Sans AddSignerWidget(), le widget se charge et dessine sa zone de dépôt, et sa première requête répond 404 : le widget signale alors Signing is not enabled on this server.

Limites de téléchargement

ASP.NET lit tout le corps de la requête avant que DocImage.axd s’exécute. Un téléchargement supérieur à MaxUploadMb kilooctets mais inférieur aux limites de l’hôte renvoie le JSON propre au widget 413 (File is too large.). Un téléchargement supérieur aux limites de l’hôte est d’abord rejeté par IIS, avec une page d’erreur que le widget ne peut pas lire. Gardez les deux limites d’hôte au‑dessus de la capacité du widget :

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

Un téléchargement envoyé sans Content-Length (chunked) qui dépasse les limites de l’hôte renvoie également la page d’erreur d’IIS ; il n’existe aucun contournement pour ce cas.

Intégrer

Le script est servi à /doconut-res/js/doconutSigner.js. C'est un fichier unique et autonome, sans dépendances. Pointez basePath vers le gestionnaire :

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) prend un sélecteur CSS ou un élément, lève une exception si le point de montage n'est pas trouvé, et renvoie un handle. Le basePath par défaut du widget, /doconut, est le point de terminaison ASP.NET Core ; dans ce paquet il doit être '/DocImage.axd'.

Le signataire téléverse un fichier PDF ou .docx, crée une signature (Dessiner sur un canevas, Saisir un nom dans une police de signature, ou Image à partir d'un PNG, JPG ou GIF), la fait glisser et la redimensionne sur la page, puis signe et télécharge le résultat. Le widget envoie toujours la signature au format PNG ; une image téléversée est convertie dans le navigateur en PNG qui s'ajuste à 520×160.

Options

OptionTypePar défautRemarques
basePathstring'/doconut'Où les points de terminaison ?sign= et les images d'aperçu sont servis. Définissez '/DocImage.axd' sur ce paquet
resPathstring'/doconut-res'Réservé ; le widget inclut son propre CSS
maxUploadMbnumber25Vérification uniquement côté client, donc un fichier trop volumineux échoue rapidement. La limite serveur est MaxUploadMb dans AddSignerWidget
maxSignatureKbnumber512Limite côté client pour le mode Image. Conservez-la égale à MaxSignatureImageKb du serveur
previewWidthnumber560Largeur en pixels de l'aperçu de la page
licenseUrlstring | nullnullTransforme l’avertissement de filigrane de démonstration en un lien vers cette URL
signatureModestring'certified'Type de signature initial : 'certified' ou 'visual'. Toute autre valeur devient 'certified'
showSignatureModeTogglebooleantrueAffiche le choix Signature numérique / Visuel uniquement. Avec false, le widget signe avec signatureMode
wordOutputstring'pdf'Sortie initiale pour les sources .docx : 'pdf' ou 'docx'. Toute autre valeur devient 'pdf'
showOutputFormatTogglebooleantrueAffiche le choix PDF / Word, uniquement pour les sources .docx. Avec false, le widget utilise wordOutput
labelsobject{}Remplace tout sous-ensemble des chaînes anglaises

Masquer un bascule ne désactive pas la fonctionnalité ; cela fixe la valeur. Deux configurations courantes :

javascript
// Les deux bascules affichées, signature numérique par défaut : un signataire en libre-service complet.
Doconut.signer('#host', { basePath: '/DocImage.axd', licenseUrl: '/pricing' });
javascript
// Visuel uniquement, pas de bascule : un tampon simple sans signature numérique offerte.
Doconut.signer('#host', {
  basePath: '/DocImage.axd',
  signatureMode: 'visual',
  showSignatureModeToggle: false
});

Rappels

RappelSe déclenche quandDonnées
onReadyUne fois, au montage (pas de nouveau sur reset())—
onSourceLoadedLe fichier est ouvert et son aperçu affiché{ file: { token, name, pages, ext } }
onSignedLa signature réussit{ downloadToken, downloadName, watermarked }
onDownloadÀ chaque clic sur Télécharger{ downloadName, downloadToken }
onErrorUne étape d'ouverture, de signature ou de téléchargement échoue, ou un fichier en mode Image est trop volumineux{ message }

Un rappel qui lève une exception est intercepté et enregistré ; il ne casse jamais le flux du widget.

Manipulateur impératif

MéthodeComportement
reset()Retourne à l'écran de dépôt et réinitialise le flux actuel. Ne déclenche pas à nouveau onReady. Aucun effet après destroy()
loadFile(file)Démarre le flux avec un(e) File. Aucun effet sauf si le widget est sur son écran de dépôt ; appelez reset() d'abord si nécessaire
destroy()Supprime les écouteurs, vide le point de montage et fige l'instance
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());

Étiquettes

Chaque chaîne possède une valeur par défaut en anglais ; labels remplace tout sous‑ensemble et le reste reste en anglais. Les fragments qui changent à l'exécution utilisent {placeholders}, comme uploading: 'Uploading {name}…' et pages: '{n} pages'.

CléValeur par défaut en anglais
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

D'autres clés couvrent l'étape de placement, l'écran d'erreur, le formulaire lié de l'avis de démonstration (demoNoticePrefix, demoNoticeLink, demoNoticeSuffix) et les annonces aria-live.

Lorsque open ou run répond 404 sans erreur JSON, le widget affiche signingNotEnabled. Une erreur JSON provenant du serveur l'emporte toujours, ainsi les messages tels qu'un téléversement expiré restent visibles.

Thématisation

Le widget ajoute la classe dsw à son élément d'ancrage et lit ses couleurs, rayons et polices à partir des propriétés personnalisées CSS, de sorte que vous pouvez le thématiser sans toucher à son fonctionnement interne :

css
#host.dsw {
  --dsw-accent: #b0522b;       /* liens, focus, mode actif */
  --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;   /* le mode Type */
}

Valeurs par défaut : --dsw-accent: #2b6cb0, --dsw-bg: #ffffff, --dsw-fg: #1a202c, --dsw-muted: #718096, --dsw-border: #cbd5e0, --dsw-radius: 8px, une police d'interface système et une police cursive pour la signature.

Créez votre propre frontend

Le widget est un client de ce contrat HTTP sur DocImage.axd. Les routes répondent 404 jusqu'à ce que AddSignerWidget() soit appelé. Les erreurs contiennent un corps JSON, { "error": "..." }, sauf lorsque le tableau indique « statut uniquement ». Une valeur ?sign= inconnue répond 400.

RouteObjectifRéponse réussie
POST /DocImage.axd?sign=open (multipart, un fichier)Téléversez un PDF ou .docx et ouvrez-le pour aperçu200 — { token, name, pages, ext }
POST /DocImage.axd?sign=run (corps JSON)Signez le fichier téléversé200 — { downloadToken, downloadName, watermarked }
GET /DocImage.axd?sign=download&token=<downloadToken>Diffusez le fichier signé200 — le fichier, Content-Disposition: attachment, Cache-Control: no-store

ext dans la réponse open inclut le point initial (".docx"). L'aperçu de page utilise la route d'image du visualiseur standard, /DocImage.axd?token={token}&page={n}&thumb=1&width={px} ; la page affichée devient placement.page.

Le corps 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"
}
ChampRemarques
tokenLe jeton provenant de open
signature.kindDrawn, Typed ou Image, insensible à la casse ; tout autre devient Drawn. Un indice seulement : la charge utile est toujours un PNG
signature.payloadUn PNG brut en base64, sans préfixe data:. Il doit s'agir d'un vrai PNG et ne pas dépasser MaxSignatureImageKb une fois décodé
placement.pageIndexé à partir de 1
placement.x / y / w / h0..1 normalisé depuis le coin supérieur gauche, avec x + w ≤ 1 et y + h ≤ 1
meta.signerName / reason / locationFacultatif. Chaque valeur est tronquée, une valeur vide est ignorée, et chaque valeur est coupée à 256 caractères
wordOutputpdf (par défaut) ou docx ; ignoré pour les sources PDF. Tout autre devient pdf
modecertified (par défaut) ou visual. Tout autre devient certified

downloadName suit la sortie : <source>-signed.pdf ou <source>-signed.docx, et download envoie le Content-Type correspondant.

La source téléversée et le résultat signé sont conservés chacun pendant 30 minutes. Après cela, run et download répondent 404 et le fichier doit être ouvert à nouveau. Tous les jetons sont des GUID.

RouteStatutQuandCorps
any404Le widget n'est pas activéstatut uniquement
any405Verbe incorrect (open et run nécessitent POST, download nécessite GET)statut uniquement
open400Pas un téléversement multipartExpected a multipart file upload.
open400Aucun fichier, ou un fichier videNo file uploaded.
open400Tout autre chose que .pdf ou .docxSigning supports PDF and Word (.docx) files only.
open413Le téléversement dépasse MaxUploadMb (mais pas les limites IIS)File is too large.
run400Le corps n'est pas un JSON valide, ou est videMalformed request. / Empty request.
run400Le jeton est manquant ou n'est pas un GUIDInvalid token.
run404Le téléversement a expiré ou n'a jamais été ouvertUpload expired — please re-open the file.
run400Pas de signature, ou pas de placementNo signature supplied. / No placement supplied.
run400La charge utile n'est pas en base64, est vide, trop grande, ou n'est pas un PNGSignature image is not valid base64. / Signature image is empty. / Signature image is too large. / The signature image must be a PNG.
run400Le placement est hors de la pageThe signature or its placement is invalid.
run400Mode certifié, une licence payante et aucun certificatNo signing certificate configured.
run400Mode certifié avec un certificat hors de sa période de validitéThe signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd.
open, run500Échec du traitementUn message assaini
download400Le jeton est manquant ou n'est pas un GUIDstatut uniquement
download404Jeton inconnu ou expiréstatut uniquement

Un cycle complet avec fetch :

javascript
// file: le fichier à signer ; pngBase64: la signature sous forme d'un PNG base64 brut, sans préfixe data:,
// par exemple canvas.toDataURL('image/png').split(',')[1].
async function signFile(file, pngBase64) {
  const base = '/DocImage.axd';

  // 1. open: téléverser le fichier
  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: le signer
  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: récupérer le fichier signé
  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);
}

Les points de terminaison sont same-origin : cette version ne prend pas en charge CORS. Servez votre UI et le script du widget depuis la même origine que l'application, ou reverse-proxy DocImage.axd et /doconut-res sous l'origine de votre UI.

En production

  1. Installez le plugin à côté du paquet principal, à la même version : Install-Package Doconut.NETFramework.Signer.

  2. Ajoutez le fichier de licence. Placez Doconut.Viewer.Signer.lic dans le même dossier que Doconut.Viewer.lic.

  3. Obtenez votre certificat au format PFX avec sa clé privée et sa chaîne d'émetteur, auprès d'une autorité de certification ou de la PKI interne de votre organisation. Pour tester d'abord, utilisez une licence de démonstration (le certificat de démonstration intégré, filigrané) ou un PFX auto-signé.

  4. Lisez le certificat depuis la configuration, afin que le modifier ne nécessite jamais de changement de code :

    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"] ?? "",
        });
    });

    Conservez le .pfx dans App_Data, que IIS ne sert jamais, et gardez le mot de passe hors d'un Web.config en texte clair : utilisez une section de configuration chiffrée, ou un magasin de secrets que votre déploiement lit.

  5. Signez un document de test en mode Certifié. Un certificat expiré ou pas encore valide est refusé avec The signing certificate expired on yyyy-MM-dd. (ou is not valid before), et un lecteur PDF indique s'il fait confiance à la signature.

Confiance dans les lecteurs PDF. Un lecteur indique que la signature est valide lorsqu'il fait confiance à la racine du certificat. Avec la PKI de votre organisation, cela s'applique à chaque machine qui fait confiance à votre racine, ce qui est généralement chaque machine au sein de l'organisation. Les certificats qu'Adobe accepte sur n'importe quelle machine (la Adobe Approved Trust List) sont, à notre connaissance, émis avec la clé privée sur un token matériel ou un HSM, ce que ce plugin ne peut pas utiliser : il signe uniquement à partir d'un PFX. Confirmez avec votre fournisseur de certificat avant de vous fier à ce type de confiance.

Fermes Web

Le widget conserve chaque téléchargement et son résultat en mémoire sur le serveur qui a servi open. Derrière un équilibreur de charge sans sessions persistantes, une requête ultérieure de run, download ou de prévisualisation peut atteindre un autre serveur et ne pas trouver le téléchargement. Enregistrez le magasin partagé et chiffré du widget via le deuxième argument de 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";   // un dossier que chaque serveur peut lire et écrire
        store.FarmKey = farmKey;                   // au moins 32 octets, identique sur chaque serveur
        // store.Ttl = TimeSpan.FromMinutes(30);   // combien de temps un téléchargement est conservé (par défaut)
    }));
  • Un serveur unique n'a besoin de rien : sans cet appel, le magasin en mémoire est utilisé.
  • Les téléchargements et les résultats sont chiffrés au repos sur le partage (AES-256, encrypt-then-MAC), et chaque fichier est lié à son token, de sorte qu'un token ne peut jamais lire le fichier d'un autre.
  • FarmKey doit faire au moins 32 octets et être identique sur chaque serveur. Chargez-le depuis un magasin de secrets ; ne le codez jamais en dur. L'enregistrement lève un ArgumentException lorsque RootPath est manquant ou que FarmKey est plus court que 32 octets.
  • Pointez RootPath vers le même emplacement partagé utilisé par le visualiseur distribué, et fournissez à chaque serveur le même certificat de signature.

Référence de l'API

La façade et les options du widget se trouvent dans l'espace de noms Doconut ; les types de requête et de résultat sont dans Doconut.Core.Models.Signing. SignerPlugin se trouve dans 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);
}

Résolu à partir de DoconutHost.Services ; le constructeur est interne. sourceExtension est ".pdf" ou ".docx". Sous une licence payante, cert est utilisé et la sortie est propre ; sous une licence temporaire, le certificat de démonstration intégré est utilisé, cert est ignoré, et la sortie est filigranée.

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
}

Une signature visible placée une fois, plus des métadonnées facultatives du signataire.

VisibleSignature et SignatureKind

csharp
public sealed record VisibleSignature(SignatureKind Kind, byte[] PngBytes)
{
    public bool IsValid { get; }   // PngBytes n'est pas vide
}

public enum SignatureKind { Drawn, Typed, Image }

PngBytes est un PNG pour chaque type. Une signature dessinée ou tapée est transparente ; une image téléchargée conserve la transparence qu'elle possédait, ainsi un JPG opaque reste opaque. Kind n'est qu'une indication.

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 est basé à 1 ; X, Y, W et H sont des 0..1 normalisés depuis le coin supérieur gauche.

SignatureMode et WordOutput

csharp
public enum SignatureMode { Certified, Visual }   // Certified est la valeur par défaut
public enum WordOutput { Pdf, Docx }              // Pdf est la valeur par défaut ; ignoré pour les sources PDF

SignResult

csharp
public sealed record SignResult(Stream Stream, string Extension);

Le document signé sous forme de flux recherchable, et son extension avec le point (".pdf" ou ".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 n'est pas vide, ou PfxPath n'est pas vide
}

Définissez soit PfxBytes, soit PfxPath, plus Password. Les mutateurs sont uniquement init‑only : le projet nécessite C# 9.0 ou une version ultérieure.

SignerWidgetOptions

csharp
public sealed class SignerWidgetOptions
{
    public int MaxUploadMb { get; set; } = 25;
    public int MaxSignatureImageKb { get; set; } = 512;
    public SigningCertificate? SigningCertificate { get; set; }
}

Défini via DoconutOptions.AddSignerWidget(Action<SignerWidgetOptions>? configure = null), qui renvoie le DoconutOptions afin que les appels puissent être enchaînés. Un SigningCertificate nul signifie le certificat de démonstration sous licence temporaire, et les signatures Visual uniquement sous licence payante.

Dépannage

SymptômeCauseSolution
Chaque requête renvoie un 500 vide après avoir ajouté le plugin ; le journal d'événements indique The Signer plugin is registered via AddPlugin but no active license grants Signer.Pas de licence, un fichier TRIAL, une licence sans Signer, ou une licence payante hors de sa fenêtre de versionInstallez une licence qui accorde Signer, ou retirez AddPlugin<SignerPlugin>()
Le journal d'événements indique AddSignerWidget() was called but the Signer plugin is not registered.Le widget est activé sans son pluginAjoutez options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>()
Le journal d'événements indique Doconut Signer: the certificate file was not found at '{path}'.PfxPath pointe vers un fichier manquantCorrigez le chemin ; déployez le fichier où le compte du pool d'applications peut le lire
Le journal d'événements indique Doconut Signer: the signing certificate could not be opened — the password is incorrect or the file is not a valid .pfx.Mot de passe incorrect, ou fichier qui n'est pas un PKCS#12Vérifiez le mot de passe ; utilisez un vrai .pfx
Le journal d'événements indique Doconut Signer: the signing certificate has no private key. Re-export the .pfx INCLUDING the private key.Le PFX a été exporté sans sa clé privéeExportez-le à nouveau avec la clé privée
new SigningCertificate { … } ne compile pasLe projet utilise C# 7.3, qui ne peut pas définir des propriétés init‑onlyDéfinissez <LangVersion> à 9.0 ou ultérieur
La résolution de DocumentSigner génère No IDocumentSigner is registered.SignerPlugin n'est pas enregistréAjoutez AddPlugin<SignerPlugin>() dans DoconutHost.Initialize
La sortie est filigranéeLa licence est temporaire (Demo/NFR)Utilisez une licence payante qui accorde Signer
run répond 400 No signing certificate configured.Une licence payante, le mode Certified, et aucun certificatConfigurez SigningCertificate, ou signez en mode Visual
run répond 400 The signing certificate expired on yyyy-MM-dd.Le certificat est périméRemplacez-le ; les signatures Visual continuent de fonctionner en attendant
Le widget se charge mais indique Signing is not enabled on this server.AddSignerWidget() n'a pas été appelé, ou basePath n'est pas '/DocImage.axd'Appelez AddSignerWidget() ; définissez basePath: '/DocImage.axd'
Un gros téléchargement affiche une page d'erreur IIS au lieu du message du widgetmaxRequestLength / maxAllowedContentLength sont en dessous de MaxUploadMbAugmentez les deux limites d'hôte au-dessus de MaxUploadMb
run répond 400 The signature image must be a PNG., Signature image is not valid base64. ou Signature image is too large.Une UI personnalisée a envoyé une URL data:, un JPG, ou plus de MaxSignatureImageKbEnvoyez un PNG base64 brut dans la limite
open répond 413 File is too large.Le téléchargement dépasse MaxUploadMbAugmentez MaxUploadMb dans AddSignerWidget ; le maxUploadMb du widget n'est qu'une vérification côté client
run ou download répond 404 Upload expired — please re-open the file.La fenêtre de 30 minutes est écoulée, ou un autre serveur du farm n'a pas le téléchargementRouvrez le fichier ; dans un farm, enregistrez AddDoconutDistributedWidgets
Un .docx signé n'affiche aucune signature dans certains visionneursLa sortie Word contient une signature de paquet OOXML, que de nombreux visionneurs n'affichent pasSignez en PDF, par défaut
Les lecteurs PDF indiquent que l'identité du signataire est inconnueLe lecteur ne fait pas confiance à la racine du certificat (le certificat de démonstration n'est jamais approuvé)Utilisez un certificat provenant d'une racine de confiance pour vos lecteurs
Le widget échoue lorsque l'UI se trouve sur une autre origineLes points de terminaison n'ont pas de support CORSServez l'UI depuis la même origine, ou reverse‑proxy DocImage.axd et /doconut-res
Le thème ne s'applique pasLe sélecteur cible un élément à l'intérieur du montageCiblez le montage lui‑même : #host.dsw ou #host

Notes du framework

Comparé aux packages ASP.NET Core, ce package ne diffère que par l'hébergement ; l'API, le contrat d'endpoint, le script du widget et les règles de licence sont les mêmes.

  • Enregistrement se trouve dans Application_Start, via DoconutHost.Initialize, au lieu de builder.Services.AddDoconut. Les services tels que AddDoconutDistributedWidgets vont dans son deuxième argument.
  • Points de terminaison sont servis par DocImage.axd et le script par DoconutResourceModule, tous deux enregistrés dans Web.config, au lieu de UseDoconut() et UseDoconutResources(). Le widget nécessite basePath: '/DocImage.axd'.
  • Échecs de démarrage apparaissent sous la forme d'un 500 vide à chaque requête, avec la raison dans le journal d'événements Windows.
  • Téléversements sont lus en entier par ASP.NET avant que Doconut ne les voie, donc les limites IIS doivent être supérieures à MaxUploadMb.
  • Pas de ligne de journal de démarrage concernant le certificat : les trois erreurs de certificat sont toujours levées, mais la ligne nommant le certificat n'est pas écrite.
  • C# 9.0 ou ultérieur est nécessaire pour définir les propriétés init-only de SigningCertificate.
  • Windows uniquement, comme le reste du package .NET Framework.

Cette page était-elle utile ?