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 stets ein PNG‑Bild: gezeichnet, getippt oder vom Unterzeichner hochgeladen.
| Oberfläche | Verwenden, wenn |
|---|---|
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 mitgeführt werden.
Paket installieren
Installieren Sie das neueste stabile Signer-Plugin:
dotnet add package Doconut.NETStandard.SignerUm das Plugin an die in dieser Dokumentation beschriebene Version zu binden, übergeben Sie die Version separat:
dotnet add package Doconut.NETStandard.Signer --version 26.10.0Halten Sie das Signer-Paket in derselben Version wie Doconut.NETStandard. Die Paket‑ID ist Doconut.NETStandard.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.
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 Fähigkeit Signer gewährt. Ohne diese wirft AddDoconut() beim Starten einen Fehler, bevor die Anwendung eine Anfrage bedient:
Hinweis: Die folgende Ausnahme wird in deutscher Sprache beschrieben, obwohl der eigentliche Code‑Block englische Meldungen enthält.
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 einen Fehler 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 eingebauten 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 eingebauten 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 auf einer Evaluations‑Lizenz 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 aus der Dependency Injection aufgelöst. Sein Konstruktor ist internal, also nie 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 Quellstream, 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; // \u0022.docx\u0022SignAsync wirft eine Ausnahme, anstatt zurückzugeben, wenn der Aufruf nicht erfolgreich sein kann:
| Ausnahme | Nachricht | Wann |
|---|---|---|
InvalidOperationException | No signing certificate configured. | Zertifizierter Modus, eine kostenpflichtige 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 entscheidet, ob die Signatur versiegelt ist.
| Modus | Was es erzeugt | Zertifikat | Verifizierbar |
|---|---|---|---|
SignatureMode.Certified (default) | Die sichtbare Signatur plus ein digitales Siegel | Erforderlich bei einer kostenpflichtigen Lizenz | Ja |
SignatureMode.Visual | Nur die sichtbare Signatur | Niemals erforderlich | 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 Ausstellerzertifikate aus Ihrem PFX, sodass ein Leser, der Ihrer Root vertraut, die Kette aufbauen kann. Word‑native Siegel sind OOXML‑Paket‑Signaturen und enthalten nur das Signaturzertifikat des Unterzeichners.
Word-Dokumente
Für eine .docx-Quelle wählt SignRequest.WordOutput die Ausgabe. Für PDF-Quellen wird dies 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 darin platziert, plus eine OOXML-Paket‑Signatur | Eingeschränkt: nicht jeder Betrachter zeigt OOXML-Paket‑Signaturen an |
Behalten Sie PDF, es sei denn, der Empfänger benötigt eine editierbare Word‑Datei und akzeptiert die eingeschränkte Verifizierungsunterstü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 niemals protokolliert, an einen Client zurückgegeben oder dauerhaft gespeichert, und das Passwort erscheint nie in einer Protokollzeile oder Fehlermeldung.
Anforderungen:
- Ein PFX / PKCS#12‑Bundle 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 jedoch 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 suchen 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‑prüfungen
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 |
Ansonsten 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 (wassergezeichnete) Signatur
});
});AddSignerWidget() ohne Argument aktiviert das Widget mit den Vorgaben. Es erteilt 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.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 der ersten Anfrage Signing is not enabled on this server. meldet.
Einbetten
UseDoconutResources() stellt das Skript unter {ResourcesPath}/js/doconutSigner.js bereit (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) akzeptiert einen CSS‑Selektor oder ein Element, wirft einen Fehler, wenn das Ziel 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 Signaturschrift, oder Image aus einer PNG-, JPG‑ oder GIF‑Datei), zieht und skaliert sie auf die Seite 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 enthält sein eigenes CSS |
maxUploadMb | number | 25 | Nur clientseitige Prüfung, sodass eine zu große Datei schnell fehlschlägt. Das Server-Limit beträgt MaxUploadMb in AddSignerWidget |
maxSignatureKb | number | 512 | Clientseitiges Limit für den Bildmodus. Halte 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 Digitale Signatur / Nur visuell. 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-Signer.
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
| Callback | Wird ausgelöst, wenn | Nutzdaten |
|---|---|---|
onReady | Einmal beim Einbinden (nicht erneut bei reset()) | — |
onSourceLoaded | Die Datei wird geöffnet und ihre Vorschau angezeigt | { file: { token, name, pages, ext } } |
onSigned | Signatur erfolgreich | { downloadToken, downloadName, watermarked } |
onDownload | Bei jedem Klick auf Download | { downloadName, downloadToken } |
onError | Ein Öffnen-, Signier- oder Download‑Schritt schlägt fehl oder eine Bild‑Modus‑Datei ist zu groß | { message } |
Ein Callback, das eine Ausnahme wirft, wird abgefangen und protokolliert; es unterbricht den Ablauf des Widgets niemals.
Imperativer Handler
| Methode | Verhalten |
|---|---|
reset() | Kehrt zum Drop‑Bildschirm zurück und löscht den aktuellen Ablauf. Feuert onReady nicht erneut. Keine Aktion nach destroy() |
loadFile(file) | Startet den Ablauf mit einem File. Keine Aktion, sofern das Widget nicht auf seinem Drop‑Bildschirm ist; rufe bei Bedarf zuerst reset() auf |
destroy() | Entfernt die Listener, leert das Mount‑Element 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());Bezeichnungen
Jeder String hat einen englischen Standard; 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 | Englischer Standard |
|---|---|
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.
Theming
Das Widget fügt dem Mount‑Element die Klasse dsw hinzu und liest seine Farben, Radien und Schriftarten aus CSS‑Custom‑Properties, sodass du es thematisieren kannst, ohne die internen Strukturen zu verändern:
#host.dsw {
--dsw-accent: #b0522b; /* Links, Fokus, 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 — die Datei, 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, case‑insensitive; alles andere wird zu Drawn. Nur ein Hinweis: das Payload ist immer ein PNG |
signature.payload | Ein reines Base64‑PNG ohne data:‑Präfix. Es muss ein echtes PNG sein und darf nach dem Dekodieren nicht größer als MaxSignatureImageKb sein |
placement.page | 1‑basiert |
placement.x / y / w / h | Normalisiertes 0..1 von der oberen linken Ecke, mit x + w ≤ 1 und y + h ≤ 1 |
meta.signerName / reason / location | Optional. Jeder Eintrag wird getrimmt, ein leerer Wert wird verworfen und jeder wird auf 256 Zeichen gekürzt |
wordOutput | pdf (Standard) oder docx; wird 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 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 |
|---|---|---|---|
| beliebig | 404 | Das Widget ist nicht aktiviert | nur Status |
| beliebig | 405 | Falsches Verb (open und run benötigen POST, download benötigt GET) | nur Status |
open | 400 | Kein Multipart‑Upload | Expected a multipart file upload. |
open | 400 | Keine Datei oder eine leere | 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 | Das Payload ist nicht 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 | nur Status |
download | 404 | Unbekanntes oder abgelaufenes Token | nur Status |
Ein vollständiger Rundlauf mit fetch:
// file: die File 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 abrufen
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) über einen Reverse‑Proxy unter dem Ursprung Ihrer UI.
In Produktion
-
Installieren Sie das Plugin neben dem Kernpaket, in derselben Version:
dotnet add package Doconut.NETStandard.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 es zunächst auszuprobieren, verwenden Sie eine Demolizenz (das integrierte Demo‑Zertifikat, mit Wasserzeichen) oder ein selbstsigniertes PFX.
-
Lesen Sie das Zertifikat aus der Konfiguration, sodass eine Änderung niemals 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 den
.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 für jede Maschine, die Ihrer Wurzel vertraut, was in der Regel jede Maschine innerhalb der Organisation ist. Zertifikate, die Adobe auf irgendeiner Maschine 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‑Farmen
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 node lesen und schreiben kann
store.FarmKey = farmKey; // mindestens 32 Bytes, identisch auf jedem node
// 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 gleich sein. Laden Sie es aus einem Geheimnis‑Store; niemals hart codieren. 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 Namensraum; die Anforderungs- und Ergebnis-Typen befinden sich in Doconut.Core.Models.Signing. SignerPlugin ist 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);
}Wird über 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.
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
}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 vorhandene Transparenz bei, sodass ein undurchsichtiges JPG undurchsichtig bleibt. Kind ist nur ein Hinweis.
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 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-QuellenSignResult
public sealed record SignResult(Stream Stream, string Extension);Das signierte Dokument als durchsuchbarer Stream und seine Dateierweiterung 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
}Setze entweder PfxBytes oder PfxPath, plus Password.
SignerWidgetOptions
public sealed class SignerWidgetOptions
{
public int MaxUploadMb { get; set; } = 25;
public int MaxSignatureImageKb { get; set; } = 512;
public SigningCertificate? SigningCertificate { get; set; }
}Setze über DoconutOptions.AddSignerWidget(Action<SignerWidgetOptions>? configure = null), das das DoconutOptions zurückgibt, sodass Aufrufe verkettet werden können. Ein null SigningCertificate bedeutet das Demo-Zertifikat unter einer temporären Lizenz und visuelle Signaturen nur unter einer kostenpflichtigen.
Fehlersuche
| 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 | Installiere eine Lizenz, die Signer gewährt, oder entferne AddPlugin<SignerPlugin>() |
AddDoconut() wirft AddSignerWidget() was called but the Signer plugin is not registered. | Das Widget ist aktiviert ohne sein Plugin | Füge 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 | Korrigiere den Pfad; stelle 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üfe das Passwort; verwende 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 | Exportiere es erneut mit dem privaten Schlüssel |
Auflösen von DocumentSigner wirft No IDocumentSigner is registered. | SignerPlugin ist nicht registriert | Füge AddPlugin<SignerPlugin>() innerhalb von AddDoconut() hinzu |
| Die Ausgabe hat ein Wasserzeichen | Die Lizenz ist temporär (Demo/NFR) | Verwende eine kostenpflichtige Lizenz, die Signer gewährt |
run antwortet 400 No signing certificate configured. | Eine kostenpflichtige Lizenz, Certified-Modus und kein Zertifikat | Konfiguriere SigningCertificate, oder signiere im Visual-Modus |
run antwortet 400 The signing certificate expired on yyyy-MM-dd. | Das Zertifikat ist abgelaufen | Ersetze es; visuelle Signaturen funktionieren in der Zwischenzeit weiter |
| Das Log sagt, die Ausgabe "verwendet das integrierte Demo-Zertifikat", doch eine kostenpflichtige Lizenz verweigert Certified-Signaturen | Diese Zeile wird immer geschrieben, wenn kein Zertifikat konfiguriert ist, unabhängig von der Lizenz | Konfiguriere 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, wo UseDoconut() gemountet ist | Rufe AddSignerWidget() auf; korrigiere 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 sendete eine data: URL, ein JPG oder mehr als MaxSignatureImageKb | Sende ein reines base64 PNG innerhalb des Limits |
open antwortet 413 File is too large. | Der Upload überschreitet MaxUploadMb | Erhöhe MaxUploadMb in AddSignerWidget; das maxUploadMb des Widgets ist nur eine clientseitige Prüfung |
run oder download antwortet 404 Upload expired — please re-open the file. | Das 30‑Minuten‑Fenster ist abgelaufen, oder ein Web‑Farm‑Knoten hat den Upload nicht | Öffne die Datei erneut; in einer Farm registriere AddDoconutDistributedWidgets |
Ein signiertes .docx zeigt in einigen Betrachtern keine Signatur | Word-Ausgabe enthält eine OOXML-Paket-Signatur, die viele Betrachter nicht anzeigen | Signiere zu PDF, dem Standard |
| PDF-Reader sagen, die Identität des Unterzeichners ist unbekannt | Der Reader vertraut der Root des Zertifikats nicht (das Demo-Zertifikat wird nie vertraut) | Verwende ein Zertifikat von einer Root, der deine Reader vertrauen |
| Das Widget schlägt fehl, wenn die UI auf einer anderen Herkunft ist | Die Endpunkte haben keine CORS-Unterstützung | Stelle die UI von derselben Herkunft bereit, oder reverse-proxy die Doconut-Pfade |
| Das Theme wird nicht angewendet | Der Selektor zielt auf ein Element innerhalb des Mounts | Ziele auf das Mount selbst: #host.dsw oder #host |
War diese Seite hilfreich?