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, som standard, förseglar det 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.
| Yta | Använd den 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.
Installera paketet
Installera den senaste stabila Signer‑pluginet:
dotnet add package Doconut.NETStandard.SignerFör att låsa pluginet till den version som denna dokumentation beskriver, ange versionen separat:
dotnet add package Doconut.NETStandard.Signer --version 26.10.0Behåll Signer‑paketet på samma version som Doconut.NETStandard. Paket‑ID:t är Doconut.NETStandard.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.
Registrera pluginet
Precis som varje Doconut‑plugin registreras Signer med AddPlugin<TPlugin>() i AddDoconut():
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 opt‑in, 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:
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 när det saknas 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 License Setup för hur licenser laddas.
Licensiering & vattenstämpel
| Licensstatus | Start | Certifierad signatur | Visuell signatur |
|---|---|---|---|
Betald licens som ger Signer, certifikat konfigurerat | Startar | Förseglad med ditt certifikat, ren (watermarked: false) | Ren |
Betald licens som ger Signer, inget certifikat | Startar | Nekad: No signing certificate configured. | Ren |
| Betald licens, certifikat utgånget eller ännu inte giltigt | Startar (med widgeten aktiverad, en varning loggas) | Nekad: The signing certificate expired on yyyy-MM-dd. | Ren |
| Tillfällig Demo/NFR‑licens, aktiv eller utgången | Startar | Förseglad med det inbyggda demo‑certifikatet, vattenmärkt (watermarked: true) | Vattenmärkt |
Ingen licens, en äldre TRIAL‑fil, en licens utan Signer, eller en betald licens utanför sitt versionsfönster | AddDoconut() kastar | — | — |
Regeln är densamma för C#‑fasaden och widgeten: utdata är vattenmärkt 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 hämtas via beroendeinjektion. Dess konstruktor är intern, så aldrig new den. Att hämta den utan AddPlugin<SignerPlugin>() kastar 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 har som standardvärde Certified (synlig signatur + digitalt sigill); WordOutput har som standardvärde 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: frigör den när du är klar.
En Visual-signatur stämplar endast bilden och kräver inget certifikat:
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:
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 kastar ett undantag istället för att returnera när anropet inte kan lyckas:
| Undantag | Meddelande | När |
|---|---|---|
InvalidOperationException | No signing certificate configured. | Certifierat läge, en betald licens, och inget certifikat skickat |
InvalidOperationException | The 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 |
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. | Tomma PNG-bytes, eller en placering som inte är giltig |
NotSupportedException | The 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äge | Vad det producerar | Certifikat | Verifierbar |
|---|---|---|---|
SignatureMode.Certified (default) | Den synliga signaturen plus en digital försegling | Krävs under en betald licens | Ja |
SignatureMode.Visual | Endast den synliga signaturen | Aldrig behövd | Nej: det är en bild |
Använd Certified när signaturen måste kunna bevisas: 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 bär utfärdarens certifikat som finns i din PFX, så en läsare som litar på din rot kan bygga kedjan. Word-inhemska förseglingar är OOXML-paket signaturer och bär endast signerarens certifikat.
Word-dokument
För en .docx källa väljer SignRequest.WordOutput utdata. Det ignoreras för PDF‑källor, som alltid producerar en PDF.
| Utdata | Vad som händer | Verifieringsstöd |
|---|---|---|
WordOutput.Pdf (default) | Dokumentet konverteras till PDF, sedan signeras och förseglas | Brett: en signerad PDF verifieras överallt |
WordOutput.Docx | Dokumentet förblir Word: signaturbilden placeras i det, plus en OOXML‑paket‑signatur | Begränsat: inte alla visare visar OOXML‑paket‑signaturer |
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 bytena eller en sökväg, samt lösenordet:
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"],
};
});
});Certifikatet hålls endast i minnet. Det loggas aldrig, returneras aldrig till en klient eller sparas, och lösenordet visas aldrig i en loggrad eller ett felmeddelande.
Krav
- Ett PFX / PKCS#12‑paket med dess privata nyckel. En fil som bara innehåller en publik nyckel (
.cer,.crt) kan inte signera. Exportera utfärdarens kedja 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, samt en utökad nyckelanvändning (om den finns) som tillåter dokumentsignering, e‑postskydd eller klientautentisering. Ett certifikat utfärdat för något annat, t.ex. ett TLS‑servercertifikat, signerar fortfarande, men det loggas som en Varning och PDF‑läsare flaggar 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:
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 (ikonen visar en nyckel när den privata nyckeln finns). Högerklicka på det, välj All Tasks → Export…, markera Yes, export the private key, välj Personal Information Exchange – 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 snarare än vid den första signaturen. Tre problem ger en 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 |
Om inget av ovanstående inträffar skriver värden en rad till loggen när den startar. Information när certifikatet är redo:
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:
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:
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 fel 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:
builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
options.AddSignerWidget(widget =>
{
widget.MaxUploadMb = 25; // standardvärdet
widget.MaxSignatureImageKb = 512; // standardvärdet
// widget.SigningCertificate: se certifikatinställning; lämna den null för demo (med vattenstämpel) signering
});
});AddSignerWidget() utan argument aktiverar widgeten med standardinställningarna. Den ger inte signering i sig själv: den behöver AddPlugin<SignerPlugin>(), annars kastar AddDoconut():
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=-förfrågan med 404. Skriptet levereras fortfarande, så widgeten laddas och ritar sin droppzon, och rapporterar sedan Signing is not enabled on this server. på sin första förfrågan.
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:
<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, skapar 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 och 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
| Alternativ | Typ | Standard | Noteringar |
|---|---|---|---|
basePath | string | '/doconut' | Var de ?sign=-slutpunkterna och förhandsgranskningsbilderna levereras |
resPath | string | '/doconut-res' | Reserverad; widgeten paketerar sin egen CSS |
maxUploadMb | number | 25 | Endast klient‑sidokontroll, så en för stor fil misslyckas snabbt. Serverns gräns är MaxUploadMb i AddSignerWidget |
maxSignatureKb | number | 512 | Klient‑sidans gräns för Bild‑läget. Håll den lika med serverns MaxSignatureImageKb |
previewWidth | number | 560 | Pixelbredd för sidans förhandsgranskning |
licenseUrl | string | null | null | Omvandlar demo‑vattenstämpel‑meddelandet till en länk till denna URL |
signatureMode | string | 'certified' | Initial signaturtyp: 'certified' eller 'visual'. Alla andra värden blir 'certified' |
showSignatureModeToggle | boolean | true | Visar valet Digital signatur / Endast visuell. Med false signerar widgeten med signatureMode |
wordOutput | string | 'pdf' | Initialt utdata för .docx-källor: 'pdf' eller 'docx'. Alla andra värden blir 'pdf' |
showOutputFormatToggle | boolean | true | Visar valet PDF / Word, endast för .docx-källor. Med false använder widgeten wordOutput |
labels | object | {} | Å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:
// Båda växlarna visas, digital signatur som standard: en fullständig självbetjäningssignatör.
Doconut.signer('#host', { basePath: '/doconut', licenseUrl: '/pricing' });// Endast visuell, ingen växel: en enkel stämpel utan digital signatur erbjuds.
Doconut.signer('#host', {
basePath: '/doconut',
signatureMode: 'visual',
showSignatureModeToggle: false
});Återuppringningar
| Återuppringning | Utlöses när | Data |
|---|---|---|
onReady | En gång, vid montering (inte igen på reset()) | — |
onSourceLoaded | Filen öppnas och dess förhandsgranskning visas | { file: { token, name, pages, ext } } |
onSigned | Signering lyckas | { downloadToken, downloadName, watermarked } |
onDownload | Vid varje klick på Ladda ner | { downloadName, downloadToken } |
onError | Ett öppnings-, signerings- eller nedladdningssteg misslyckas, eller en fil i bildläge är för stor | { message } |
En återuppringning som kastar ett undantag fångas och loggas; den bryter aldrig widgetens flöde.
Imperativ hantering
| Metod | Beteende |
|---|---|
reset() | Återgår till droppskärmen och rensar det aktuella flödet. Avfyrar inte onReady igen. Ingen operation efter destroy() |
loadFile(file) | Startar flödet med en File. Ingen operation om inte widgeten är på droppskärmen; anropa reset() först om det behövs |
destroy() | Tar bort lyssnarna, tömmer monteringen och fryser instansen |
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'.
| Nyckel | Engelsk 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 |
Ytterligare nycklar täcker placeringssteget, felskärmen, den länkade formen av demovarningen (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 dess färger, radie och typsnitt från CSS‑anpassade egenskaper, så du kan tematisera den utan att röra dess interna delar:
#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; /* Type-läget */
}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 med 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 med 400.
| Rutt | Syfte | Framgångssvar |
|---|---|---|
POST ?sign=open (multipart, one file) | Ladda upp en PDF eller .docx och öppna den för förhandsgranskning | 200 — { token, name, pages, ext } |
POST ?sign=run (JSON body) | Signera den uppladdade filen | 200 — { downloadToken, downloadName, watermarked } |
GET ?sign=download&token=<downloadToken> | Strömma den signerade filen | 200 — filen, Content-Disposition: attachment, Cache-Control: no-store |
ext i open‑svaret inkluderar den inledande punkten (".docx"). Sidans förhandsgranskning använder standard‑visnings‑bild‑rutten, {basePath}?token={token}&page={n}&thumb=1&width={px}; den visade sidan blir placement.page.
run‑kroppen:
{
"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ält | Anteckningar |
|---|---|
token | Token från open |
signature.kind | Drawn, Typed eller Image, skiftlägesokänsligt; allt annat blir Drawn. Endast en ledtråd: payload är alltid en PNG |
signature.payload | En 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.page | 1‑baserad |
placement.x / y / w / h | Normaliserad 0..1 från övre‑vänstra hörnet, med x + w ≤ 1 och y + h ≤ 1 |
meta.signerName / reason / location | Valfritt. Var och en trimmas, ett tomt värde tas bort, och varje begränsas till 256 tecken |
wordOutput | pdf (standard) eller docx; ignoreras för PDF‑källor. Allt annat blir pdf |
mode | certified (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.
| Rutt | Status | När | Kropp |
|---|---|---|---|
| any | 404 | Widgeten är inte aktiverad | endast status |
| any | 405 | Fel HTTP‑verb (open och run kräver POST, download kräver GET) | endast status |
open | 400 | Inte en multipart‑uppladdning | Expected a multipart file upload. |
open | 400 | Ingen fil, eller en tom fil | No file uploaded. |
open | 400 | Allt annat än .pdf eller .docx | Signing supports PDF and Word (.docx) files only. |
open | 413 | Uppladdningen överskrider MaxUploadMb | File is too large. |
run | 400 | Kroppen är inte giltig JSON, eller är tom | Malformed request. / Empty request. |
run | 400 | Token saknas eller är inte en GUID | Invalid token. |
run | 404 | Uppladdningen har gått ut eller öppnades aldrig | Upload expired — please re-open the file. |
run | 400 | Ingen signatur, eller ingen placering | No signature supplied. / No placement supplied. |
run | 400 | Payload är inte base64, är tom, för stor, eller inte en 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 | Placeringen är utanför sidan | The signature or its placement is invalid. |
run | 400 | Certifierat läge, en betald licens och inget certifikat | No signing certificate configured. |
run | 400 | Certifierat läge med ett certifikat utanför dess giltighetsperiod | The signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd. |
open, run | 500 | Bearbetning misslyckades | Ett sanerat meddelande |
download | 400 | Token saknas eller är inte en GUID | endast status |
download | 404 | Okänd eller utgången token | endast status |
En komplett rundresa med fetch:
// 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
-
Installera pluginet bredvid kärnpaketet, i samma version:
dotnet add package Doconut.NETStandard.Signer. -
Lägg till licensfilen. Placera
Doconut.Viewer.Signer.lici samma mapp somDoconut.Viewer.lic. -
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.
-
Läs certifikatet från konfigurationen, så att ändra det aldrig kräver en kodändring:
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"] ?? "", }); });Behåll
.pfxutanförwwwroot, och håll lösenordet borta frånappsettings.json: användarsekrets i utveckling (dotnet user-secrets set "DoconutSigner:Password" "<password>"), en miljövariabel (DoconutSigner__Password) eller ett valv i produktion. -
Kontrollera startloggen. Den bör visa
using certificate '{subject}' (valid until …). Signatures are digitally sealed.. En varning betyder istället att certifikatet har gått ut, ännu inte är giltigt, eller inte utfärdat för dokumentunderskrift.
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.
Webbfarmar
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():
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 sparas (standardvärdet)
});- En enskild server behöver inget: utan detta anrop används den minnesbaserade lagringen.
- Uppladdningar och resultat är krypterade i vila på delningen (AES-256, encrypt-then-MAC), och varje fil är bunden till sin token, så en token kan aldrig läsa en annans fil.
FarmKeymåste vara minst 32 byte och samma på varje nod. Ladda den från en hemlig lagring; hårdkoda den aldrig. Registrering kastar ettArgumentExceptionnärRootPathsaknas ellerFarmKeyär kortare än 32 byte.- Peka
RootPathpå 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
public sealed class DocumentSigner
{
public Task<SignResult> SignAsync(
Stream source, string sourceExtension, SignRequest request,
SigningCertificate? cert = null, CancellationToken ct = default);
}Löst 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ämpad.
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
}En synlig signatur placerad en gång, plus valfri signerarmetadata.
VisibleSignature and SignatureKind
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 hint.
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 är 1-baserad; X, Y, W och H är normaliserade 0..1 från det övre vänstra hörnet.
SignatureMode and WordOutput
public enum SignatureMode { Certified, Visual } // Certified är standard
public enum WordOutput { Pdf, Docx } // Pdf är standard; ignoreras för PDF-källorSignResult
public sealed record SignResult(Stream Stream, string Extension);Det signerade dokumentet som en sökbar ström, och dess filändelse med punkten (".pdf" eller ".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 är inte tom, eller PfxPath är inte tom
}Ange antingen PfxBytes eller 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; }
}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
| Symptom | Orsak | Åtgärd |
|---|---|---|
AddDoconut() throws 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önster | Installera en licens som ger Signer, eller ta bort AddPlugin<SignerPlugin>() |
AddDoconut() throws AddSignerWidget() was called but the Signer plugin is not registered. | Widgeten är aktiverad utan dess plugin | Lägg till options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>() |
AddDoconut() throws Doconut Signer: the certificate file was not found at '{path}'. | PfxPath pekar på en saknad fil | Fixa sökvägen; distribuera filen där appens konto kan läsa den |
AddDoconut() throws 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-fil | Kontrollera lösenordet; använd en riktig .pfx |
AddDoconut() throws Doconut Signer: the signing certificate has no private key. Re-export the .pfx INCLUDING the private key. | PFX:en exporterades utan sin privata nyckel | Exportera den igen med den privata nyckeln |
Resolving DocumentSigner throws No IDocumentSigner is registered. | SignerPlugin är inte registrerad | Lägg till AddPlugin<SignerPlugin>() i AddDoconut() |
| The output is watermarked | Licensen är tillfällig (Demo/NFR) | Använd en betald licens som ger Signer |
run answers 400 No signing certificate configured. | En betald licens, Certified-läge, och inget certifikat | Konfigurera SigningCertificate, eller signera i Visual-läge |
run answers 400 The signing certificate expired on yyyy-MM-dd. | Certifikatet är föråldrat | Byt ut det; visuella signaturer fortsätter fungera under tiden |
| The log says the output "uses the built-in demo certificate", yet a paid license refuses Certified signatures | Den raden skrivs när inget certifikat är konfigurerat, oavsett licens | Konfigurera SigningCertificate |
The widget loads but says Signing is not enabled on this server. | AddSignerWidget() anropades inte, eller basePath matchar inte där UseDoconut() är monterad | Anropa AddSignerWidget(); fixa basePath |
run answers 400 The signature image must be a PNG., Signature image is not valid base64. or Signature image is too large. | En anpassad UI skickade en data:-URL, en JPG, eller mer än MaxSignatureImageKb | Skicka en ren base64 PNG inom gränsen |
open answers 413 File is too large. | Uppladdningen överskrider MaxUploadMb | Höj MaxUploadMb i AddSignerWidget; widgetens maxUploadMb är bara en klientkontroll |
run or download answers 404 Upload expired — please re-open the file. | 30-minutersfönstret har gått ut, eller en webbfarmnod har inte uppladdningen | Öppna filen igen; i en farm, registrera AddDoconutDistributedWidgets |
A signed .docx shows no signature in some viewers | Word-utdata innehåller en OOXML-paket signatur, som många visare inte visar | Signera till PDF, standard |
| PDF readers say the signer's identity is unknown | Läsaren litar inte på certifikatets rot (democertifikatet är aldrig betrott) | Använd ett certifikat från en rot som dina läsare litar på |
| The widget fails when the UI is on another origin | Slutpunkterna har ingen CORS-support | Servera UI från samma origin, eller reverse-proxy Doconut-sökvägarna |
| The theme does not apply | Selektorn riktar sig mot ett element inne i mounten | Rikta mot själva mounten: #host.dsw eller #host |
Var den här sidan hjälpsam?