Signer-Plugin
PDF- und Word-Dokumente mit einer sichtbaren Signatur und einem digitalen Siegel signieren
Das Signer-Plugin fügt einem Dokument eine sichtbare Signatur hinzu und versieht es standardmäßig mit einer digitalen Signatur, die ein PDF‑Reader verifizieren kann. Es signiert PDF‑ und Word (.docx)‑Dateien. Die sichtbare Signatur ist immer ein PNG‑Bild: gezeichnet, getippt oder vom Unterzeichner hochgeladen.
| Oberfläche | Verwendung |
|---|---|
DocumentSigner (C#) | Sie signieren auf dem Server, ohne dass ein Browser beteiligt ist |
Drop-in widget (doconutSigner.js) | Sie möchten einen fertigen Upload-, Signatur- und Download‑Bildschirm in Ihrer Seite |
HTTP endpoints (?sign=open|run|download) | Sie bauen Ihre eigene Signatur‑UI gegen einen dokumentierten Server‑Vertrag |
Jede Signatur wird einmal, auf einer Seite, platziert. Der Name des Unterzeichners, der Grund und der Ort können mit ihr übertragen werden.
Paket installieren
Installieren Sie das neueste stabile Signer-Plugin:
dotnet add package Doconut.NET8.SignerUm das Plugin an die in dieser Dokumentation beschriebene Version zu binden, übergeben Sie die Version separat:
dotnet add package Doconut.NET8.Signer --version 26.10.0Halten Sie das Signer-Paket in derselben Version wie Doconut.NET8. Die Paket‑ID ist Doconut.NET8.Signer; .<version> erscheint nur im heruntergeladenen .nupkg Dateinamen.
Die Lizenzdatei des Plugins, Doconut.Viewer.Signer.lic, wird im selben Ordner wie Doconut.Viewer.lic abgelegt; sie wird zusammen mit der Viewer‑Lizenz gelesen.
Plattformen. Das Plugin läuft überall dort, wo Doconut.NET8 läuft: Windows und auf glibc‑basiertem Linux auf x64 (nicht Alpine oder andere musl‑basierte Distributionen). Unter Linux installieren Sie die Font‑Konfigurationsbibliothek, bevor das erste Dokument geöffnet wird:
apt-get update && apt-get install -y libfontconfig1Unter RHEL, Fedora und ähnlichen Distributionen ist das Paket fontconfig. Ohne dieses schlägt das Öffnen eines Dokuments mit The system library libfontconfig1 is missing. Install it (Debian/Ubuntu: apt-get install -y libfontconfig1) and see the Linux section of the Doconut documentation. fehl.
Plugin registrieren
Wie jedes Doconut-Plugin registriert sich Signer bei AddPlugin<TPlugin>() innerhalb von AddDoconut():
builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
});Das ist alles, was die C#‑Fassade benötigt. Das Widget und seine HTTP‑Endpunkte sind ein separater Opt‑In, AddSignerWidget() (siehe Drop-in-Widget).
Das Plugin benötigt eine Lizenz, die die Signer‑Funktionalität gewährt. Ohne diese wirft AddDoconut() beim Starten, bevor die Anwendung eine Anfrage bedient, eine Ausnahme:
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.Es wirft bei fehlender Lizenz, einer veralteten TRIAL‑Datei, einer Lizenz ohne Signer und einer kostenpflichtigen Lizenz, die außerhalb ihres Versionsfensters verwendet wird. Temporäre Demo/NFR‑Lizenzen werden akzeptiert. Siehe Lizenzsetup für das Laden von Lizenzen.
Lizenzierung & Wasserzeichen
| Lizenzstatus | Start | Zertifizierte Signatur | Visuelle Signatur |
|---|---|---|---|
Kostenpflichtige Lizenz, die Signer gewährt, Zertifikat konfiguriert | Startet | Versiegelt mit Ihrem Zertifikat, sauber (watermarked: false) | Sauber |
Kostenpflichtige Lizenz, die Signer gewährt, kein Zertifikat | Startet | Abgelehnt: No signing certificate configured. | Sauber |
| Kostenpflichtige Lizenz, Zertifikat abgelaufen oder noch nicht gültig | Startet (mit aktiviertem Widget, eine Warnung wird protokolliert) | Abgelehnt: The signing certificate expired on yyyy-MM-dd. | Sauber |
| Temporäre Demo/NFR‑Lizenz, aktiv oder abgelaufen | Startet | Versiegelt mit dem integrierten Demo‑Zertifikat, mit Wasserzeichen (watermarked: true) | Mit Wasserzeichen |
Keine Lizenz, eine veraltete TRIAL‑Datei, eine Lizenz ohne Signer oder eine kostenpflichtige Lizenz außerhalb ihres Versionsfensters | AddDoconut() wirft | — | — |
Die Regel ist für die C#‑Fassade und das Widget identisch: Die Ausgabe wird mit einem Wasserzeichen versehen, wenn die Lizenz keine kostenpflichtige Viewer‑Lizenz ist oder temporär ist. Unter einer temporären Lizenz signiert das Plugin stets mit seinem integrierten Demo‑Zertifikat, und jedes von Ihnen konfigurierte Zertifikat wird nicht verwendet.
Das Demo‑Zertifikat erzeugt ein echtes Siegel, aber PDF‑Reader vertrauen ihm nicht. Eine Integration kann end‑to‑end mit einer Evaluationslizenz aufgebaut und getestet werden; um saubere, vertrauenswürdige Ausgaben zu erhalten, benötigen Sie sowohl eine kostenpflichtige Lizenz als auch Ihr eigenes Signaturzertifikat.
Verwendung aus C#
DocumentSigner wird von AddDoconut() registriert und über Dependency Injection aufgelöst. Sein Konstruktor ist internal, also niemals new es. Das Auflösen ohne AddPlugin<SignerPlugin>() wirft 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");
// Mode ist standardmäßig Certified (sichtbare Signatur + digitales Siegel); WordOutput ist standardmäßig 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 nimmt den Quell‑Stream, seine Erweiterung (".pdf" oder ".docx"), die Anfrage und das Zertifikat für diesen Aufruf. Die Fassade liest SignerWidgetOptions.SigningCertificate nicht; diese Einstellung ist für das Widget. Übergeben Sie null unter einer Demo‑Lizenz oder im Visual‑Modus.
SignResult hält das signierte Dokument als seekbaren Stream, plus sein Extension (".pdf" oder ".docx"), sodass Sie die Datei benennen können. Sie besitzen den Stream: Entsorgen Sie ihn, wenn Sie fertig sind.
Eine Visual‑Signatur stempelt nur das Bild und benötigt kein Zertifikat:
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);Eine Word‑Quelle wird zu PDF signiert, es sei denn, Sie verlangen Word‑Ausgabe. Benennen Sie das Ergebnis von 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 wirft eine Ausnahme, anstatt zurückzugeben, wenn der Aufruf nicht erfolgreich sein kann:
| Ausnahme | Nachricht | Wann |
|---|---|---|
InvalidOperationException | No signing certificate configured. | Zertifizierter Modus, eine bezahlte Lizenz und kein Zertifikat übergeben |
InvalidOperationException | The signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd. | Zertifizierter Modus mit einem Zertifikat außerhalb seines Gültigkeitszeitraums |
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. | Leere PNG‑Bytes oder eine Platzierung, die nicht gültig ist |
NotSupportedException | The signer supports PDF and Word (.docx) documents; got '{extension}'. | Beliebiger anderer Quelltyp |
Signaturmodi, Word‑Ausgabe und Zertifikate
Signaturmodi
SignRequest.Mode bestimmt, ob die Signatur versiegelt ist.
| Modus | Was es erzeugt | Zertifikat | Verifizierbar |
|---|---|---|---|
SignatureMode.Certified (default) | Die sichtbare Signatur plus ein digitales Siegel | Erforderlich bei einer bezahlten Lizenz | Ja |
SignatureMode.Visual | Nur die sichtbare Signatur | Niemals benötigt | Nein: es ist ein Bild |
Verwenden Sie Certified, wenn die Signatur nachweisbar sein muss: Genehmigungen, Verträge, alles, was ein Prüfer zur Überprüfung von Identität und Integrität benötigt. Verwenden Sie Visual, wenn Sie nur das Aussehen einer Signatur benötigen oder kein Zertifikat haben. Eine temporäre Lizenz versieht beide mit einem Wasserzeichen.
PDF‑Siegel sind PKCS#7‑abgetrennte Signaturen (adbe.pkcs7.detached) mit SHA‑256, für RSA‑ oder ECDSA‑Schlüssel. Sie enthalten die Aussteller‑Zertifikate aus Ihrem PFX, sodass ein Leser, der Ihrer Stammzertifizierungsstelle vertraut, die Kette aufbauen kann. Word‑native Siegel sind OOXML‑Paket‑Signaturen und enthalten nur das Signatur‑Zertifikat.
Word-Dokumente
Für eine .docx-Quelle wählt SignRequest.WordOutput die Ausgabe. Sie wird bei PDF-Quellen ignoriert, die immer ein PDF erzeugen.
| Ausgabe | Was passiert | Unterstützung des Verifiers |
|---|---|---|
WordOutput.Pdf (default) | Das Dokument wird in PDF konvertiert, dann signiert und versiegelt | Breit: ein signiertes PDF wird überall verifiziert |
WordOutput.Docx | Das Dokument bleibt Word: das Signaturbild wird eingefügt, plus eine OOXML-Paket‑Signatur | Eingeschränkt: nicht jeder Viewer zeigt OOXML-Paket‑Signaturen an |
Behalte PDF, es sei denn, der Empfänger benötigt eine editierbare Word‑Datei und akzeptiert die eingeschränkte Verifier‑Unterstützung.
Zertifikatseinrichtung
Um mit Ihrer eigenen Identität zu versiegeln, geben Sie dem Plugin eine PFX (PKCS#12)‑Datei, die den privaten Schlüssel enthält. Für das Widget setzen Sie SignerWidgetOptions.SigningCertificate; für die C#‑Fassade übergeben Sie das Zertifikat an SignAsync. Geben Sie entweder die Bytes oder einen Pfad an, plus das Passwort:
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"],
};
});
});Das Zertifikat wird nur im Speicher gehalten. Es wird nie protokolliert, an einen Client zurückgegeben oder dauerhaft gespeichert, und das Passwort erscheint nie in einer Protokollzeile oder Fehlermeldung.
Anforderungen:
- Ein PFX / PKCS#12‑Paket mit seinem privaten Schlüssel. Eine Datei, die nur den öffentlichen Schlüssel enthält (
.cer,.crt), kann nicht signieren. Exportieren Sie die Ausstellerkette mit, damit PDF‑Siegel sie tragen können. - Das korrekte Passwort.
- Innerhalb seines Gültigkeitszeitraums. Ein abgelaufenes oder noch nicht gültiges Zertifikat stoppt die Anwendung nicht: Es wird beim Start als Warnung protokolliert, und zertifizierte Signaturen werden abgelehnt, bis es ersetzt wird. Visuelle Signaturen bleiben unverändert.
- Für Dokumentensignatur ausgestellt: eine Schlüsselverwendung mit digital signature oder non-repudiation und, falls vorhanden, einer erweiterten Schlüsselverwendung, die Dokumentensignatur, E‑Mail‑Schutz oder Client‑Authentifizierung erlaubt. Ein Zertifikat, das für etwas anderes ausgestellt wurde, z. B. ein TLS‑Serverzertifikat, signiert zwar, wird aber als Warnung protokolliert und PDF‑Reader markieren die Signatur.
- Hardware‑Token, Smartcards, HSMs und der Windows‑Zertifikatspeicher werden nicht unterstützt. Exportieren Sie das Zertifikat mit seinem privaten Schlüssel und der Kette in ein PFX.
Erstellen Sie ein PFX aus einem Zertifikat und seinem privaten Schlüssel mit OpenSSL:
openssl pkcs12 -export -out signing.pfx -inkey private.key -in certificate.crt
# Das Export-Passwort, nach dem Sie gefragt werden, ist SigningCertificate.Password.Exportieren Sie eines aus dem Windows‑Zertifikatspeicher: Öffnen Sie certmgr.msc und finden Sie das Zertifikat (sein Symbol zeigt einen Schlüssel, wenn der private Schlüssel vorhanden ist). Rechtsklicken Sie darauf, wählen Sie Alle Aufgaben → Exportieren…, wählen Sie Ja, privaten Schlüssel exportieren, wählen Sie Personal Information Exchange – PKCS #12 (.PFX) und setzen Sie ein Passwort.
Start‑Checks
Wenn das Widget aktiviert ist, wird das Zertifikat in SignerWidgetOptions.SigningCertificate einmal geprüft, innerhalb von AddDoconut(), sodass ein falsch konfiguriertes PFX beim Start fehlschlägt und nicht erst bei der ersten Signatur. Drei Probleme werfen ein InvalidOperationException:
| Nachricht | Lösung |
|---|---|
Doconut Signer: the certificate file was not found at '{path}'. | Korrigieren Sie PfxPath; stellen Sie sicher, dass die Datei bereitgestellt und vom Konto der Anwendung lesbar ist |
Doconut Signer: the signing certificate could not be opened — the password is incorrect or the file is not a valid .pfx. | Überprüfen Sie das Passwort; stellen Sie sicher, dass die Datei ein echtes .pfx ist, nicht ein .cer oder .pem |
Doconut Signer: the signing certificate has no private key. Re-export the .pfx INCLUDING the private key. | Exportieren Sie das PFX erneut mit dem privaten Schlüssel |
Andernfalls schreibt der Host beim Start eine Zeile ins Protokoll. Information, wenn das Zertifikat bereit ist:
Doconut Signer: using certificate '{subject}' (valid until yyyy-MM-dd). Signatures are digitally sealed.Eine Warnung, wenn es abgelaufen, noch nicht gültig oder nicht für Dokumentensignatur ausgestellt ist:
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.Und Information, wenn kein Zertifikat konfiguriert ist:
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.Diese letzte Zeile ist bei jeder Lizenz gleich. Bei einer kostenpflichtigen Lizenz wird das Demo‑Zertifikat nie verwendet: Ohne Zertifikat funktionieren nur visuelle Signaturen.
Die C#‑Fassade wird beim Start nicht geprüft. Das Zertifikat, das Sie an SignAsync übergeben, wird beim Signieren gelesen, sodass ein falscher Pfad oder ein falsches Passwort diesen Aufruf fehlschlagen lässt.
Drop-in-Widget
Endpunkte aktivieren
Die ?sign=open|run|download-Endpunkte des Widgets sind standardmäßig deaktiviert. Aktivieren Sie sie neben der Plugin-Registrierung:
builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
options.AddSignerWidget(widget =>
{
widget.MaxUploadMb = 25; // der Standard
widget.MaxSignatureImageKb = 512; // der Standard
// widget.SigningCertificate: siehe Zertifikatseinrichtung; lassen Sie es null für Demo (mit Wasserzeichen) Signatur
});
});AddSignerWidget() ohne Argument aktiviert das Widget mit den Standardwerten. Es gewährt nicht von selbst das Signieren: es benötigt AddPlugin<SignerPlugin>(), oder AddDoconut() wirft:
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.Signieren ist auf diesem Server nicht aktiviert.
Ohne AddSignerWidget() beantwortet jede ?sign=-Anfrage 404. Das Skript selbst wird weiterhin bereitgestellt, sodass das Widget lädt und seine Drop‑Zone zeichnet, dann bei seiner ersten Anfrage Signing is not enabled on this server. meldet.
Einbetten
UseDoconutResources() liefert das Skript unter {ResourcesPath}/js/doconutSigner.js (Standard /doconut-res/js/doconutSigner.js). Es ist eine einzelne, eigenständige Datei ohne Abhängigkeiten:
<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) nimmt einen CSS-Selektor oder ein Element, wirft, wenn das Mount nicht gefunden wird, und gibt einen Handle zurück.
Der Unterzeichner lädt eine PDF- oder .docx-Datei hoch, erstellt eine Signatur (Draw auf einer Leinwand, Type einen Namen in einer Signatur-Schriftart oder Image aus einem PNG, JPG oder GIF), zieht sie auf die Seite, ändert ihre Größe und signiert und lädt das Ergebnis herunter. Das Widget sendet die Signatur immer als PNG; ein hochgeladenes Bild wird im Browser in ein PNG konvertiert, das 520×160 passt.
Optionen
| Option | Typ | Standard | Hinweise |
|---|---|---|---|
basePath | string | '/doconut' | Wo die ?sign=-Endpunkte und Vorschaubilder bereitgestellt werden |
resPath | string | '/doconut-res' | Reserviert; das Widget bündelt sein eigenes CSS |
maxUploadMb | number | 25 | Nur clientseitige Prüfung, sodass eine zu große Datei sofort fehlschlägt. Das Server‑Limit beträgt MaxUploadMb in AddSignerWidget |
maxSignatureKb | number | 512 | Clientseitiges Limit für den Bildmodus. Halten Sie es gleich dem Server‑MaxSignatureImageKb |
previewWidth | number | 560 | Pixelbreite der Seitenvorschau |
licenseUrl | string | null | null | Wandelt den Demo‑Wasserzeichen‑Hinweis in einen Link zu dieser URL um |
signatureMode | string | 'certified' | Initialer Signaturtyp: 'certified' oder 'visual'. Jeder andere Wert wird zu 'certified' |
showSignatureModeToggle | boolean | true | Zeigt die Auswahl Digital signature / Visual only. Mit false signiert das Widget mit signatureMode |
wordOutput | string | 'pdf' | Initiale Ausgabe für .docx-Quellen: 'pdf' oder 'docx'. Jeder andere Wert wird zu 'pdf' |
showOutputFormatToggle | boolean | true | Zeigt die Auswahl PDF / Word, nur für .docx-Quellen. Mit false verwendet das Widget wordOutput |
labels | object | {} | Überschreibt beliebige Teilmenge der englischen Zeichenketten |
Das Ausblenden eines Schalters deaktiviert die Funktion nicht; es fixiert den Wert. Zwei gängige Konfigurationen:
// Beide Schalter angezeigt, digitale Signatur standardmäßig: ein vollständiger Self-Service‑Unterzeichner.
Doconut.signer('#host', { basePath: '/doconut', licenseUrl: '/pricing' });// Nur visuell, kein Schalter: ein einfacher Stempel ohne digitale Signatur angeboten.
Doconut.signer('#host', {
basePath: '/doconut',
signatureMode: 'visual',
showSignatureModeToggle: false
});Rückrufe
| Rückruf | Wird ausgelöst, wenn | Nutzdaten |
|---|---|---|
onReady | Einmal beim Mount (nicht erneut bei reset()) | — |
onSourceLoaded | Die Datei wird geöffnet und ihre Vorschau angezeigt | { file: { token, name, pages, ext } } |
onSigned | Signieren erfolgreich | { downloadToken, downloadName, watermarked } |
onDownload | Bei jedem Klick auf Download | { downloadName, downloadToken } |
onError | Ein Öffnen‑, Signier‑ oder Download‑Schritt schlägt fehl, oder eine Datei im Bildmodus ist zu groß | { message } |
Ein Rückruf, der wirft, wird abgefangen und protokolliert; er unterbricht den Ablauf des Widgets niemals.
Imperative Handhabung
| Methode | Verhalten |
|---|---|
reset() | Kehrt zum Drop‑Screen zurück und löscht den aktuellen Flow. Löst onReady nicht erneut aus. Keine Operation nach destroy() |
loadFile(file) | Startet den Flow mit einem File. Keine Operation, sofern das Widget nicht auf seinem Drop‑Screen ist; rufe bei Bedarf zuerst reset() auf |
destroy() | Entfernt die Listener, leert das Mount und friert die Instanz ein |
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());Beschriftungen
Jeder String hat eine englische Vorgabe; labels überschreibt beliebige Teilmengen und der Rest bleibt Englisch. Fragmente, die zur Laufzeit geändert werden, verwenden {placeholders}, wie z. B. uploading: 'Uploading {name}…' und pages: '{n} pages'.
| Schlüssel | Englische Vorgabe |
|---|---|
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 |
Weitere Schlüssel decken den Platzierungsschritt, den Fehlerschirm, das verknüpfte Formular des Demo‑Hinweises (demoNoticePrefix, demoNoticeLink, demoNoticeSuffix) und die aria-live Ankündigungen ab.
Wenn open oder run 404 ohne JSON‑Fehler beantwortet, zeigt das Widget signingNotEnabled. Ein JSON‑Fehler vom Server hat immer Vorrang, sodass Meldungen wie ein abgelaufener Upload sichtbar bleiben.
Themen
Das Widget fügt dem Mount‑Element die Klasse dsw hinzu und liest seine Farben, Radius und Schriftarten aus CSS‑Custom‑Properties, sodass du es thematisieren kannst, ohne seine Interna zu berühren:
#host.dsw {
--dsw-accent: #b0522b; /* links, focus, aktiver Modus */
--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; /* der Type Modus */
}Standardwerte: --dsw-accent: #2b6cb0, --dsw-bg: #ffffff, --dsw-fg: #1a202c, --dsw-muted: #718096, --dsw-border: #cbd5e0, --dsw-radius: 8px, eine System‑UI‑Schrift und eine kursive Signaturschrift.
Erstelle dein eigenes Frontend
Das Widget ist ein Client für diesen HTTP‑Vertrag. Alle drei Routen liegen unter dem Pfad, an dem UseDoconut() eingebunden ist (normalerweise /doconut), und sie beantworten 404, bis AddSignerWidget() aufgerufen wird. Fehler enthalten einen JSON‑Body, { "error": "..." }, außer dort, wo die Tabelle "nur Status" angibt. Ein unbekannter ?sign=‑Wert beantwortet 400.
| Route | Zweck | Erfolgsantwort |
|---|---|---|
POST ?sign=open (multipart, one file) | Lade ein PDF oder .docx hoch und öffne es zur Vorschau | 200 — { token, name, pages, ext } |
POST ?sign=run (JSON body) | Signiere die hochgeladene Datei | 200 — { downloadToken, downloadName, watermarked } |
GET ?sign=download&token=<downloadToken> | Streame die signierte Datei | 200 — the file, Content-Disposition: attachment, Cache-Control: no-store |
ext in der open‑Antwort enthält den führenden Punkt (".docx"). Die Seitenvorschau verwendet die Standard‑Viewer‑Bild‑Route, {basePath}?token={token}&page={n}&thumb=1&width={px}; die angezeigte Seite wird zu placement.page.
Der run‑Body:
{
"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"
}| Feld | Hinweise |
|---|---|
token | Das Token von open |
signature.kind | Drawn, Typed oder Image, Groß‑/Kleinschreibung egal; alles andere wird zu Drawn. Nur ein Hinweis: die Nutzlast ist immer ein PNG |
signature.payload | Ein reines Base64‑PNG ohne data:‑Präfix. Es muss ein echtes PNG sein und nach dem Dekodieren nicht größer als MaxSignatureImageKb sein |
placement.page | 1‑basiert |
placement.x / y / w / h | Normalisiertes 0..1 vom oberen linken Eckpunkt, mit x + w ≤ 1 und y + h ≤ 1 |
meta.signerName / reason / location | Optional. Jeder wird getrimmt, ein leerer Wert wird verworfen und jeder wird auf 256 Zeichen gekürzt |
wordOutput | pdf (Standard) oder docx; für PDF‑Quellen ignoriert. Alles andere wird zu pdf |
mode | certified (Standard) oder visual. Alles andere wird zu certified |
downloadName folgt der Ausgabe: <source>-signed.pdf oder <source>-signed.docx, und download sendet das passende Content-Type.
Die hochgeladene Quelle und das signierte Ergebnis werden jeweils für 30 Minuten aufbewahrt. Danach beantworten run und download 404 und die Datei muss erneut geöffnet werden. Alle Tokens sind GUIDs.
| Route | Status | Wann | Body |
|---|---|---|---|
| any | 404 | Das Widget ist nicht aktiviert | status only |
| any | 405 | Falsches Verb (open und run benötigen POST, download benötigt GET) | status only |
open | 400 | Kein Multipart‑Upload | Expected a multipart file upload. |
open | 400 | Keine Datei oder eine leere Datei | No file uploaded. |
open | 400 | Alles andere als .pdf oder .docx | Signing supports PDF and Word (.docx) files only. |
open | 413 | Der Upload überschreitet MaxUploadMb | File is too large. |
run | 400 | Der Body ist kein gültiges JSON oder ist leer | Malformed request. / Empty request. |
run | 400 | Das Token fehlt oder ist keine GUID | Invalid token. |
run | 404 | Der Upload ist abgelaufen oder wurde nie geöffnet | Upload expired — please re-open the file. |
run | 400 | Keine Signatur oder keine Platzierung | No signature supplied. / No placement supplied. |
run | 400 | Die Nutzlast ist kein Base64, ist leer, zu groß oder kein 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 | Die Platzierung liegt außerhalb der Seite | The signature or its placement is invalid. |
run | 400 | Zertifizierter Modus, eine kostenpflichtige Lizenz und kein Zertifikat | No signing certificate configured. |
run | 400 | Zertifizierter Modus mit einem Zertifikat außerhalb seines Gültigkeitszeitraums | The signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd. |
open, run | 500 | Verarbeitung fehlgeschlagen | Eine bereinigte Meldung |
download | 400 | Das Token fehlt oder ist keine GUID | status only |
download | 404 | Unbekanntes oder abgelaufenes Token | status only |
Ein vollständiger Rundlauf mit fetch:
// file: die Datei zum Signieren; pngBase64: die Signatur als reines base64 PNG, ohne data:-Präfix,
// zum Beispiel canvas.toDataURL('image/png').split(',')[1].
async function signFile(file, pngBase64) {
const base = '/doconut';
// 1. open: Datei hochladen
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: signiere sie
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: die signierte Datei holen
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);
}Die Endpunkte sind same-origin: Diese Version unterstützt kein CORS. Stellen Sie Ihre UI und das Widget‑Skript vom selben Ursprung wie Doconut bereit, oder setzen Sie beide /doconut Pfade (den Middleware‑Pfad und den Ressourcen‑Pfad) per Reverse‑Proxy unter dem Ursprung Ihrer UI.
In production
-
Installieren Sie das Plugin neben dem Kernpaket, in derselben Version:
dotnet add package Doconut.NET8.Signer. -
Fügen Sie die Lizenzdatei hinzu. Legen Sie
Doconut.Viewer.Signer.licim selben Ordner wieDoconut.Viewer.licab. -
Holen Sie Ihr Zertifikat als PFX mit seinem privaten Schlüssel und der Ausstellerkette, von einer Zertifizierungsstelle oder der eigenen PKI Ihrer Organisation. Um zunächst zu testen, verwenden Sie eine Demo‑Lizenz (das integrierte Demo‑Zertifikat, mit Wasserzeichen) oder ein selbstsigniertes PFX.
-
Lesen Sie das Zertifikat aus der Konfiguration, sodass eine Änderung nie einen Code‑Änderung erfordert:
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"] ?? "", }); });Bewahren Sie das
.pfxaußerhalb vonwwwrootauf und halten Sie das Passwort außerhalb vonappsettings.json: Benutzergeheimnisse in der Entwicklung (dotnet user-secrets set "DoconutSigner:Password" "<password>"), eine Umgebungsvariable (DoconutSigner__Password) oder ein Tresor in der Produktion. -
Überprüfen Sie das Start‑Log. Es sollte
using certificate '{subject}' (valid until …). Signatures are digitally sealed.anzeigen. Eine Warnung bedeutet stattdessen, dass das Zertifikat abgelaufen, noch nicht gültig oder nicht für die Dokumenten‑signatur ausgestellt ist.
Vertrauen in PDF‑Reader. Ein Reader zeigt die Signatur als gültig an, wenn er der Zertifikatswurzel vertraut. Mit der PKI Ihrer Organisation gilt das auf jedem Rechner, der Ihrer Wurzel vertraut, was in der Regel jeder Rechner innerhalb der Organisation ist. Zertifikate, die Adobe auf irgendeinem Rechner vertraut (die Adobe Approved Trust List), werden, soweit wir wissen, mit dem privaten Schlüssel auf einem Hardware‑Token oder HSM ausgestellt, was dieses Plugin nicht nutzen kann: Es signiert ausschließlich aus einem PFX. Bestätigen Sie dies bei Ihrem Zertifikatsanbieter, bevor Sie sich auf diese Art von Vertrauen verlassen.
Web farms
Das Widget speichert jede Upload‑Datei und ihr Ergebnis im Speicher des Knotens, der open bereitgestellt hat. Hinter einem Load‑Balancer ohne Sticky‑Sessions kann eine spätere run, download oder Vorschaumanfrage einen anderen Knoten erreichen und den Upload nicht finden. Registrieren Sie den gemeinsamen, verschlüsselten Widget‑Speicher einmalig, nach AddDoconut():
byte[] farmKey = Convert.FromBase64String(builder.Configuration["Doconut:FarmKey"]);
builder.Services.AddDoconutDistributedWidgets(store =>
{
store.RootPath = @"\\fileshare\doconut"; // ein Ordner, den jeder Knoten lesen und schreiben kann
store.FarmKey = farmKey; // mindestens 32 Bytes, auf jedem Knoten identisch
// store.Ttl = TimeSpan.FromMinutes(30); // wie lange ein Upload aufbewahrt wird (der Standard)
});- Ein einzelner Server benötigt nichts: Ohne diesen Aufruf wird der In‑Memory‑Store verwendet.
- Uploads und Ergebnisse werden im Ruhezustand auf dem Share verschlüsselt (AES‑256, encrypt‑then‑MAC), und jede Datei ist an ihr Token gebunden, sodass ein Token niemals die Datei eines anderen lesen kann.
FarmKeymuss mindestens 32 Byte groß sein und auf jedem Knoten identisch sein. Laden Sie es aus einem Geheimnisspeicher; nie hartkodieren. Die Registrierung wirft einArgumentException, wennRootPathfehlt oderFarmKeykürzer als 32 Byte ist.- Zeigen Sie
RootPathauf denselben gemeinsamen Speicherort, den der verteilte Viewer verwendet, und geben Sie jedem Knoten dasselbe Signaturzertifikat.
API-Referenz
Die Fassade und die Widget-Optionen befinden sich im Doconut-Namespace; die Anforderungs‑ und Ergebnis‑Typen befinden sich in Doconut.Core.Models.Signing. SignerPlugin befindet sich in Doconut.Plugins.Signer.
DocumentSigner
public sealed class DocumentSigner
{
public Task<SignResult> SignAsync(
Stream source, string sourceExtension, SignRequest request,
SigningCertificate? cert = null, CancellationToken ct = default);
}Durch Dependency Injection aufgelöst; der Konstruktor ist intern. sourceExtension ist ".pdf" oder ".docx". Unter einer kostenpflichtigen Lizenz wird cert verwendet und die Ausgabe ist sauber; unter einer temporären Lizenz wird das integrierte Demo‑Zertifikat verwendet, cert wird ignoriert, und die Ausgabe ist mit Wasserzeichen versehen.
SignaturAnfrage
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
}Eine sichtbare Signatur, einmal platziert, plus optionale Unterzeichner‑Metadaten.
VisibleSignature und SignatureKind
public sealed record VisibleSignature(SignatureKind Kind, byte[] PngBytes)
{
public bool IsValid { get; } // PngBytes ist nicht leer
}
public enum SignatureKind { Drawn, Typed, Image }PngBytes ist ein PNG für jede Art. Eine gezeichnete oder getippte Signatur ist transparent; ein hochgeladenes Bild behält die Transparenz bei, die es hatte, sodass ein undurchsichtiges JPG undurchsichtig bleibt. Kind ist nur ein Hinweis.
Signaturplatzierung
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 ist 1-basiert; X, Y, W und H sind normalisierte 0..1 vom oberen linken Eckpunkt.
SignatureMode und WordOutput
public enum SignatureMode { Certified, Visual } // Certified ist standardmäßig
public enum WordOutput { Pdf, Docx } // Pdf ist standardmäßig; ignoriert für PDF-QuellenSignaturErgebnis
public sealed record SignResult(Stream Stream, string Extension);Das signierte Dokument als durchsuchbarer Stream und seine Erweiterung mit dem Punkt (".pdf" oder ".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 ist nicht leer, oder PfxPath ist nicht leer
}Setzen Sie entweder PfxBytes oder PfxPath, plus Password.
SignerWidgetOptionen
public sealed class SignerWidgetOptions
{
public int MaxUploadMb { get; set; } = 25;
public int MaxSignatureImageKb { get; set; } = 512;
public SigningCertificate? SigningCertificate { get; set; }
}Set through DoconutOptions.AddSignerWidget(Action<SignerWidgetOptions>? configure = null), which returns the DoconutOptions so calls can be chained. A null SigningCertificate means the demo certificate under a temporary license, and Visual signatures only under a paid one.
Fehlerbehebung
| Symptom | Ursache | Lösung |
|---|---|---|
AddDoconut() wirft The Signer plugin is registered via AddPlugin but no active license grants Signer. | Keine Lizenz, eine TRIAL‑Datei, eine Lizenz ohne Signer oder eine kostenpflichtige Lizenz außerhalb ihres Versionsfensters | Installieren Sie eine Lizenz, die Signer gewährt, oder entfernen Sie AddPlugin<SignerPlugin>() |
AddDoconut() wirft AddSignerWidget() was called but the Signer plugin is not registered. | Das Widget ist aktiviert ohne sein Plugin | Fügen Sie options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>() hinzu |
AddDoconut() wirft Doconut Signer: the certificate file was not found at '{path}'. | PfxPath verweist auf eine fehlende Datei | Korrigieren Sie den Pfad; stellen Sie die Datei dort bereit, wo das App‑Konto sie lesen kann |
AddDoconut() wirft Doconut Signer: the signing certificate could not be opened — the password is incorrect or the file is not a valid .pfx. | Falsches Passwort oder keine PKCS#12‑Datei | Überprüfen Sie das Passwort; verwenden Sie ein echtes .pfx |
AddDoconut() wirft Doconut Signer: the signing certificate has no private key. Re-export the .pfx INCLUDING the private key. | Das PFX wurde ohne privaten Schlüssel exportiert | Exportieren Sie es erneut mit dem privaten Schlüssel |
Auflösen von DocumentSigner wirft No IDocumentSigner is registered. | SignerPlugin ist nicht registriert | Fügen Sie AddPlugin<SignerPlugin>() innerhalb von AddDoconut() hinzu |
| Die Ausgabe ist mit Wasserzeichen versehen | Die Lizenz ist temporär (Demo/NFR) | Verwenden Sie eine kostenpflichtige Lizenz, die Signer gewährt |
run antwortet 400 No signing certificate configured. | Eine kostenpflichtige Lizenz, zertifizierter Modus und kein Zertifikat | Konfigurieren Sie SigningCertificate, oder melden Sie sich im visuellen Modus an |
run antwortet 400 The signing certificate expired on yyyy-MM-dd. | Das Zertifikat ist abgelaufen | Ersetzen Sie es; visuelle Signaturen funktionieren in der Zwischenzeit weiter |
| Das Protokoll sagt, die Ausgabe "verwendet das integrierte Demo‑Zertifikat", doch eine kostenpflichtige Lizenz verweigert zertifizierte Signaturen | Diese Zeile wird immer geschrieben, wenn kein Zertifikat konfiguriert ist, unabhängig von der Lizenz | Konfigurieren Sie SigningCertificate |
Das Widget lädt, sagt aber Signing is not enabled on this server. | AddSignerWidget() wurde nicht aufgerufen, oder basePath stimmt nicht mit dem Ort überein, an dem UseDoconut() gemountet ist | Rufen Sie AddSignerWidget() auf; korrigieren Sie basePath |
run antwortet 400 The signature image must be a PNG., Signature image is not valid base64. oder Signature image is too large. | Eine benutzerdefinierte UI hat eine data:‑URL, ein JPG oder mehr als MaxSignatureImageKb gesendet | Senden Sie ein reines base64 PNG innerhalb des Limits |
open antwortet 413 File is too large. | Der Upload überschreitet MaxUploadMb | Erhöhen Sie MaxUploadMb in AddSignerWidget; das maxUploadMb des Widgets ist nur eine clientseitige Prüfung |
run oder download antworten 404 Upload expired — please re-open the file. | Das 30‑Minuten‑Fenster ist abgelaufen, oder ein Web‑Farm‑Knoten hat den Upload nicht | Öffnen Sie die Datei erneut; in einer Farm registrieren Sie AddDoconutDistributedWidgets |
Ein signiertes .docx zeigt in einigen Betrachtern keine Signatur | Word‑Ausgabe enthält eine OOXML‑Paket‑Signatur, die viele Betrachter nicht anzeigen | Signieren Sie zu PDF, dem Standard |
| PDF‑Reader sagen, die Identität des Unterzeichners ist unbekannt | Der Reader vertraut der Zertifikatswurzel nicht (das Demo‑Zertifikat wird nie vertraut) | Verwenden Sie ein Zertifikat von einer Wurzel, der Ihre Reader vertrauen |
| Das Widget schlägt fehl, wenn die UI auf einer anderen Herkunft ist | Die Endpunkte unterstützen kein CORS | Stellen Sie die UI von derselben Herkunft bereit, oder setzen Sie einen Reverse‑Proxy für die Doconut‑Pfade ein |
| Das Theme wird nicht angewendet | Der Selektor zielt auf ein Element innerhalb des Mounts | Zielen Sie auf das Mount selbst: #host.dsw oder #host |
War diese Seite hilfreich?