Plugin Signer
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.
| Interface | Quand l’utiliser |
|---|---|
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 (?sign=open|run|download) | Vous construisez votre propre interface de signature contre un contrat serveur documenté |
Chaque signature est placée une seule fois, sur une page. Le nom du signataire, la raison et le lieu peuvent l’accompagner.
Installer le paquet
Installez la dernière version stable du plugin Signer :
dotnet add package Doconut.NET6.SignerPour fixer le plugin à la version décrite dans cette documentation, indiquez la version séparément :
dotnet add package Doconut.NET6.Signer --version 26.10.0Conservez le paquet Signer à la même version que Doconut.NET6. L’identifiant du paquet est Doconut.NET6.Signer ; .<version> n’apparaît que dans le nom du fichier .nupkg téléchargé.
Le fichier de licence du plugin, Doconut.Viewer.Signer.lic, se place dans le même dossier que Doconut.Viewer.lic ; il est lu conjointement avec la licence du visualiseur.
Plateformes. Le plugin s’exécute partout où Doconut.NET6 s’exécute : Windows, et Linux basé sur glibc en x64 (pas Alpine ou autres distributions basées sur musl). Sous Linux, installez la bibliothèque de configuration des polices avant que le premier document ne s’ouvre :
apt-get update && apt-get install -y libfontconfig1Sur RHEL, Fedora et distributions similaires, le paquet est fontconfig. Sans cela, l’ouverture d’un document échoue avec The system library libfontconfig1 is missing. Install it (Debian/Ubuntu: apt-get install -y libfontconfig1) and see the Linux section of the Doconut documentation..
Enregistrer le plugin
Comme tout plugin Doconut, Signer s’enregistre avec AddPlugin<TPlugin>() à l’intérieur de AddDoconut() :
builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
});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 licence, AddDoconut() lève une exception au démarrage, avant que l’application ne traite une requête :
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.Il lève une exception en l’absence de licence, avec un fichier legacy TRIAL, une licence sans Signer, ou une licence payante utilisée hors de sa fenêtre de version. Les licences temporaires Démo/NFR sont acceptées. Voir Configuration de licence pour le chargement des licences.
Licence & filigrane
| État de licence | Démarrage | Signature certifiée | Signature visuelle |
|---|---|---|---|
Licence payante accordant Signer, certificat configuré | Démarre | Scellé avec votre certificat, propre (watermarked: false) | Propre |
Licence payante accordant Signer, aucun certificat | Démarre | Refusé : No signing certificate configured. | Propre |
| Licence payante, certificat expiré ou pas encore valide | Démarre (avec le widget activé, un avertissement est enregistré) | Refusé : The signing certificate expired on yyyy-MM-dd. | Propre |
| Licence Démo/NFR temporaire, active ou expirée | Démarre | Scellé avec le certificat de démonstration intégré, filigrané (watermarked: true) | Filigrané |
Pas de licence, un fichier legacy TRIAL, une licence sans Signer, ou une licence payante hors de sa fenêtre de version | AddDoconut() lève une exception | — | — |
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 est temporaire. Sous 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 AddDoconut() et résolu via l'injection de dépendances. Son constructeur est interne, donc ne jamais new le. Le résoudre sans AddPlugin<SignerPlugin>() lance No IDocumentSigner is registered. Add the signing plugin: options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>().
using Doconut;
using Doconut.Core.Models.Signing;
public sealed class ContractSigning
{
private readonly DocumentSigner _signer;
public ContractSigning(DocumentSigner signer) => _signer = signer;
public async Task<byte[]> SignAsync(Stream pdf, byte[] signaturePng, SigningCertificate certificate, CancellationToken ct)
{
var request = new SignRequest(
new VisibleSignature(SignatureKind.Drawn, signaturePng),
new SignaturePlacement(Page: 1, X: 0.58, Y: 0.80, W: 0.32, H: 0.12),
SignerName: "Ada Lovelace",
Reason: "I approve this document",
Location: "London, UK");
// Le mode est par défaut Certified (signature visible + sceau numérique); WordOutput est 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, 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. Transmettez 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é.
Une signature Visuelle appose uniquement l'image et ne nécessite aucun certificat :
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);Une source Word est signée en PDF sauf si vous demandez une sortie Word. Nommez le résultat provenant de result.Extension :
var signer = app.Services.GetRequiredService<DocumentSigner>();
byte[] signaturePng = File.ReadAllBytes("signature.png");
var request = new SignRequest(
new VisibleSignature(SignatureKind.Drawn, signaturePng),
new SignaturePlacement(Page: 1, X: 0.58, Y: 0.80, W: 0.32, H: 0.12),
WordOutput: WordOutput.Docx);
SignResult result = await signer.SignAsync(stream, ".docx", request, ct: ct);
string downloadName = "contract-signed" + result.Extension; // ".docx"SignAsync lance une exception au lieu de retourner lorsque l'appel ne peut pas réussir :
| Exception | Message | Quand |
|---|---|---|
InvalidOperationException | No signing certificate configured. | Mode certifié, une licence payante, et aucun certificat fourni |
InvalidOperationException | The 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é |
ArgumentException | The sign request is invalid: the visible signature needs PNG bytes and the placement must be a normalized rectangle on a 1-based page. | Octets PNG vides, ou un placement non valide |
NotSupportedException | The 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 détermine si la signature est scellée.
| Mode | Ce qu'il produit | Certificat | Vérifiable |
|---|---|---|---|
SignatureMode.Certified (default) | La signature visible plus un sceau numérique | Requis avec une licence payante | Oui |
SignatureMode.Visual | La signature visible uniquement | Jamais nécessaire | Non : c'est une image |
Utilisez Certified lorsque la signature doit être vérifiable : approbations, contrats, tout ce qu'un vérificateur doit contrôler 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 aucun 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 émetteurs présents dans votre PFX, de sorte qu'un lecteur qui fait confiance à votre racine puisse construire la chaîne. Les sceaux natifs Word sont des signatures de paquet OOXML et ne transportent 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.
| Sortie | Ce qui se passe | Support du vérificateur |
|---|---|---|
WordOutput.Pdf (par défaut) | Le document est converti en PDF, puis signé et scellé | Large : un PDF signé est vérifié partout |
WordOutput.Docx | Le document reste au format Word : l'image de la signature y est placée, ainsi qu'une signature de paquet OOXML | Limité : tous les visionneurs n'affichent pas les signatures de paquet OOXML |
Conservez le PDF sauf si le destinataire a besoin d'un fichier Word modifiable 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) contenant 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, ainsi que le mot de passe :
builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
options.AddSignerWidget(widget =>
{
widget.SigningCertificate = new SigningCertificate
{
PfxBytes = File.ReadAllBytes("/secure/signing.pfx"),
Password = builder.Configuration["Signing:PfxPassword"],
};
});
});builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
options.AddSignerWidget(widget =>
{
widget.SigningCertificate = new SigningCertificate
{
PfxPath = "/secure/signing.pfx",
Password = builder.Configuration["Signing:PfxPassword"],
};
});
});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 une ligne de journal ou un message d'erreur.
Exigences :
- Un bundle PFX / PKCS#12 avec sa clé privée. Un fichier ne contenant que la clé publique (
.cer,.crt) ne peut pas signer. Exportez la chaîne de l'émetteur avec celui‑ci, 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 : il est journalisé comme un Avertissement au démarrage, et les signatures Certifiées sont refusées jusqu'à son remplacement. Les signatures Visuelles ne sont pas affectées.
- Émis pour la signature de documents : une utilisation de clé avec signature numérique ou non‑répudiation, 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 serveur TLS, signe quand même, mais il est journalisé comme un Avertissement et 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 :
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 All Tasks → Export…, sélectionnez Yes, export the private key, choisissez Personal Information Exchange – PKCS #12 (.PFX), et définissez un mot de passe.
Vérifications au démarrage
Lorsque le widget est activé, le certificat dans SignerWidgetOptions.SigningCertificate est vérifié une fois, à l'intérieur de AddDoconut(), de sorte qu'un PFX mal configuré échoue au démarrage plutôt qu'à la première signature. Trois problèmes génèrent un InvalidOperationException :
| Message | Correction |
|---|---|
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 de l'application |
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, et non un .cer ou un .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 |
Sinon, l'hôte écrit une ligne dans le journal au démarrage. Informations lorsque le certificat est prêt :
Doconut Signer: using certificate '{subject}' (valid until yyyy-MM-dd). Signatures are digitally sealed.Un Avertissement lorsqu'il est expiré, pas encore valide, ou non émis pour la signature de documents :
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.Et Informations lorsqu'aucun certificat n'est configuré :
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.Cette dernière ligne est identique sous toutes les licences. Sous une licence payante, le certificat de démonstration n'est jamais utilisé : sans certificat, seules les signatures Visuelles fonctionnent.
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, ainsi un chemin ou un mot de passe incorrect entraîne l'échec de cet appel.
Widget intégrable
Activer les points de terminaison
Les points de terminaison ?sign=open|run|download du widget sont désactivés par défaut. Activez‑les à côté de l'enregistrement du plugin :
builder.Services.AddDoconut(options =>
{
options.LicensePath = "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 ; laissez‑le null pour une signature de démonstration (filigrane)
});
});AddSignerWidget() sans argument active le widget avec les valeurs par défaut. Il ne permet pas la signature par lui‑même : il nécessite AddPlugin<SignerPlugin>(), ou AddDoconut() lève une exception :
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.Message d’erreur : « La signature n’est pas activée sur ce serveur. »
Sans AddSignerWidget(), chaque requête ?sign= répond 404. Le script lui‑même est toujours servi, ainsi le widget se charge et dessine sa zone de dépôt, puis signale Signing is not enabled on this server. lors de sa première requête.
Intégrer le widget
UseDoconutResources() fournit le script à {ResourcesPath}/js/doconutSigner.js (par défaut /doconut-res/js/doconutSigner.js). C’est un fichier unique, autonome, sans dépendances :
<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) accepte un sélecteur CSS ou un élément, lève une exception si le point de montage n’est pas trouvé, et renvoie une poignée.
Le signataire téléverse un fichier PDF ou .docx, crée une signature (Dessiner sur un canvas, Taper un nom dans une police de signature, ou Image depuis 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
| Option | Type | Par défaut | Remarques |
|---|---|---|---|
basePath | string | '/doconut' | Où les points de terminaison ?sign= et les images d’aperçu sont servis |
resPath | string | '/doconut-res' | Réservé ; le widget intègre son propre CSS |
maxUploadMb | number | 25 | Vérification côté client uniquement, ainsi un fichier trop volumineux échoue rapidement. La limite serveur est MaxUploadMb en AddSignerWidget |
maxSignatureKb | number | 512 | Limite côté client pour le mode Image. Gardez‑la égale à MaxSignatureImageKb du serveur |
previewWidth | number | 560 | Largeur en pixels de l’aperçu de la page |
licenseUrl | string | null | null | Transforme l’avertissement de filigrane de démonstration en un lien vers cette URL |
signatureMode | string | 'certified' | Type de signature initial : 'certified' ou 'visual'. Toute autre valeur devient 'certified' |
showSignatureModeToggle | boolean | true | Affiche le choix Signature numérique / Visuel uniquement. Avec false, le widget signe avec signatureMode |
wordOutput | string | 'pdf' | Sortie initiale pour les sources .docx : 'pdf' ou 'docx'. Toute autre valeur devient 'pdf' |
showOutputFormatToggle | boolean | true | Affiche le choix PDF / Word, uniquement pour les sources .docx. Avec false, le widget utilise wordOutput |
labels | object | {} | Remplace tout sous‑ensemble des chaînes anglaises |
Masquer un commutateur ne désactive pas la fonctionnalité ; cela fixe la valeur. Deux configurations courantes :
// Les deux bascules affichées, signature numérique par défaut : un signataire en libre‑service complet.
Doconut.signer('#host', { basePath: '/doconut', licenseUrl: '/pricing' });// Visuel uniquement, aucune bascule : un simple tampon sans signature numérique proposée.
Doconut.signer('#host', {
basePath: '/doconut',
signatureMode: 'visual',
showSignatureModeToggle: false
});Rappels
| Rappel | Se déclenche quand | Charge utile |
|---|---|---|
onReady | Une fois, à l'initialisation (pas de nouveau sur reset()) | — |
onSourceLoaded | Le fichier est ouvert et son aperçu affiché | { file: { token, name, pages, ext } } |
onSigned | La signature réussit | { downloadToken, downloadName, watermarked } |
onDownload | À chaque clic sur Télécharger | { downloadName, downloadToken } |
onError | Une é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 perturbe jamais le flux du widget.
Gestion impérative
| Méthode | Comportement |
|---|---|
reset() | Retourne à l'écran de dépôt et efface 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 se trouve sur son écran de dépôt ; appelez reset() d'abord si nécessaire |
destroy() | Supprime les écouteurs, vide le montage et gèle l'instance |
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());É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 |
|---|---|
dropPrompt | Drag & drop a PDF or Word file here |
dropHint | PDF or Word (.docx) |
chooseFile | Choose file |
signatureHeading | Your signature |
modeDraw / modeType / modeImage | Draw / Type / Image |
metaSummary | Signature details (optional) |
metaSignerName / metaReason / metaLocation | Signer name / Reason / Location |
signatureType | Signature type |
modeCertified / modeVisual | Digital signature / Visual only |
modeVisualNote | No certificate — a visible mark only, not cryptographically verifiable. |
outputFormat | Output format |
outputPdf / outputWord | PDF / Word (.docx) |
signAction | Sign document |
download | Download |
demoNotice | Demo — signed with the Doconut demo certificate; output is watermarked. |
signingNotEnabled | Signing is not enabled on this server. |
page / pages | 1 page / {n} pages |
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 comme un téléchargement expiré restent visibles.
Thématisation
Le widget ajoute la classe dsw à son élément de montage et lit ses couleurs, rayon et polices à partir des propriétés personnalisées CSS, ainsi vous pouvez le thématiser sans toucher à ses internes :
#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.
Construisez votre propre interface
Le widget est un client pour ce contrat HTTP. Les trois routes se trouvent sous le chemin où UseDoconut() est monté (normalement /doconut), et elles 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 inconnue de ?sign= répond 400.
| Route | Objectif | Réponse réussie |
|---|---|---|
POST ?sign=open (multipart, un fichier) | Téléverser un PDF ou .docx et l'ouvrir en aperçu | 200 — { token, name, pages, ext } |
POST ?sign=run (corps JSON) | Signer le fichier téléversé | 200 — { downloadToken, downloadName, watermarked } |
GET ?sign=download&token=<downloadToken> | Diffuser 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 la page utilise la route d'image du visualiseur standard, {basePath}?token={token}&page={n}&thumb=1&width={px} ; la page affichée devient placement.page.
Le corps run :
{
"token": "GUID-from-open",
"signature": { "kind": "Drawn", "payload": "<base64 PNG, no data: prefix>" },
"placement": { "page": 1, "x": 0.58, "y": 0.80, "w": 0.32, "h": 0.12 },
"meta": { "signerName": "Ada Lovelace", "reason": "I approve", "location": "London, UK" },
"wordOutput": "pdf",
"mode": "certified"
}| Champ | Notes |
|---|---|
token | Le jeton provenant de open |
signature.kind | Drawn, Typed ou Image, insensible à la casse ; tout autre devient Drawn. Un indice seulement : la charge utile est toujours un PNG |
signature.payload | Un PNG base64 brut, sans préfixe data:. Il doit s'agir d'un vrai PNG et ne pas dépasser MaxSignatureImageKb une fois décodé |
placement.page | Indexé à 1 |
placement.x / y / w / h | 0..1 normalisé depuis le coin supérieur gauche, avec x + w ≤ 1 et y + h ≤ 1 |
meta.signerName / reason / location | Facultatif. Chaque valeur est tronquée, une valeur vide est ignorée, et chaque valeur est coupée à 256 caractères |
wordOutput | pdf (par défaut) ou docx ; ignoré pour les sources PDF. Tout autre devient pdf |
mode | certified (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.
| Route | Statut | Quand | Corps |
|---|---|---|---|
| any | 404 | Le widget n'est pas activé | statut uniquement |
| any | 405 | Verbe incorrect (open et run nécessitent POST, download nécessite GET) | statut uniquement |
open | 400 | Pas un téléversement multipart | Expected a multipart file upload. |
open | 400 | Pas de fichier, ou un fichier vide | No file uploaded. |
open | 400 | Tout autre que .pdf ou .docx | Signing supports PDF and Word (.docx) files only. |
open | 413 | Le téléversement dépasse MaxUploadMb | File is too large. |
run | 400 | Le corps n'est pas un JSON valide, ou est vide | Malformed request. / Empty request. |
run | 400 | Le jeton est manquant ou n'est pas un GUID | Invalid token. |
run | 404 | Le téléversement a expiré ou n'a jamais été ouvert | Upload expired — please re-open the file. |
run | 400 | Pas de signature, ou aucun placement | No signature supplied. / No placement supplied. |
run | 400 | La charge utile n'est pas en base64, est vide, trop grande, ou n'est pas un PNG | Signature image is not valid base64. / Signature image is empty. / Signature image is too large. / The signature image must be a PNG. |
run | 400 | Le placement est en dehors de la page | The signature or its placement is invalid. |
run | 400 | Mode certifié, une licence payante et aucun certificat | No signing certificate configured. |
run | 400 | Mode 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, run | 500 | Traitement échoué | Un message assaini |
download | 400 | Le jeton est manquant ou n'est pas un GUID | statut uniquement |
download | 404 | Jeton inconnu ou expiré | statut uniquement |
Un aller-retour complet avec fetch :
// file: le fichier à signer; pngBase64: la signature sous forme de PNG base64 brut, sans préfixe data:,
// par exemple canvas.toDataURL('image/png').split(',')[1].
async function signFile(file, pngBase64) {
const base = '/doconut';
// 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 Doconut, ou effectuez un reverse‑proxy des deux chemins /doconut (le chemin du middleware et le chemin des ressources) sous l’origine de votre UI.
En production
-
Installez le plugin à côté du paquet principal, à la même version :
dotnet add package Doconut.NET6.Signer. -
Ajoutez le fichier de licence. Placez
Doconut.Viewer.Signer.licdans le même dossier queDoconut.Viewer.lic. -
Obtenez votre certificat au format PFX avec sa clé privée et sa chaîne d’émission, auprès d’une autorité de certification ou de la PKI 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é.
-
Lisez le certificat depuis la configuration, afin que le modifier ne nécessite jamais de changement de code :
json"DoconutSigner": { "PfxPath": "certs/your-certificate.pfx" }csharpvar signerSettings = builder.Configuration.GetSection("DoconutSigner"); builder.Services.AddDoconut(options => { options.LicensePath = "Doconut.Viewer.lic"; options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>(); options.AddSignerWidget(widget => widget.SigningCertificate = new SigningCertificate { PfxPath = Path.Combine(builder.Environment.ContentRootPath, signerSettings["PfxPath"]), Password = signerSettings["Password"] ?? "", }); });Conservez le
.pfxà l’extérieur dewwwroot, et gardez le mot de passe hors deappsettings.json: secrets utilisateur en développement (dotnet user-secrets set "DoconutSigner:Password" "<password>"), une variable d’environnement (DoconutSigner__Password) ou un coffre‑fort en production. -
Vérifiez le journal de démarrage. Il devrait lire
using certificate '{subject}' (valid until …). Signatures are digitally sealed.. Un avertissement indique que le certificat est expiré, pas encore valide, ou n’est pas délivré pour la signature de documents.
Confiance dans les lecteurs PDF. Un lecteur affiche la signature comme 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 nœud qui a servi open. Derrière un équilibreur de charge sans sessions persistantes, une requête run, download ou de prévisualisation ultérieure peut atteindre un autre nœud et ne pas trouver le téléchargement. Enregistrez le magasin de widget partagé et chiffré une seule fois, après AddDoconut() :
byte[] farmKey = Convert.FromBase64String(builder.Configuration["Doconut:FarmKey"]);
builder.Services.AddDoconutDistributedWidgets(store =>
{
store.RootPath = @"\\fileshare\doconut"; // un dossier que chaque nœud peut lire et écrire
store.FarmKey = farmKey; // au moins 32 octets, identique sur chaque nœud
// store.Ttl = TimeSpan.FromMinutes(30); // pendant combien de temps un téléversement 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.
FarmKeydoit être d'au moins 32 octets et identique sur chaque nœud. Chargez‑le depuis un magasin de secrets ; ne le codez jamais en dur. L'enregistrement génère uneArgumentExceptionlorsqueRootPathest manquant ou queFarmKeyfait moins de 32 octets.- Pointez
RootPathvers le même emplacement partagé utilisé par le visualiseur distribué, et fournissez à chaque nœud 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
public sealed class DocumentSigner
{
public Task<SignResult> SignAsync(
Stream source, string sourceExtension, SignRequest request,
SigningCertificate? cert = null, CancellationToken ct = default);
}Résolu par injection de dépendances ; 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 porte un filigrane.
SignRequest
public sealed record SignRequest(
VisibleSignature Signature,
SignaturePlacement Placement,
string? SignerName = null,
string? Reason = null,
string? Location = null,
WordOutput WordOutput = WordOutput.Pdf,
SignatureMode Mode = SignatureMode.Certified)
{
public bool IsValid { get; } // Signature.IsValid && Placement.IsValid
}Une signature visible placée une fois, plus des métadonnées facultatives du signataire.
VisibleSignature et SignatureKind
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éversée conserve la transparence qu'elle avait, ainsi un JPG opaque reste opaque. Kind n'est qu'une indication.
SignaturePlacement
public readonly record struct SignaturePlacement(int Page, double X, double Y, double W, double H)
{
public bool IsValid { get; } // Page >= 1; X, Y >= 0; W, H > 0; X + W <= 1; Y + H <= 1
}Page est indexé à partir de 1 ; X, Y, W et H sont des 0..1 normalisés depuis le coin supérieur gauche.
SignatureMode et WordOutput
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 PDFSignResult
public sealed record SignResult(Stream Stream, string Extension);Le document signé sous forme de flux consultable, et son extension avec le point (".pdf" ou ".docx").
SigningCertificate
public sealed class SigningCertificate
{
public byte[]? PfxBytes { get; init; }
public string? PfxPath { get; init; }
public string Password { get; init; } = "";
public bool HasMaterial { get; } // PfxBytes n'est pas vide, ou PfxPath n'est pas vide
}Définissez soit PfxBytes, soit PfxPath, ainsi que Password.
SignerWidgetOptions
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 chaînés. Un SigningCertificate nul signifie le certificat de démonstration sous une licence temporaire, et les signatures Visuelles uniquement sous une licence payante.
Dépannage
| Symptôme | Cause | Solution |
|---|---|---|
AddDoconut() lance 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 version | Installez une licence qui accorde Signer, ou supprimez AddPlugin<SignerPlugin>() |
AddDoconut() lance AddSignerWidget() was called but the Signer plugin is not registered. | Le widget est activé sans son plugin | Ajoutez options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>() |
AddDoconut() lance Doconut Signer: the certificate file was not found at '{path}'. | PfxPath pointe vers un fichier manquant | Corrigez le chemin ; déployez le fichier à un endroit où le compte de l'application peut le lire |
AddDoconut() lance 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#12 | Vérifiez le mot de passe ; utilisez un vrai .pfx |
AddDoconut() lance 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ée | Exportez-le à nouveau avec la clé privée |
La résolution de DocumentSigner lance No IDocumentSigner is registered. | SignerPlugin n'est pas enregistré | Ajoutez AddPlugin<SignerPlugin>() à l'intérieur de AddDoconut() |
| La sortie porte un filigrane | La licence est temporaire (Démo/NFR) | Utilisez une licence payante qui accorde Signer |
run répond 400 No signing certificate configured. | Une licence payante, le mode Certifié, et aucun certificat | Configurez SigningCertificate, ou signez en mode Visuel |
run répond 400 The signing certificate expired on yyyy-MM-dd. | Le certificat est périmé | Remplacez-le ; les signatures Visuelles continuent de fonctionner en attendant |
| Le journal indique que la sortie "utilise le certificat de démonstration intégré", pourtant une licence payante refuse les signatures Certifiées | Cette ligne est écrite chaque fois qu'aucun certificat n'est configuré, quelle que soit la licence | Configurez SigningCertificate |
Le widget se charge mais indique Signing is not enabled on this server. | AddSignerWidget() n'a pas été appelé, ou basePath ne correspond pas à l'endroit où UseDoconut() est monté | Appelez AddSignerWidget() ; corrigez basePath |
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 MaxSignatureImageKb | Envoyez un PNG base64 brut dans la capacité |
open répond 413 File is too large. | Le téléversement dépasse MaxUploadMb | Augmentez 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 nœud du web-farm n'a pas le téléversement | Rouvrez le fichier ; dans un farm, enregistrez AddDoconutDistributedWidgets |
Un .docx signé n'affiche aucune signature dans certains visionneurs | La sortie Word contient une signature de paquet OOXML, que de nombreux visionneurs n'affichent pas | Signez en PDF, par défaut |
| Les lecteurs PDF indiquent que l'identité du signataire est inconnue | Le lecteur ne fait pas confiance à la racine du certificat (le certificat de démonstration n'est jamais fiable) | Utilisez un certificat provenant d'une autorité racine fiable par vos lecteurs |
| Le widget échoue lorsque l'UI se trouve sur une autre origine | Les points de terminaison n'ont pas de support CORS | Servez l'UI depuis la même origine, ou utilisez un reverse-proxy sur les chemins Doconut |
| Le thème ne s'applique pas | Le sélecteur cible un élément à l'intérieur du montage | Ciblez le montage lui-même : #host.dsw ou #host |
Cette page était-elle utile ?