Signer-plugin
Signera PDF- och Word-dokument med en synlig signatur och ett digitalt sigill
Signer‑pluginet placerar en synlig signatur på ett dokument och förseglings 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 den som signerar.
| Yta | Använd när |
|---|---|
DocumentSigner (C#) | Du signerar på servern, utan att en webbläsare är inblandad |
Inbäddad widget (doconutSigner.js) | Du vill ha en färdig uppladdnings-, signerings- och nedladdningsskärm på din sida |
HTTP‑endpunkter på DocImage.axd (?sign=open|run|download) | Du bygger ditt eget signerings‑UI mot ett dokumenterat serverkontrakt |
Varje signatur placeras en gång, på en sida. Signerarens namn, anledningen och platsen kan följa med den.
Installera paketet
Install-Package Doconut.NETFramework.SignerFör att låsa pluginet till den version som den här dokumentationen beskriver:
Install-Package Doconut.NETFramework.Signer -Version 26.10.0Behåll Signer‑paketet i samma version som Doconut.NETFramework.
Pluginets 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 DoconutHost.Initialize, anropad från Application_Start:
Doconut.DoconutHost.Initialize(options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
});Lägg till Doconut.DoconutHost.Shutdown() i Application_End så att bakgrundsarbetet stoppas rent när applikationspoolen återcirkuleras.
Det är allt som C#‑fasaden behöver. Widgeten och dess HTTP‑endpunkter är ett separat opt‑in, AddSignerWidget() (se Inbäddad widget).
Pluginet behöver en licens som ger Signer‑kapaciteten. Utan en sådan kastar DoconutHost.Initialize från Application_Start:
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.I System.Web betyder det att varje förfrågan svarar med en tom 500, och orsaken finns bara i Windows‑händelseloggen (källa ASP.NET). Det kastar ett undantag när ingen licens finns, en äldre TRIAL‑fil, en licens utan Signer, eller en betald licens som används utanför dess versionsfönster. Tillfälliga Demo/NFR‑licenser accepteras. Se Licensinställning.
Licensiering & vattenstämpel
| Licensstatus | Uppstart | Certifierad signatur | Visuell signatur |
|---|---|---|---|
Betald licens som ger Signer, certifikat konfigurerat | Startar | Sigillad med ditt certifikat, rent (watermarked: false) | Rent |
Betald licens som ger Signer, inget certifikat | Startar | Nekad: No signing certificate configured. | Rent |
| Betald licens, certifikat utgånget eller ännu inte giltigt | Startar | Nekad: The signing certificate expired on yyyy-MM-dd. | Rent |
| Tillfällig Demo/NFR-licens, aktiv eller utgången | Startar | Sigillad med det inbyggda democertifikatet, vattenstämpel (watermarked: true) | Vattenstämplad |
Ingen licens, en äldre TRIAL‑fil, en licens utan Signer, eller en betald licens utanför dess versionsfönster | Application_Start kastar; varje förfrågan svarar med en tom 500 | — | — |
Regeln är densamma för C#‑fasaden och widgeten: utdata får en vattenstämpel när licensen inte är en betald visningslicens eller är tillfällig. Under en tillfällig licens signerar pluginet alltid med sitt inbyggda democertifikat, och eventuellt konfigurerat certifikat används inte.
Democertifikatet producerar ett riktigt sigill, men PDF‑läsare litar inte på det. En integration kan byggas och testas från början till slut på en utvärderingslicens; för att få rena, pålitliga utdata behöver du både en betald licens och ditt eget signeringscertifikat.
Användning från C#
DocumentSigner registreras av DoconutHost.Initialize; lös upp det från DoconutHost.Services. Dess konstruktor är intern, så aldrig new den. Att lösa upp det 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 standardvärdet Certified (synlig signatur + digitalt sigill); WordOutput har standardvärdet Pdf.
SignResult result = await _signer.SignAsync(pdf, ".pdf", request, certificate, ct);
using (result.Stream)
using (var output = new MemoryStream())
{
await result.Stream.CopyToAsync(output, 81920, 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: släpp den när du är klar.
I en MVC 5‑controller
Gör åtgärden asynkron och await signaturen. Denna lägger till en Visual‑signatur, som inte kräver något certifikat:
[HttpPost]
public async Task<ActionResult> Sign(HttpPostedFileBase file)
{
var signer = Doconut.DoconutHost.Services.GetRequiredService<DocumentSigner>();
byte[] signaturePng = System.IO.File.ReadAllBytes(Server.MapPath("~/App_Data/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(
file.InputStream, Path.GetExtension(file.FileName), request, ct: Response.ClientDisconnectedToken);
string contentType = result.Extension == ".pdf"
? "application/pdf"
: "application/vnd.openxmlformats-officedocument.wordprocessingml.document";
return File(result.Stream, contentType, Path.GetFileNameWithoutExtension(file.FileName) + "-signed" + result.Extension);
}En Word‑källa signeras till PDF om du inte begär Word‑utdata. Namnge resultatet från result.Extension:
var signer = Doconut.DoconutHost.Services.GetRequiredService<DocumentSigner>();
byte[] signaturePng = File.ReadAllBytes(HostingEnvironment.MapPath("~/App_Data/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‑byte, 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 (standard) | 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 med sig utfärdarens certifikat som finns i ditt PFX, så en läsare som litar på din rot kan bygga kedjan. Word‑inhemska förseglingar är OOXML‑paketsignaturer och bär endast undertecknarens 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 som händer | Verifieringsstöd |
|---|---|---|
WordOutput.Pdf (standard) | Dokumentet konverteras till PDF, sedan signeras och förseglas | Bred: en signerad PDF verifieras överallt |
WordOutput.Docx | Dokumentet förblir Word: signaturbilden placeras i det, plus en OOXML‑paketsignatur | Begränsad: inte alla visare visar OOXML‑paketsignaturer |
Behåll PDF om inte mottagaren behöver en redigerbar Word‑fil och accepterar den 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, sätt SignerWidgetOptions.SigningCertificate; för C#‑fasaden, skicka certifikatet till SignAsync. Tillhandahåll antingen bytena eller en sökväg, plus lösenordet. App_Data är en bra plats för filen, eftersom IIS aldrig levererar den:
Doconut.DoconutHost.Initialize(options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
options.AddSignerWidget(widget =>
{
widget.SigningCertificate = new SigningCertificate
{
PfxBytes = File.ReadAllBytes(HostingEnvironment.MapPath("~/App_Data/signing.pfx")),
Password = System.Configuration.ConfigurationManager.AppSettings["DoconutSigner:Password"] ?? "",
};
});
});Doconut.DoconutHost.Initialize(options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
options.AddSignerWidget(widget =>
{
widget.SigningCertificate = new SigningCertificate
{
PfxPath = HostingEnvironment.MapPath("~/App_Data/signing.pfx"),
Password = System.Configuration.ConfigurationManager.AppSettings["DoconutSigner:Password"] ?? "",
};
});
});Egenskaperna för SigningCertificate är endast initieringsbara, vilket C# 7.3 (standard för .NET Framework‑projekt) inte kan sätta. Sätt <LangVersion> till 9.0 eller senare i projektfilen.
Certifikatet hålls endast i minnet. Det loggas aldrig, returneras till en klient eller sparas, och lösenordet visas aldrig i ett 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 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, men Certified‑signaturer avvisas tills det ersätts. Visual‑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 utfärdat för något annat, som ett TLS‑servercertifikat, signerar fortfarande, men 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 (dess ikon 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 DoconutHost.Initialize, så ett felkonfigurerat PFX misslyckas vid start snarare än vid den första signaturen. Tre problem kastar ett InvalidOperationException från Application_Start, och varje begäran svarar sedan med ett tomt 500; meddelandet finns i Windows händelselogg:
| 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 apppoolens 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 ett riktigt .pfx, inte ett .cer eller .pem |
Doconut Signer: the signing certificate has no private key. Re-export the .pfx INCLUDING the private key. | Exportera PFX:en igen med den privata nyckeln |
På ASP.NET Core loggar värden också en rad vid start som namnger certifikatet, eller varnar för att det är utgånget eller inte utfärdat för signering. DoconutHost skriver inte den raden, så på .NET Framework bör du kontrollera ett nytt certifikat genom att signera ett testdokument i certifierat läge.
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
Aktivera slutpunkterna
Widgetens ?sign=open|run|download-slutpunkter levereras av DocImage.axd och är avstängda som standard. Aktivera dem bredvid plugin‑registreringen:
Doconut.DoconutHost.Initialize(options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/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 Certificate setup; låt den vara null för demo (watermarked) signering
});
});
// System.Web läser hela uppladdningen innan Doconut ser den: behåll maxRequestLength (KB) och
// maxAllowedContentLength (bytes) i Web.config ovanför widget's MaxUploadMb.AddSignerWidget() utan argument aktiverar widgeten med standardinställningarna. Den beviljar inte signering i sig själv: den behöver AddPlugin<SignerPlugin>(), eller så kastar DoconutHost.Initialize:
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.Slutpunkterna och skriptet levereras av hanteraren och modulen som är registrerad i Web.config:
<system.webServer>
<handlers>
<add name="DocImage" verb="GET,HEAD,POST" path="DocImage.axd" type="Doconut.DocImageHandler, Doconut" />
</handlers>
<modules>
<add name="DoconutResources" type="Doconut.DoconutResourceModule, Doconut" />
</modules>
</system.webServer>Modulen levererar skriptet oavsett om widgeten är aktiverad eller inte. Utan AddSignerWidget() laddas widgeten och ritar sin droppzon, och dess första begäran svarar med 404: widgeten rapporterar sedan Signing is not enabled on this server.
Uppladdningsgränser
ASP.NET läser hela begärans kropp innan DocImage.axd körs. En uppladdning över MaxUploadMb men under värdens gränser får widgetens egna JSON 413 (File is too large.). En uppladdning över värdens gränser avvisas först av IIS, med en felsida som widgeten inte kan läsa. Håll båda värdens gränser över widgetens tak:
<system.web>
<httpRuntime maxRequestLength="30720" /> <!-- KILOBYTES: 30 MB -->
</system.web>
<system.webServer>
<security>
<requestFiltering>
<requestLimits maxAllowedContentLength="31457280" /> <!-- BYTES: 30 MB -->
</requestFiltering>
</security>
</system.webServer>En uppladdning som skickas utan en Content-Length (chunked) och som överskrider värdens gränser får också IIS‑felsidan; det finns ingen lösning för det fallet.
Bädda in den
Skriptet levereras på /doconut-res/js/doconutSigner.js. Det är en enda, självständig fil utan beroenden. Peka basePath mot hanteraren:
<div id="host"></div>
<script src="/doconut-res/js/doconutSigner.js"></script>
<script>
const handle = Doconut.signer('#host', { basePath: '/DocImage.axd' });
</script>Doconut.signer(selectorOrElement, options) tar en CSS‑väljare eller ett element, kastar ett fel om monteringen inte hittas och returnerar ett handtag. Widgetens standardbasePath, /doconut, är ASP.NET Core‑slutpunkten; i detta paket måste den vara '/DocImage.axd'.
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 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.
Alternativ
| Alternativ | Typ | Standard | Anteckningar |
|---|---|---|---|
basePath | string | '/doconut' | Var ?sign=‑slutpunkterna och förhandsgranskningsbilderna levereras. Ställ in '/DocImage.axd' i detta paket |
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 för sidans förhandsgranskning |
licenseUrl | string | null | null | Omvandlar demo‑vattenstämpeln 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äningsundertecknare.
Doconut.signer('#host', { basePath: '/DocImage.axd', licenseUrl: '/pricing' });// Endast visuell, ingen växel: en enkel stämpel utan digital signatur erbjuds.
Doconut.signer('#host', {
basePath: '/DocImage.axd',
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 Nedladdning‑klick | { downloadName, downloadToken } |
onError | Ett öppnings-, signerings‑ eller nedladdningssteg misslyckas, eller en fil i Bild‑läge är för stor | { message } |
En återuppringning som kastar ett fel fångas och loggas; den bryter aldrig widgetens flöde.
Imperativt handtag
| 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: '/DocImage.axd',
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; /* 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 på DocImage.axd. Rutter 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 | Lyckad respons |
|---|---|---|
POST /DocImage.axd?sign=open (multipart, one file) | Ladda upp en PDF eller .docx och öppna den för förhandsgranskning | 200 — { token, name, pages, ext } |
POST /DocImage.axd?sign=run (JSON body) | Signera den uppladdade filen | 200 — { downloadToken, downloadName, watermarked } |
GET /DocImage.axd?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, /DocImage.axd?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änslig; 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 övre vänstra hörnet, med x + w ≤ 1 och y + h ≤ 1 |
meta.signerName / reason / location | Valfri. Varje värde trimmas, ett tomt värde tas bort, och varje värde kapas vid 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 behålls 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 |
|---|---|---|---|
| valfri | 404 | Widgeten är inte aktiverad | endast status |
| valfri | 405 | Fel verb (open och run behöver POST, download behöver GET) | endast status |
open | 400 | Ingen multipart‑uppladdning | Expected a multipart file upload. |
open | 400 | Ingen fil, eller en tom | No file uploaded. |
open | 400 | Allt annat än .pdf eller .docx | Signing supports PDF and Word (.docx) files only. |
open | 413 | Uppladdningen överskrider MaxUploadMb (men inte IIS‑gränserna) | 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 löpt 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 | Data ä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: File 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 = '/DocImage.axd';
// 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 ursprung som applikationen, eller reverse-proxy DocImage.axd och /doconut-res under ditt UI:s ursprung.
I produktion
-
Installera pluginet bredvid kärnpaketet, i samma version:
Install-Package Doconut.NETFramework.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 förändring aldrig kräver kodändring:
xml<appSettings> <add key="DoconutSigner:PfxPath" value="~/App_Data/your-certificate.pfx" /> </appSettings>csharpvar settings = System.Configuration.ConfigurationManager.AppSettings; Doconut.DoconutHost.Initialize(options => { options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic"); options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>(); options.AddSignerWidget(widget => widget.SigningCertificate = new SigningCertificate { PfxPath = HostingEnvironment.MapPath(settings["DoconutSigner:PfxPath"]), Password = settings["DoconutSigner:Password"] ?? "", }); });Behåll
.pfxiApp_Data, vilket IIS aldrig serverar, och håll lösenordet ute från en klartextWeb.config: använd en krypterad konfigurationssektion, eller en hemlig lagring som din distribution läser. -
Signera ett testdokument i Certified‑läge. Ett certifikat som har gått ut eller ännu inte är giltigt avvisas med
The signing certificate expired on yyyy-MM-dd.(elleris not valid before), och en PDF‑läsare visar om den litar på signaturen.
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å servern som levererade open. Bakom en lastbalanserare utan klistrade sessioner kan en senare run, download eller förhandsgranskningsförfrågan nå en annan server och inte hitta uppladdningen. Registrera den delade, krypterade widget‑lagringen via det andra argumentet till DoconutHost.Initialize:
byte[] farmKey = Convert.FromBase64String(System.Configuration.ConfigurationManager.AppSettings["Doconut:FarmKey"]);
Doconut.DoconutHost.Initialize(
options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
options.AddSignerWidget();
},
services => services.AddDoconutDistributedWidgets(store =>
{
store.RootPath = @"\\fileshare\doconut"; // en mapp som varje server kan läsa och skriva
store.FarmKey = farmKey; // minst 32 byte, identisk på varje server
// 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 server. 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 server 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 från DoconutHost.Services; 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 vattenmärkt.
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 ogenomskinlig JPG förblir ogenomskinlig. 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, 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. Sättarna är endast initieringsbara: projektet kräver C# 9.0 eller senare.
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 |
|---|---|---|
Varje begäran svarar med en tom 500 efter att ha lagt till pluginet; händelseloggen visar 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>() |
Händelseloggen visar 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>() |
Händelseloggen visar Doconut Signer: the certificate file was not found at '{path}'. | PfxPath pekar på en saknad fil | Fixa sökvägen; distribuera filen där apppoolens konto kan läsa den |
Händelseloggen visar 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 |
Händelseloggen visar 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 |
new SigningCertificate { … } kompilerar inte | Projektet använder C# 7.3, vilket inte kan sätta init-only-egenskaper | Ställ in <LangVersion> till 9.0 eller senare |
Uppslagning av DocumentSigner kastar No IDocumentSigner is registered. | SignerPlugin är inte registrerad | Lägg till AddPlugin<SignerPlugin>() i DoconutHost.Initialize |
| Utdata är vattenmärkt | 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 fungerar fortfarande under tiden |
Widgeten laddas men säger Signing is not enabled on this server. | AddSignerWidget() anropades inte, eller basePath är inte '/DocImage.axd' | Anropa AddSignerWidget(); sätt basePath: '/DocImage.axd' |
| En stor uppladdning visar en IIS-felsida istället för widgetens meddelande | maxRequestLength / maxAllowedContentLength är under MaxUploadMb | Höj båda värdgränserna över MaxUploadMb |
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 annan server i farmen har inte uppladdningen | Öppna filen igen; i en farm, registrera AddDoconutDistributedWidgets |
Ett signerat .docx visar ingen signatur i vissa visare | Word‑utdata innehåller en OOXML‑paketsignatur, som många visare inte visar | Signera till PDF, 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 domän | Endpoints har inget CORS‑stöd | Servera UI:n från samma ursprung, eller reverse-proxy DocImage.axd och /doconut-res |
| Temat tillämpas inte | Selektorn riktar sig mot ett element inuti mounten | Målsätt mounten själv: #host.dsw eller #host |
Ramverkanteckningar
Jämfört med ASP.NET Core-paketen skiljer sig detta paket endast i hosting; API:t, endpoint‑kontraktet, widget‑skriptet och licensreglerna är desamma.
- Registrering är i
Application_Start, viaDoconutHost.Initialize, istället förbuilder.Services.AddDoconut. Tjänster somAddDoconutDistributedWidgetsgår i dess andra argument. - Endpoints tillhandahålls av
DocImage.axdoch skriptet avDoconutResourceModule, båda registrerade iWeb.config, istället förUseDoconut()ochUseDoconutResources(). Widgeten behöverbasePath: '/DocImage.axd'. - Startfel visas som en tom
500på varje begäran, med orsaken i Windows händelseloggen. - Uppladdningar läses helt av ASP.NET innan Doconut ser dem, så IIS-gränserna måste vara över
MaxUploadMb. - Ingen startlogg‑rad om certifikatet: de tre certifikatfelen kastas fortfarande, men raden som namnger certifikatet skrivs inte.
- C# 9.0 eller senare krävs för att sätta
SigningCertificate's init‑only‑egenskaper. - Endast Windows, precis som resten av .NET Framework-paketet.
Var den här sidan hjälpsam?