Signer-plugin

Signera PDF- och Word-dokument med en synlig signatur och en digital försegling

Signer‑pluginet placerar en synlig signatur på ett dokument och förseglar det som standard med en digital signatur som en PDF‑läsare kan verifiera. Det signerar PDF‑ och Word (.docx)‑filer. Den synliga signaturen är alltid en PNG‑bild: ritad, skriven eller uppladdad av undertecknaren.

YtaAnvänd när
DocumentSigner (C#)Du signerar på servern, utan att en webbläsare är inblandad
Drop-in widget (doconutSigner.js)Du vill ha en färdig uppladdnings‑, signerings‑ och nedladdningsskärm på din sida
HTTP endpoints (?sign=open|run|download)Du bygger ditt eget signerings‑UI mot ett dokumenterat serverkontrakt

Varje signatur placeras en gång, på en sida. Undertecknarens namn, anledning och plats kan följa med den.

Installera paketet

Installera den senaste stabila Signer‑pluginet:

bash
dotnet add package Doconut.NET8.Signer

För att låsa pluginet till den version som den här dokumentationen beskriver, ange versionen separat:

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

Behåll Signer‑paketet på samma version som Doconut.NET8. Paket‑ID:t är Doconut.NET8.Signer; .<version> visas endast i det nedladdade filnamnet .nupkg.

Pluginens licensfil, Doconut.Viewer.Signer.lic, placeras i samma mapp som Doconut.Viewer.lic; den läses tillsammans med visningslicensen.

Plattformar. Pluginet körs där Doconut.NET8 körs: Windows och glibc‑baserad Linux på x64 (inte Alpine eller andra musl‑baserade distributioner). På Linux, installera fontkonfigurationsbiblioteket innan det första dokumentet öppnas:

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

På RHEL, Fedora och liknande distributioner är paketet fontconfig. Utan det misslyckas öppning av ett dokument med The system library libfontconfig1 is missing. Install it (Debian/Ubuntu: apt-get install -y libfontconfig1) and see the Linux section of the Doconut documentation.

Registrera pluginet

Precis som varje Doconut‑plugin registreras Signer med AddPlugin<TPlugin>() i AddDoconut():

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
});

Det är allt som C#‑fasaden behöver. Widgeten och dess HTTP‑endpoints är ett separat val, AddSignerWidget() (se Inbäddad widget).

Pluginet behöver en licens som ger Signer‑kapaciteten. Utan en sådan kastar AddDoconut() ett undantag vid start, innan appen hanterar en begäran:

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.

Det kastas för ingen licens, en äldre TRIAL‑fil, en licens utan Signer, och en betald licens som används utanför sitt versionsfönster. Tillfälliga Demo/NFR‑licenser accepteras. Se Licensinställning för hur licenser laddas.

Licensiering & vattenstämpel

LicensstatusUppstartCertifierad signaturVisuell signatur
Betald licens som beviljar Signer, certifikat konfigureratStartarFörseglad med ditt certifikat, ren (watermarked: false)Ren
Betald licens som beviljar Signer, inget certifikatStartarAvvisad: No signing certificate configured.Ren
Betald licens, certifikat utgånget eller ännu inte giltigtStartar (med widgeten aktiverad, en varning loggas)Avvisad: The signing certificate expired on yyyy-MM-dd.Ren
Tillfällig Demo/NFR‑licens, aktiv eller utgångenStartarFörseglad med det inbyggda demo‑certifikatet, vattenstämplad (watermarked: true)Vattenstämplad
Ingen licens, en äldre TRIAL‑fil, en licens utan Signer, eller en betald licens utanför sitt versionsfönsterAddDoconut() kastar——

Regeln är densamma för C#‑fasaden och widgeten: utdata är vattenstämplade när licensen inte är en betald visningslicens eller är tillfällig. Under en tillfällig licens signerar pluginet alltid med sitt inbyggda demo‑certifikat, och eventuella certifikat du konfigurerar används inte.

Demo‑certifikatet skapar en äkta försegling, men PDF‑läsare litar inte på det. En integration kan byggas och testas från början till slut med en utvärderingslicens; för att få ren, pålitlig utdata behöver du både en betald licens och ditt eget signeringscertifikat.

Användning från C#

DocumentSigner registreras av AddDoconut() och löses upp via beroendeinjektion. Dess konstruktor är intern, så du får aldrig new den. Att lösa den utan AddPlugin<SignerPlugin>() kastar 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 standardvärdet är Certified (synlig signatur + digitalt sigill); WordOutput standardvärdet är 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 tar källströmmen, dess filändelse (".pdf" eller ".docx"), begäran och certifikatet för detta anrop. Facaden läser inte SignerWidgetOptions.SigningCertificate; den inställningen är för widgeten. Skicka null under en demolicens eller i Visual‑läge.

SignResult innehåller det signerade dokumentet som en sökbar ström, plus dess Extension (".pdf" eller ".docx") så att du kan namnge filen. Du äger strömmen: disponera den när du är klar.

En Visual‑signatur stämplar endast bilden och kräver inget certifikat:

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

En Word‑källa signeras till PDF om du inte begär Word‑utdata. Namnge resultatet från 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 kastar ett undantag istället för att returnera när anropet inte kan lyckas:

UndantagMeddelandeNär
InvalidOperationExceptionNo signing certificate configured.Certifierat läge, en betald licens, och inget certifikat skickat
InvalidOperationExceptionThe signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd.Certifierat läge med ett certifikat utanför dess giltighetsperiod
ArgumentExceptionThe sign request is invalid: the visible signature needs PNG bytes and the placement must be a normalized rectangle on a 1-based page.Tomma PNG‑bytes, eller en placering som inte är giltig
NotSupportedExceptionThe signer supports PDF and Word (.docx) documents; got '{extension}'.Alla andra källtyper

Signeringslägen, Word‑utdata och certifikat

Signeringslägen

SignRequest.Mode väljer om signaturen är förseglad.

LägeVad den producerarCertifikatVerifierbar
SignatureMode.Certified (default)Den synliga signaturen plus en digital förseglingKrävs under en betald licensJa
SignatureMode.VisualEndast den synliga signaturenAldrig behövsNej: den är en bild

Använd Certified när signaturen måste vara verifierbar: godkännanden, kontrakt, allt en verifierare behöver kontrollera för identitet och integritet. Använd Visual när du bara behöver signaturens utseende, eller saknar certifikat. En tillfällig licens vattenmärker båda.

PDF‑förseglingar är PKCS#7‑fristående signaturer (adbe.pkcs7.detached) med SHA-256, för RSA‑ eller ECDSA‑nycklar. De innehåller utfärdarens certifikat som finns i din PFX, så en läsare som litar på ditt rotcertifikat kan bygga kedjan. Word‑inhemska förseglingar är OOXML‑paket‑signaturer och innehåller endast signerarens certifikat.

Word-dokument

För en .docx-källa väljer SignRequest.WordOutput utdata. Den ignoreras för PDF-källor, som alltid producerar en PDF.

UtdataVad händerVerifieringsstöd
WordOutput.Pdf (default)Dokumentet konverteras till PDF, signeras och förseglasBrett: en signerad PDF verifieras överallt
WordOutput.DocxDokumentet förblir Word: signaturbilden placeras i det, plus en OOXML-paketunderskriftBegränsat: inte alla visare visar OOXML-paketunderskrifter

Behåll PDF om inte mottagaren behöver en redigerbar Word-fil och accepterar det begränsade verifieringsstödet.

Certifikatinställning

För att försegla med din egen identitet, ge pluginet en PFX (PKCS#12)‑fil som innehåller den privata nyckeln. För widgeten, ange SignerWidgetOptions.SigningCertificate; för C#‑fasaden, skicka certifikatet till SignAsync. Tillhandahåll antingen byte‑sekvensen eller en sökväg, samt lösenordet:

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

Certifikatet hålls endast i minnet. Det loggas aldrig, returneras inte till en klient eller sparas, och lösenordet visas aldrig i en loggrad eller felmeddelande.

Krav:

  • Ett PFX / PKCS#12‑paket med sin privata nyckel. En fil som endast innehåller publik nyckel (.cer, .crt) kan inte signera. Exportera utfärdarens kedja tillsammans med den, så att PDF‑förseglingar kan bära den.
  • Det korrekta lösenordet.
  • Inom dess giltighetsperiod. Ett utgånget eller ännu inte giltigt certifikat stoppar inte appen: det loggas som en Varning vid start, och certifierade signaturer avvisas tills det ersätts. Visuella signaturer påverkas inte.
  • Utfärdat för dokumentsignering: en nyckelanvändning med digital signatur eller icke‑förnekelse, och en utökad nyckelanvändning, om den finns, som tillåter dokumentsignering, e‑postskydd eller klientautentisering. Ett certifikat som utfärdats för något annat, såsom ett TLS‑serversertifikat, kan fortfarande signera, men det loggas som en Varning och PDF‑läsare markerar signaturen.
  • Hårdvarutoken, smartkort, HSM:er och Windows‑certifikatlagring stöds inte. Exportera certifikatet, med dess privata nyckel och kedja, till en PFX.

Skapa en PFX från ett certifikat och dess privata nyckel med OpenSSL:

bash
openssl pkcs12 -export -out signing.pfx -inkey private.key -in certificate.crt
# Exportlösenordet du blir ombedd att ange är SigningCertificate.Password.

Exportera ett från Windows‑certifikatlagring: öppna certmgr.msc och hitta certifikatet (dess ikon visar en nyckel när den privata nyckeln finns). Högerklicka på det, välj Alla uppgifter → Exportera…, markera Ja, exportera den privata nyckeln, välj Personlig informationsutbyte – PKCS #12 (.PFX) och ange ett lösenord.

Startkontroller

När widgeten är aktiverad kontrolleras certifikatet i SignerWidgetOptions.SigningCertificate en gång, inuti AddDoconut(), så en felkonfigurerad PFX misslyckas vid start istället för vid den första signaturen. Tre problem kastar ett InvalidOperationException:

MeddelandeÅtgärd
Doconut Signer: the certificate file was not found at '{path}'.Korrigera PfxPath; se till att filen är distribuerad och läsbar för appens konto
Doconut Signer: the signing certificate could not be opened — the password is incorrect or the file is not a valid .pfx.Kontrollera lösenordet; se till att filen är en riktig .pfx, inte en .cer eller .pem
Doconut Signer: the signing certificate has no private key. Re-export the .pfx INCLUDING the private key.Exportera PFX‑filen igen med den privata nyckeln

Annars skriver värden en rad till loggen när den startar. Information när certifikatet är klart:

text
Doconut Signer: using certificate '{subject}' (valid until yyyy-MM-dd). Signatures are digitally sealed.

En Varning när det är utgånget, ännu inte giltigt, eller inte utfärdat för dokumentsignering:

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.

Och Information när inget certifikat är konfigurerat:

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.

Den sista raden är densamma för alla licenser. Under en betald licens används aldrig democertifikatet: utan certifikat fungerar endast visuella signaturer.

C#‑fasaden kontrolleras inte vid start. Certifikatet du skickar till SignAsync läses när du signerar, så en felaktig sökväg eller lösenord får anropet att misslyckas.

Drop-in widget

Enable the endpoints

Widgetens ?sign=open|run|download‑slutpunkter är avstängda som standard. Aktivera dem bredvid plugin‑registreringen:

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
    options.AddSignerWidget(widget =>
    {
        widget.MaxUploadMb = 25;           // standard
        widget.MaxSignatureImageKb = 512;  // standard
        // widget.SigningCertificate: se certifikatinställning; lämna den null för demo (vattenstämpel) signering
    });
});

AddSignerWidget() utan argument aktiverar widgeten med standardinställningarna. Den ger inte signering i sig själv: den behöver AddPlugin<SignerPlugin>(), eller AddDoconut() kastar:

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.

Utan AddSignerWidget() svarar varje ?sign=‑begäran med 404. Skriptet levereras fortfarande, så widgeten laddas och ritar sin droppzon, och rapporterar sedan Signing is not enabled on this server. vid sin första begäran.

Embed it

UseDoconutResources() levererar skriptet på {ResourcesPath}/js/doconutSigner.js (standard /doconut-res/js/doconutSigner.js). Det är en enda, fristående fil utan beroenden:

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) tar en CSS‑väljare eller ett element, kastar om monteringen inte hittas, och returnerar ett handtag.

Signatören laddar upp en PDF‑ eller .docx‑fil, bygger en signatur (Rita på en canvas, Skriv ett namn i ett signaturtypsnitt, eller Bild från en PNG, JPG eller GIF), drar och ändrar storlek på den på sidan, och signerar samt laddar ner resultatet. Widgeten skickar alltid signaturen som en PNG; en uppladdad bild konverteras i webbläsaren till en PNG som passar 520×160.

Options

OptionTypeDefaultNotes
basePathstring'/doconut'Var ?sign=‑slutpunkterna och förhandsgranskningsbilderna levereras
resPathstring'/doconut-res'Reserverad; widgeten paketerar sin egen CSS
maxUploadMbnumber25Endast klient‑sida kontroll, så en för stor fil misslyckas snabbt. Servergränsen är MaxUploadMb i AddSignerWidget
maxSignatureKbnumber512Klient‑sida gräns för Bild‑läget. Håll den lika med serverns MaxSignatureImageKb
previewWidthnumber560Pixelbredd på sidans förhandsgranskning
licenseUrlstring | nullnullGör demo‑vattenstämpel‑meddelandet till en länk till den här URL‑en
signatureModestring'certified'Initial signaturtyp: 'certified' eller 'visual'. Alla andra värden blir 'certified'
showSignatureModeTogglebooleantrueVisar valet Digital signatur / Endast visuell. Med false signerar widgeten med signatureMode
wordOutputstring'pdf'Initialt utdata för .docx‑källor: 'pdf' eller 'docx'. Alla andra värden blir 'pdf'
showOutputFormatTogglebooleantrueVisar valet PDF / Word, endast för .docx‑källor. Med false använder widgeten wordOutput
labelsobject{}Åsidosätter någon delmängd av de engelska strängarna

Att dölja en växel inaktiverar inte funktionen; den fixerar värdet. Två vanliga konfigurationer:

javascript
// Båda växlarna visas, digital signatur som standard: en fullständig självbetjäningssignatör.
Doconut.signer('#host', { basePath: '/doconut', licenseUrl: '/pricing' });
javascript
// Endast visuell, ingen växel: en enkel stämpel utan digital signatur erbjuds.
Doconut.signer('#host', {
  basePath: '/doconut',
  signatureMode: 'visual',
  showSignatureModeToggle: false
});

Callbacks

CallbackFires whenPayload
onReadyEn gång, vid montering (inte igen på reset())—
onSourceLoadedFilen öppnas och dess förhandsgranskning visas{ file: { token, name, pages, ext } }
onSignedSignering lyckas{ downloadToken, downloadName, watermarked }
onDownloadVid varje klick på Ladda ner{ downloadName, downloadToken }
onErrorEtt öppnings-, signerings- eller nedladdningssteg misslyckas, eller en fil i Bild‑läge är för stor{ message }

En återanrop som kastar fångas och loggas; den bryter aldrig widgetens flöde.

Imperativ hantering

MetodBeteende
reset()Återgår till droppskärmen och rensar det aktuella flödet. Avfyrar inte onReady igen. Ingen åtgärd efter destroy()
loadFile(file)Startar flödet med en File. Ingen åtgärd om inte widgeten är på sin droppskärm; anropa reset() först om det behövs
destroy()Tar bort lyssnarna, tömmer monteringen och fryser instansen
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());

Etiketter

Varje sträng har en engelsk standard; labels åsidosätter någon delmängd och resten förblir engelska. Fragment som ändras vid körning använder {placeholders}, såsom uploading: 'Uploading {name}…' och pages: '{n} pages'.

NyckelEngelsk standard
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

Ytterligare nycklar täcker placeringssteget, felskärmen, den länkade formen av demomeddelandet (demoNoticePrefix, demoNoticeLink, demoNoticeSuffix) och aria-live-meddelandena.

När open eller run svarar 404 utan JSON‑fel, visar widgeten signingNotEnabled. Ett JSON‑fel från servern har alltid företräde, så meddelanden som en utgången uppladdning förblir synliga.

Tematisering

Widgeten lägger till klassen dsw på sitt monterings‑element och läser sina färger, radie och typsnitt från CSS‑anpassade egenskaper, så du kan tematisera den utan att röra dess interna delar:

css
#host.dsw {
  --dsw-accent: #b0522b;       /* länkar, fokus, aktivt läge */
  --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;   /* det Type läge */
}

Standardvärden: --dsw-accent: #2b6cb0, --dsw-bg: #ffffff, --dsw-fg: #1a202c, --dsw-muted: #718096, --dsw-border: #cbd5e0, --dsw-radius: 8px, ett system‑UI‑typsnitt och ett kursivt signaturtypsnitt.

Bygg ditt eget frontend

Widgeten är en klient för detta HTTP‑avtal. Alla tre rutter ligger under sökvägen där UseDoconut() är monterad (vanligtvis /doconut), och de svarar 404 tills AddSignerWidget() anropas. Fel innehåller en JSON‑kropp, { "error": "..." }, förutom där tabellen säger "endast status". Ett okänt ?sign=‑värde svarar 400.

RuttSyfteSvar vid lyckat anrop
POST ?sign=open (multipart, en fil)Ladda upp en PDF eller .docx och öppna den för förhandsgranskning200 — { token, name, pages, ext }
POST ?sign=run (JSON‑kropp)Signera den uppladdade filen200 — { downloadToken, downloadName, watermarked }
GET ?sign=download&token=<downloadToken>Strömma den signerade filen200 — filen, Content-Disposition: attachment, Cache-Control: no-store

ext i open‑svaret inkluderar den inledande punkten (".docx"). Sidans förhandsgranskning använder den standardiserade bildrutt för visaren, {basePath}?token={token}&page={n}&thumb=1&width={px}; den visade sidan blir placement.page.

Kroppen för run:

json
{
  "token": "GUID-from-open",
  "signature": { "kind": "Drawn", "payload": "<base64 PNG, no data: prefix>" },
  "placement": { "page": 1, "x": 0.58, "y": 0.80, "w": 0.32, "h": 0.12 },
  "meta": { "signerName": "Ada Lovelace", "reason": "I approve", "location": "London, UK" },
  "wordOutput": "pdf",
  "mode": "certified"
}
FältAnteckningar
tokenToken från open
signature.kindDrawn, Typed eller Image, skiftlägesokänsligt; allt annat blir Drawn. Endast en ledtråd: nyttolasten är alltid en PNG
signature.payloadEn ren base64 PNG, utan data:‑prefix. Den måste vara en riktig PNG och får inte vara större än MaxSignatureImageKb när den avkodas
placement.page1‑baserad
placement.x / y / w / hNormaliserad 0..1 från det övre vänstra hörnet, med x + w ≤ 1 och y + h ≤ 1
meta.signerName / reason / locationValfritt. Var och en trimmas, ett tomt värde tas bort, och varje värde kapas till 256 tecken
wordOutputpdf (standard) eller docx; ignoreras för PDF‑källor. Allt annat blir pdf
modecertified (standard) eller visual. Allt annat blir certified

downloadName följer utdata: <source>-signed.pdf eller <source>-signed.docx, och download skickar den matchande Content-Type.

Den uppladdade källan och det signerade resultatet sparas vardera i 30 minuter. Därefter svarar run och download med 404 och filen måste öppnas igen. Alla token är GUID‑er.

RuttStatusNärKropp
any404Widgeten är inte aktiveradendast status
any405Fel verb (open och run kräver POST, download kräver GET)endast status
open400Inte en multipart‑uppladdningExpected a multipart file upload.
open400Ingen fil, eller en tom filNo file uploaded.
open400Allt annat än .pdf eller .docxSigning supports PDF and Word (.docx) files only.
open413Uppladdningen överskrider MaxUploadMbFile is too large.
run400Kroppen är inte giltig JSON, eller är tomMalformed request. / Empty request.
run400Token saknas eller är inte en GUIDInvalid token.
run404Uppladdningen har gått ut eller öppnades aldrigUpload expired — please re-open the file.
run400Ingen signatur, eller ingen placeringNo signature supplied. / No placement supplied.
run400Payload är inte base64, är tom, för stor, eller inte en PNGSignature image is not valid base64. / Signature image is empty. / Signature image is too large. / The signature image must be a PNG.
run400Placeringen är utanför sidanThe signature or its placement is invalid.
run400Certifierat läge, en betald licens och inget certifikatNo signing certificate configured.
run400Certifierat läge med ett certifikat utanför dess giltighetsperiodThe signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd.
open, run500Bearbetning misslyckadesEtt sanerat meddelande
download400Token saknas eller är inte en GUIDendast status
download404Okänd eller utgången tokenendast status

En komplett rundresa med fetch:

javascript
// file: filen att signera; pngBase64: signaturen som en ren base64 PNG, utan data:-prefix,
// till exempel canvas.toDataURL('image/png').split(',')[1].
async function signFile(file, pngBase64) {
  const base = '/doconut';

  // 1. open: ladda upp filen
  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: signera den
  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: hämta den signerade filen
  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);
}

Slutpunkterna är same-origin: den här versionen har inget CORS‑stöd. Servera ditt UI och widget‑skriptet från samma origin som Doconut, eller reverse‑proxy båda /doconut‑vägarna (middleware‑vägen och resurser‑vägen) under ditt UI:s origin.

I produktion

  1. Installera pluginet bredvid kärnpaketet, i samma version: dotnet add package Doconut.NET8.Signer.

  2. Lägg till licensfilen. Placera Doconut.Viewer.Signer.lic i samma mapp som Doconut.Viewer.lic.

  3. Skaffa ditt certifikat som en PFX med dess privata nyckel och utfärdar‑kedja, från en certifikatutfärdare eller din organisations egna PKI. För att prova först, använd en demolicens (det inbyggda democertifikatet, med vattenstämpel) eller en självsignerad PFX.

  4. Läs certifikatet från konfigurationen, så att en ändring aldrig kräver en kodändring:

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

    Behåll .pfx utanför wwwroot, och håll lösenordet borta från appsettings.json: användarhemligheter i utveckling (dotnet user-secrets set "DoconutSigner:Password" "<password>"), en miljövariabel (DoconutSigner__Password) eller ett valv i produktion.

  5. Kontrollera startloggen. Den bör visa using certificate '{subject}' (valid until …). Signatures are digitally sealed.. En varning betyder istället att certifikatet är utgånget, ännu inte giltigt, eller inte utfärdat för dokumentsignering.

Förtroende i PDF‑läsare. En läsare visar signaturen som giltig när den litar på certifikatets rot. Med din organisations PKI gäller det på varje maskin som litar på din rot, vilket vanligtvis är varje maskin inom organisationen. Certifikat som Adobe litar på på någon maskin (Adobe Approved Trust List) utfärdas, såvitt vi vet, med den privata nyckeln på en hårdvarutoken eller HSM, vilket detta plugin inte kan använda: det signerar endast från en PFX. Bekräfta med din certifikatleverantör innan du förlitar dig på den typen av förtroende.

Webbfarmer

Widgeten behåller varje uppladdning och dess resultat i minnet på noden som levererade open. Bakom en lastbalanserare utan sticky sessions kan en senare run, download eller förhandsgranskningsförfrågan nå en annan nod och inte hitta uppladdningen. Registrera den delade, krypterade widgetlagringen en gång, efter AddDoconut():

csharp
byte[] farmKey = Convert.FromBase64String(builder.Configuration["Doconut:FarmKey"]);

builder.Services.AddDoconutDistributedWidgets(store =>
{
    store.RootPath = @"\\fileshare\doconut";   // en mapp som varje nod kan läsa och skriva
    store.FarmKey = farmKey;                   // minst 32 byte, identisk på varje nod
    // store.Ttl = TimeSpan.FromMinutes(30);   // hur länge en uppladdning behålls (standardvärdet)
});
  • En enskild server behöver inget: utan detta anrop används minneslagringen.
  • Uppladdningar och resultat är krypterade i vila på delningen (AES-256, encrypt-then-MAC), och varje fil är bunden till sin token, så att en token aldrig kan läsa en annans fil.
  • FarmKey måste vara minst 32 byte och samma på varje nod. Ladda den från en hemlig lagring; hårdkoda den aldrig. Registrering kastar ett ArgumentException när RootPath saknas eller FarmKey är kortare än 32 byte.
  • Peka RootPath på samma delade plats som den distribuerade visaren använder, och ge varje nod samma signeringscertifikat.

API-referens

Fasaden och widgetalternativen finns i Doconut-namnutrymmet; begäran- och resultattyperna finns i Doconut.Core.Models.Signing. SignerPlugin finns i 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);
}

Lösts via beroendeinjektion; konstruktorn är intern. sourceExtension är ".pdf" eller ".docx". Under en betald licens används cert och utdata är rena; under en tillfällig licens används det inbyggda democertifikatet, cert ignoreras, och utdata är vattenstämplad.

SignRequest

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

En synlig signatur placerad en gång, plus valfri signerarmetadata.

VisibleSignature and SignatureKind

csharp
public sealed record VisibleSignature(SignatureKind Kind, byte[] PngBytes)
{
    public bool IsValid { get; }   // PngBytes är inte tom
}

public enum SignatureKind { Drawn, Typed, Image }

PngBytes är en PNG för varje typ. En ritad eller skriven signatur är transparent; en uppladdad bild behåller den transparens den hade, så en opak JPG förblir opak. Kind är bara en ledtråd.

SignaturePlacement

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

Page är 1-baserad; X, Y, W och H är normaliserade 0..1 från det övre vänstra hörnet.

SignatureMode and WordOutput

csharp
public enum SignatureMode { Certified, Visual }   // Certified är standard
public enum WordOutput { Pdf, Docx }              // Pdf är standard; ignoreras för PDF-källor

SignResult

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

Det signerade dokumentet som en sökbar ström, samt dess filändelse med punkt (".pdf" eller ".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 är inte tom, eller PfxPath är inte tom
}

Ställ in antingen PfxBytes eller PfxPath, samt Password.

SignerWidgetOptions

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

Ställ in via DoconutOptions.AddSignerWidget(Action<SignerWidgetOptions>? configure = null), som returnerar DoconutOptions så att anrop kan kedjas. En null SigningCertificate betyder democertifikatet under en tillfällig licens, och visuella signaturer endast under en betald.

Felsökning

SymptomOrsakÅtgärd
AddDoconut() kastar The Signer plugin is registered via AddPlugin but no active license grants Signer.Ingen licens, en TRIAL-fil, en licens utan Signer, eller en betald licens utanför dess versionsfönsterInstallera en licens som ger Signer, eller ta bort AddPlugin<SignerPlugin>()
AddDoconut() kastar AddSignerWidget() was called but the Signer plugin is not registered.Widgeten är aktiverad utan dess pluginLägg till options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>()
AddDoconut() kastar Doconut Signer: the certificate file was not found at '{path}'.PfxPath pekar på en saknad filFixa sökvägen; distribuera filen där appens konto kan läsa den
AddDoconut() kastar Doconut Signer: the signing certificate could not be opened — the password is incorrect or the file is not a valid .pfx.Fel lösenord, eller inte en PKCS#12-filKontrollera lösenordet; använd ett riktigt .pfx
AddDoconut() kastar Doconut Signer: the signing certificate has no private key. Re-export the .pfx INCLUDING the private key.PFX:en exporterades utan sin privata nyckelExportera den igen med den privata nyckeln
Löser DocumentSigner kastar No IDocumentSigner is registered.SignerPlugin är inte registreradLägg till AddPlugin<SignerPlugin>() i AddDoconut()
Utdata är vattenstämpladLicensen är tillfällig (Demo/NFR)Använd en betald licens som ger Signer
run svarar 400 No signing certificate configured.En betald licens, Certified-läge, och inget certifikatKonfigurera SigningCertificate, eller signera i Visual-läge
run svarar 400 The signing certificate expired on yyyy-MM-dd.Certifikatet är föråldratByt ut det; visuella signaturer fortsätter fungera under tiden
Loggen säger att utdata "använder det inbyggda democertifikatet", men en betald licens vägrar Certified-signaturerDen raden skrivs när inget certifikat är konfigurerat, oavsett licensKonfigurera SigningCertificate
Widgeten laddas men säger Signing is not enabled on this server.AddSignerWidget() anropades inte, eller basePath matchar inte där UseDoconut() är monteradAnropa AddSignerWidget(); fixa basePath
run svarar 400 The signature image must be a PNG., Signature image is not valid base64. eller Signature image is too large.En anpassad UI skickade en data:-URL, en JPG, eller mer än MaxSignatureImageKbSkicka en ren base64 PNG inom gränsen
open svarar 413 File is too large.Uppladdningen överskrider MaxUploadMbHöj MaxUploadMb i AddSignerWidget; widgetens maxUploadMb är bara en klient‑sidokontroll
run eller download svarar 404 Upload expired — please re-open the file.30‑minutersfönstret har löpt ut, eller en webbfarmnod har inte uppladdningenÖppna filen igen; i en farm, registrera AddDoconutDistributedWidgets
En signerad .docx visar ingen signatur i vissa visareWord-utdata bär en OOXML-paket‑signatur, som många visare inte visarSignera till PDF, som standard
PDF-läsare säger att signerarens identitet är okändLäsaren litar inte på certifikatets rot (democertifikatet är aldrig betrott)Använd ett certifikat från en rot som dina läsare litar på
Widgeten misslyckas när UI:n är på en annan originEndpoints har ingen CORS‑stödServera UI:n från samma origin, eller reverse-proxy Doconut‑vägarna
Temat tillämpas inteSelektorn riktar sig mot ett element inuti mountenRikta mot själva mounten: #host.dsw eller #host

Var den här sidan hjälpsam?