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ächeVerwendung
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:

bash
dotnet add package Doconut.NET8.Signer

Um das Plugin an die in dieser Dokumentation beschriebene Version zu binden, übergeben Sie die Version separat:

bash
dotnet add package Doconut.NET8.Signer --version 26.10.0

Halten 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:

bash
apt-get update && apt-get install -y libfontconfig1

Unter 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():

csharp
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:

text
The Signer plugin is registered via AddPlugin but no active license grants Signer. Remove the AddPlugin<...>() call or install a license (or trial/demo) that includes Signer.

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

LizenzstatusStartZertifizierte SignaturVisuelle Signatur
Kostenpflichtige Lizenz, die Signer gewährt, Zertifikat konfiguriertStartetVersiegelt mit Ihrem Zertifikat, sauber (watermarked: false)Sauber
Kostenpflichtige Lizenz, die Signer gewährt, kein ZertifikatStartetAbgelehnt: No signing certificate configured.Sauber
Kostenpflichtige Lizenz, Zertifikat abgelaufen oder noch nicht gültigStartet (mit aktiviertem Widget, eine Warnung wird protokolliert)Abgelehnt: The signing certificate expired on yyyy-MM-dd.Sauber
Temporäre Demo/NFR‑Lizenz, aktiv oder abgelaufenStartetVersiegelt 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 VersionsfenstersAddDoconut() 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>().

csharp
using Doconut;
using Doconut.Core.Models.Signing;

public sealed class ContractSigning
{
    private readonly DocumentSigner _signer;

    public ContractSigning(DocumentSigner signer) => _signer = signer;

    public async Task<byte[]> SignAsync(Stream pdf, byte[] signaturePng, SigningCertificate certificate, CancellationToken ct)
    {
        var request = new SignRequest(
            new VisibleSignature(SignatureKind.Drawn, signaturePng),
            new SignaturePlacement(Page: 1, X: 0.58, Y: 0.80, W: 0.32, H: 0.12),
            SignerName: "Ada Lovelace",
            Reason: "I approve this document",
            Location: "London, UK");
        // Mode 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:

csharp
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:

csharp
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:

AusnahmeNachrichtWann
InvalidOperationExceptionNo signing certificate configured.Zertifizierter Modus, eine bezahlte Lizenz und kein Zertifikat übergeben
InvalidOperationExceptionThe 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
ArgumentExceptionThe 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
NotSupportedExceptionThe 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.

ModusWas es erzeugtZertifikatVerifizierbar
SignatureMode.Certified (default)Die sichtbare Signatur plus ein digitales SiegelErforderlich bei einer bezahlten LizenzJa
SignatureMode.VisualNur die sichtbare SignaturNiemals benötigtNein: 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.

AusgabeWas passiertUnterstützung des Verifiers
WordOutput.Pdf (default)Das Dokument wird in PDF konvertiert, dann signiert und versiegeltBreit: ein signiertes PDF wird überall verifiziert
WordOutput.DocxDas Dokument bleibt Word: das Signaturbild wird eingefügt, plus eine OOXML-Paket‑SignaturEingeschrä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:

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

bash
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:

NachrichtLö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:

text
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:

text
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:

text
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:

csharp
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:

text
AddSignerWidget() was called but the Signer plugin is not registered. Add options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>() (the widget needs it), or remove the AddSignerWidget() call.

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:

html
<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

OptionTypStandardHinweise
basePathstring'/doconut'Wo die ?sign=-Endpunkte und Vorschaubilder bereitgestellt werden
resPathstring'/doconut-res'Reserviert; das Widget bündelt sein eigenes CSS
maxUploadMbnumber25Nur clientseitige Prüfung, sodass eine zu große Datei sofort fehlschlägt. Das Server‑Limit beträgt MaxUploadMb in AddSignerWidget
maxSignatureKbnumber512Clientseitiges Limit für den Bildmodus. Halten Sie es gleich dem Server‑MaxSignatureImageKb
previewWidthnumber560Pixelbreite der Seitenvorschau
licenseUrlstring | nullnullWandelt den Demo‑Wasserzeichen‑Hinweis in einen Link zu dieser URL um
signatureModestring'certified'Initialer Signaturtyp: 'certified' oder 'visual'. Jeder andere Wert wird zu 'certified'
showSignatureModeTogglebooleantrueZeigt die Auswahl Digital signature / Visual only. Mit false signiert das Widget mit signatureMode
wordOutputstring'pdf'Initiale Ausgabe für .docx-Quellen: 'pdf' oder 'docx'. Jeder andere Wert wird zu 'pdf'
showOutputFormatTogglebooleantrueZeigt die Auswahl PDF / Word, nur für .docx-Quellen. Mit false verwendet das Widget wordOutput
labelsobject{}Überschreibt beliebige Teilmenge der englischen Zeichenketten

Das Ausblenden eines Schalters deaktiviert die Funktion nicht; es fixiert den Wert. Zwei gängige Konfigurationen:

javascript
// Beide Schalter angezeigt, digitale Signatur standardmäßig: ein vollständiger Self-Service‑Unterzeichner.
Doconut.signer('#host', { basePath: '/doconut', licenseUrl: '/pricing' });
javascript
// Nur visuell, kein Schalter: ein einfacher Stempel ohne digitale Signatur angeboten.
Doconut.signer('#host', {
  basePath: '/doconut',
  signatureMode: 'visual',
  showSignatureModeToggle: false
});

Rückrufe

RückrufWird ausgelöst, wennNutzdaten
onReadyEinmal beim Mount (nicht erneut bei reset())—
onSourceLoadedDie Datei wird geöffnet und ihre Vorschau angezeigt{ file: { token, name, pages, ext } }
onSignedSignieren erfolgreich{ downloadToken, downloadName, watermarked }
onDownloadBei jedem Klick auf Download{ downloadName, downloadToken }
onErrorEin Ö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

MethodeVerhalten
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
javascript
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üsselEnglische Vorgabe
dropPromptDrag & drop a PDF or Word file here
dropHintPDF or Word (.docx)
chooseFileChoose file
signatureHeadingYour signature
modeDraw / modeType / modeImageDraw / Type / Image
metaSummarySignature details (optional)
metaSignerName / metaReason / metaLocationSigner name / Reason / Location
signatureTypeSignature type
modeCertified / modeVisualDigital signature / Visual only
modeVisualNoteNo certificate — a visible mark only, not cryptographically verifiable.
outputFormatOutput format
outputPdf / outputWordPDF / Word (.docx)
signActionSign document
downloadDownload
demoNoticeDemo — signed with the Doconut demo certificate; output is watermarked.
signingNotEnabledSigning is not enabled on this server.
page / pages1 page / {n} pages

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:

css
#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.

RouteZweckErfolgsantwort
POST ?sign=open (multipart, one file)Lade ein PDF oder .docx hoch und öffne es zur Vorschau200 — { token, name, pages, ext }
POST ?sign=run (JSON body)Signiere die hochgeladene Datei200 — { downloadToken, downloadName, watermarked }
GET ?sign=download&token=<downloadToken>Streame die signierte Datei200 — 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:

json
{
  "token": "GUID-from-open",
  "signature": { "kind": "Drawn", "payload": "<base64 PNG, no data: prefix>" },
  "placement": { "page": 1, "x": 0.58, "y": 0.80, "w": 0.32, "h": 0.12 },
  "meta": { "signerName": "Ada Lovelace", "reason": "I approve", "location": "London, UK" },
  "wordOutput": "pdf",
  "mode": "certified"
}
FeldHinweise
tokenDas Token von open
signature.kindDrawn, Typed oder Image, Groß‑/Kleinschreibung egal; alles andere wird zu Drawn. Nur ein Hinweis: die Nutzlast ist immer ein PNG
signature.payloadEin reines Base64‑PNG ohne data:‑Präfix. Es muss ein echtes PNG sein und nach dem Dekodieren nicht größer als MaxSignatureImageKb sein
placement.page1‑basiert
placement.x / y / w / hNormalisiertes 0..1 vom oberen linken Eckpunkt, mit x + w ≤ 1 und y + h ≤ 1
meta.signerName / reason / locationOptional. Jeder wird getrimmt, ein leerer Wert wird verworfen und jeder wird auf 256 Zeichen gekürzt
wordOutputpdf (Standard) oder docx; für PDF‑Quellen ignoriert. Alles andere wird zu pdf
modecertified (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.

RouteStatusWannBody
any404Das Widget ist nicht aktiviertstatus only
any405Falsches Verb (open und run benötigen POST, download benötigt GET)status only
open400Kein Multipart‑UploadExpected a multipart file upload.
open400Keine Datei oder eine leere DateiNo file uploaded.
open400Alles andere als .pdf oder .docxSigning supports PDF and Word (.docx) files only.
open413Der Upload überschreitet MaxUploadMbFile is too large.
run400Der Body ist kein gültiges JSON oder ist leerMalformed request. / Empty request.
run400Das Token fehlt oder ist keine GUIDInvalid token.
run404Der Upload ist abgelaufen oder wurde nie geöffnetUpload expired — please re-open the file.
run400Keine Signatur oder keine PlatzierungNo signature supplied. / No placement supplied.
run400Die Nutzlast ist kein Base64, ist leer, zu groß oder kein PNGSignature image is not valid base64. / Signature image is empty. / Signature image is too large. / The signature image must be a PNG.
run400Die Platzierung liegt außerhalb der SeiteThe signature or its placement is invalid.
run400Zertifizierter Modus, eine kostenpflichtige Lizenz und kein ZertifikatNo signing certificate configured.
run400Zertifizierter Modus mit einem Zertifikat außerhalb seines GültigkeitszeitraumsThe signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd.
open, run500Verarbeitung fehlgeschlagenEine bereinigte Meldung
download400Das Token fehlt oder ist keine GUIDstatus only
download404Unbekanntes oder abgelaufenes Tokenstatus only

Ein vollständiger Rundlauf mit fetch:

javascript
// 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

  1. Installieren Sie das Plugin neben dem Kernpaket, in derselben Version: dotnet add package Doconut.NET8.Signer.

  2. Fügen Sie die Lizenzdatei hinzu. Legen Sie Doconut.Viewer.Signer.lic im selben Ordner wie Doconut.Viewer.lic ab.

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

  4. Lesen Sie das Zertifikat aus der Konfiguration, sodass eine Änderung nie einen Code‑Änderung erfordert:

    json
    "DoconutSigner": { "PfxPath": "certs/your-certificate.pfx" }
    csharp
    var 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 .pfx außerhalb von wwwroot auf und halten Sie das Passwort außerhalb von appsettings.json: Benutzergeheimnisse in der Entwicklung (dotnet user-secrets set "DoconutSigner:Password" "<password>"), eine Umgebungsvariable (DoconutSigner__Password) oder ein Tresor in der Produktion.

  5. Ü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():

csharp
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.
  • FarmKey muss mindestens 32 Byte groß sein und auf jedem Knoten identisch sein. Laden Sie es aus einem Geheimnisspeicher; nie hartkodieren. Die Registrierung wirft ein ArgumentException, wenn RootPath fehlt oder FarmKey kürzer als 32 Byte ist.
  • Zeigen Sie RootPath auf 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

csharp
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

csharp
public sealed record SignRequest(
    VisibleSignature   Signature,
    SignaturePlacement Placement,
    string?            SignerName = null,
    string?            Reason     = null,
    string?            Location   = null,
    WordOutput         WordOutput = WordOutput.Pdf,
    SignatureMode      Mode       = SignatureMode.Certified)
{
    public bool IsValid { get; }   // Signature.IsValid && Placement.IsValid
}

Eine sichtbare Signatur, einmal platziert, plus optionale Unterzeichner‑Metadaten.

VisibleSignature und SignatureKind

csharp
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

csharp
public readonly record struct SignaturePlacement(int Page, double X, double Y, double W, double H)
{
    public bool IsValid { get; }   // Page >= 1; X, Y >= 0; W, H > 0; X + W <= 1; Y + H <= 1
}

Page ist 1-basiert; X, Y, W und H sind normalisierte 0..1 vom oberen linken Eckpunkt.

SignatureMode und WordOutput

csharp
public enum SignatureMode { Certified, Visual }   // Certified ist standardmäßig
public enum WordOutput { Pdf, Docx }              // Pdf ist standardmäßig; ignoriert für PDF-Quellen

SignaturErgebnis

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

Das signierte Dokument als durchsuchbarer Stream und seine Erweiterung mit dem Punkt (".pdf" oder ".docx").

SigningCertificate

csharp
public sealed class SigningCertificate
{
    public byte[]? PfxBytes { get; init; }
    public string? PfxPath  { get; init; }
    public string  Password { get; init; } = "";
    public bool    HasMaterial { get; }   // PfxBytes ist nicht leer, oder PfxPath ist nicht leer
}

Setzen Sie entweder PfxBytes oder PfxPath, plus Password.

SignerWidgetOptionen

csharp
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

SymptomUrsacheLö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 VersionsfenstersInstallieren 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 PluginFü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 DateiKorrigieren 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 exportiertExportieren Sie es erneut mit dem privaten Schlüssel
Auflösen von DocumentSigner wirft No IDocumentSigner is registered.SignerPlugin ist nicht registriertFügen Sie AddPlugin<SignerPlugin>() innerhalb von AddDoconut() hinzu
Die Ausgabe ist mit Wasserzeichen versehenDie 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 ZertifikatKonfigurieren Sie SigningCertificate, oder melden Sie sich im visuellen Modus an
run antwortet 400 The signing certificate expired on yyyy-MM-dd.Das Zertifikat ist abgelaufenErsetzen 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 SignaturenDiese Zeile wird immer geschrieben, wenn kein Zertifikat konfiguriert ist, unabhängig von der LizenzKonfigurieren 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 istRufen 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 gesendetSenden Sie ein reines base64 PNG innerhalb des Limits
open antwortet 413 File is too large.Der Upload überschreitet MaxUploadMbErhö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 SignaturWord‑Ausgabe enthält eine OOXML‑Paket‑Signatur, die viele Betrachter nicht anzeigenSignieren Sie zu PDF, dem Standard
PDF‑Reader sagen, die Identität des Unterzeichners ist unbekanntDer 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 istDie Endpunkte unterstützen kein CORSStellen Sie die UI von derselben Herkunft bereit, oder setzen Sie einen Reverse‑Proxy für die Doconut‑Pfade ein
Das Theme wird nicht angewendetDer Selektor zielt auf ein Element innerhalb des MountsZielen Sie auf das Mount selbst: #host.dsw oder #host

War diese Seite hilfreich?