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.
| Yta | Anvä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:
dotnet add package Doconut.NET8.SignerFör att låsa pluginet till den version som den här dokumentationen beskriver, ange versionen separat:
dotnet add package Doconut.NET8.Signer --version 26.10.0Behå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:
apt-get update && apt-get install -y libfontconfig1På 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():
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:
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
| Licensstatus | Uppstart | Certifierad signatur | Visuell signatur |
|---|---|---|---|
Betald licens som beviljar Signer, certifikat konfigurerat | Startar | Förseglad med ditt certifikat, ren (watermarked: false) | Ren |
Betald licens som beviljar Signer, inget certifikat | Startar | Avvisad: No signing certificate configured. | Ren |
| Betald licens, certifikat utgånget eller ännu inte giltigt | Startar (med widgeten aktiverad, en varning loggas) | Avvisad: 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, vattenstämplad (watermarked: true) | Vattenstämplad |
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 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>().
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:
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; // ".docx"SignAsync 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 den 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övs | Nej: 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.
| Utdata | Vad händer | Verifieringsstöd |
|---|---|---|
WordOutput.Pdf (default) | Dokumentet konverteras till PDF, signeras och förseglas | Brett: en signerad PDF verifieras överallt |
WordOutput.Docx | Dokumentet förblir Word: signaturbilden placeras i det, plus en OOXML-paketunderskrift | Begrä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:
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 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:
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:
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 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; // 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:
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:
<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
| Option | Type | Default | Notes |
|---|---|---|---|
basePath | string | '/doconut' | Var ?sign=‑slutpunkterna och förhandsgranskningsbilderna levereras |
resPath | string | '/doconut-res' | Reserverad; widgeten paketerar sin egen CSS |
maxUploadMb | number | 25 | Endast klient‑sida kontroll, så en för stor fil misslyckas snabbt. Servergränsen är MaxUploadMb i AddSignerWidget |
maxSignatureKb | number | 512 | Klient‑sida gräns för Bild‑läget. Håll den lika med serverns MaxSignatureImageKb |
previewWidth | number | 560 | Pixelbredd på sidans förhandsgranskning |
licenseUrl | string | null | null | Gör demo‑vattenstämpel‑meddelandet till en länk till den här URL‑en |
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
});Callbacks
| Callback | Fires when | Payload |
|---|---|---|
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 Bild‑läge är för stor | { message } |
En återanrop som kastar 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 å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 |
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 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:
#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.
| Rutt | Syfte | Svar vid lyckat anrop |
|---|---|---|
POST ?sign=open (multipart, en fil) | Ladda upp en PDF eller .docx och öppna den för förhandsgranskning | 200 — { token, name, pages, ext } |
POST ?sign=run (JSON‑kropp) | 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 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:
{
"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: nyttolasten ä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 det ö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 värde kapas 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 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.NET8.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 en ändring 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ändarhemligheter 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 ä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():
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.
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ö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
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 ledtråd.
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, samt dess filändelse med punkt (".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
}Ställ in antingen PfxBytes eller PfxPath, samt 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() 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önster | Installera 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 plugin | Lä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 fil | Fixa 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-fil | Kontrollera 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 nyckel | Exportera den igen med den privata nyckeln |
Löser DocumentSigner kastar No IDocumentSigner is registered. | SignerPlugin är inte registrerad | Lägg till AddPlugin<SignerPlugin>() i AddDoconut() |
| Utdata är vattenstämplad | Licensen ä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 certifikat | Konfigurera SigningCertificate, eller signera i Visual-läge |
run svarar 400 The signing certificate expired on yyyy-MM-dd. | Certifikatet är föråldrat | Byt 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-signaturer | Den raden skrivs när inget certifikat är konfigurerat, oavsett licens | Konfigurera SigningCertificate |
Widgeten laddas men säger Signing is not enabled on this server. | AddSignerWidget() anropades inte, eller basePath matchar inte där UseDoconut() är monterad | Anropa 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 MaxSignatureImageKb | Skicka en ren base64 PNG inom gränsen |
open svarar 413 File is too large. | Uppladdningen överskrider MaxUploadMb | Hö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 visare | Word-utdata bär en OOXML-paket‑signatur, som många visare inte visar | Signera till PDF, som standard |
| PDF-läsare säger att signerarens identitet är okänd | 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å |
| Widgeten misslyckas när UI:n är på en annan origin | Endpoints har ingen CORS‑stöd | Servera UI:n från samma origin, eller reverse-proxy Doconut‑vägarna |
| Temat tillämpas inte | Selektorn riktar sig mot ett element inuti mounten | Rikta mot själva mounten: #host.dsw eller #host |
Var den här sidan hjälpsam?