Plugin Signer
Podepisujte PDF a Word dokumenty viditelným podpisem a digitální pečetí
Plugin Signer umisťuje viditelný podpis na dokument a ve výchozím nastavení jej zapečeťuje digitálním podpisem, který může ověřit PDF čtečka. Podepisuje PDF a Word (.docx) soubory. Viditelný podpis je vždy PNG obrázek: nakreslený, napsaný nebo nahraný podepisujícím.
| Rozhraní | Použijte, když |
|---|---|
DocumentSigner (C#) | Podepisujete na serveru, bez zapojení prohlížeče |
Vložený widget (doconutSigner.js) | Chcete připravenou obrazovku pro nahrání, podepsání a stažení ve své stránce |
HTTP koncové body na DocImage.axd (?sign=open|run|download) | Vytvoříte vlastní UI pro podepisování podle dokumentovaného serverového kontraktu |
Každý podpis je umístěn jednou, na jedné stránce. Jméno podepisujícího, důvod a místo mohou s ním cestovat.
Instalace balíčku
Install-Package Doconut.NETFramework.SignerAby byl plugin připnut k verzi, kterou tato dokumentace popisuje:
Install-Package Doconut.NETFramework.Signer -Version 26.10.0Udržujte balíček Signer ve stejné verzi jako Doconut.NETFramework.
Licenční soubor pluginu, Doconut.Viewer.Signer.lic, umístěte do stejné složky jako Doconut.Viewer.lic; je načítán spolu s licencí prohlížeče.
Registrace pluginu
Stejně jako každý Doconut plugin, Signer se registruje pomocí AddPlugin<TPlugin>() v DoconutHost.Initialize, voláno z Application_Start:
Doconut.DoconutHost.Initialize(options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
});Přidejte Doconut.DoconutHost.Shutdown() do Application_End, aby se pozadí práce čistě zastavilo při recyklaci aplikačního poolu.
To je vše, co C# fasáda potřebuje. Widget a jeho HTTP koncové body jsou samostatná volitelná funkce, AddSignerWidget() (viz Vložený widget).
Plugin potřebuje licenci, která poskytuje schopnost Signer. Bez ní DoconutHost.Initialize vyhazuje z 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.V System.Web to znamená, že každá žádost vrátí prázdný 500 a důvod je zaznamenán pouze v protokolu událostí Windows (zdroj ASP.NET). Vyhazuje při chybě licence, starém souboru TRIAL, licenci bez Signer a placené licenci použití mimo její časové okno. Dočasné Demo/NFR licence jsou akceptovány. Viz Nastavení licence.
Licencování a vodoznak
| Stav licence | Spuštění | Certifikovaný podpis | Vizuální podpis |
|---|---|---|---|
Placená licence poskytující Signer, certifikát nakonfigurován | Spouští | Zapečetěno vaším certifikátem, čisté (watermarked: false) | Čisté |
Placená licence poskytující Signer, bez certifikátu | Spouští | Odmítnuto: No signing certificate configured. | Čisté |
| Placená licence, certifikát vypršel nebo ještě není platný | Spouští | Odmítnuto: The signing certificate expired on yyyy-MM-dd. | Čisté |
| Dočasná Demo/NFR licence, aktivní nebo vypršená | Spouští | Zapečetěno vestavěným demo certifikátem, opatřeno vodoznakem (watermarked: true) | S vodoznakem |
Žádná licence, starý soubor TRIAL, licence bez Signer, nebo placená licence mimo její časové okno | Application_Start vyhazuje; každá žádost vrátí prázdný 500 | — | — |
Pravidlo je stejné pro C# fasádu i widget: výstup je opatřen vodoznakem, pokud licence není placená licence pro prohlížeč nebo je dočasná. Pod dočasnou licencí plugin vždy podepisuje svým vestavěným demo certifikátem a jakýkoli certifikát, který nakonfigurujete, není použit.
Demo certifikát vytváří pravý pečeť, ale PDF čtečky mu nedůvěřují. Integraci lze postavit a otestovat end-to-end na evaluační licenci; pro získání čistého, důvěryhodného výstupu potřebujete jak placenou licenci, tak vlastní certifikát pro podepisování.
Použití z C#
DocumentSigner je registrován pomocí DoconutHost.Initialize; vyřešte jej z DoconutHost.Services. Jeho konstruktor je interní, takže jej nikdy nenew. Vyřešení bez AddPlugin<SignerPlugin>() vyvolá 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 defaults to Certified (viditelný podpis + digitální pečeť); WordOutput defaults to 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 bere zdrojový stream, jeho příponu (".pdf" nebo ".docx"), požadavek a certifikát pro tento hovor. Facade nečte SignerWidgetOptions.SigningCertificate; toto nastavení je pro widget. Předávejte null pod demo licencí, nebo ve Visual režimu.
SignResult obsahuje podepsaný dokument jako seekovatelný stream, plus jeho Extension (".pdf" nebo ".docx"), abyste mohli pojmenovat soubor. Vlastníte stream: uvolněte jej, když jste hotovi.
V MVC 5 kontroleru
Udělejte akci asynchronní a await podpis. Tato přidá vizuální podpis, který nevyžaduje žádný certifikát:
[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);
}Zdroj Word je podepsán do PDF, pokud nepožádáte o výstup Word. Pojmenujte výsledek z 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 vyhodí výjimku místo vrácení, když volání nemůže uspět:
| Výjimka | Zpráva | Kdy |
|---|---|---|
InvalidOperationException | No signing certificate configured. | Certifikovaný režim, placená licence a žádný certifikát nepředán |
InvalidOperationException | The signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd. | Certifikovaný režim s certifikátem mimo jeho platnostní období |
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. | Prázdné PNG bajty nebo umístění, které není platné |
NotSupportedException | The signer supports PDF and Word (.docx) documents; got '{extension}'. | Jakýkoli jiný typ zdroje |
Režimy podepisování, výstup Word a certifikáty
Režimy podepisování
SignRequest.Mode určuje, zda je podpis zapečetěn.
| Režim | Co vytváří | Certifikát | Ověřitelné |
|---|---|---|---|
SignatureMode.Certified (default) | Viditelný podpis plus digitální pečeť | Vyžadováno při placené licenci | Ano |
SignatureMode.Visual | Pouze viditelný podpis | Nikdy nepotřebné | Ne: je to obrázek |
Použijte Certified, když musí být podpis prokazatelný: schválení, smlouvy, cokoliv, co ověřovatel potřebuje zkontrolovat pro identitu a integritu. Použijte Visual, když potřebujete jen vzhled podpisu, nebo nemáte certifikát. Dočasná licence přidá vodoznak k oběma.
PDF pečetě jsou oddělené podpisy PKCS#7 (adbe.pkcs7.detached) s SHA-256, pro klíče RSA nebo ECDSA. Obsahují certifikáty vydavatele nalezené ve vašem PFX, takže čtečka, která důvěřuje vašemu kořenu, může vytvořit řetězec. Word‑nativní pečetě jsou podpisy OOXML balíčků a obsahují pouze certifikát podepisujícího.
Word dokumenty
Pro zdroj typu .docx, SignRequest.WordOutput určuje výstup. Je ignorováno pro PDF zdroje, které vždy vytvářejí PDF.
| Výstup | Co se stane | Podpora ověřovatele |
|---|---|---|
WordOutput.Pdf (default) | Dokument je převeden na PDF, poté podepsán a zapečetěn | Široká: podepsané PDF se ověří všude |
WordOutput.Docx | Dokument zůstane ve Wordu: obrázek podpisu je do něj vložen, plus podpis OOXML balíčku | Omezená: ne každý prohlížeč zobrazuje podpisy OOXML balíčků |
Používejte PDF, pokud příjemce nepotřebuje editovatelný Word soubor a přijímá omezenou podporu ověřovatele.
Nastavení certifikátu
Pro zapečetění vlastní identitou poskytněte pluginu soubor PFX (PKCS#12), který obsahuje soukromý klíč. Pro widget nastavte SignerWidgetOptions.SigningCertificate; pro C# fasádu předávejte certifikát do SignAsync. Poskytněte buď bajty nebo cestu, plus heslo. App_Data je dobré místo pro soubor, protože IIS jej nikdy neslouží:
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"] ?? "",
};
});
});SigningCertificate má vlastnosti init‑only, což C# 7.3 (výchozí pro projekty .NET Framework) nedokáže nastavit. Nastavte <LangVersion> na 9.0 nebo novější v souboru projektu.
Certifikát je uchováván pouze v paměti. Nikdy není zaznamenán, vrácen klientovi ani uložen, a heslo se nikdy neobjeví v chybové zprávě.
Požadavky:
- Balíček PFX / PKCS#12 s jeho soukromým klíčem. Soubor pouze s veřejným klíčem (
.cer,.crt) nemůže podepisovat. Exportujte řetězec vydavatele s ním, aby PDF pečetě mohly být přenášeny. - Správné heslo.
- V rámci jeho období platnosti. Expirovaný nebo ještě neplatný certifikát aplikaci nezastaví, ale Certified podpisy jsou odmítnuty, dokud není nahrazen. Visual podpisy nejsou ovlivněny.
- Vydáno pro podepisování dokumentů: použití klíče s digitálním podpisem nebo neodmítnutím, a rozšířené použití klíče, pokud je přítomno, které umožňuje podepisování dokumentů, ochranu e‑mailu nebo autentizaci klienta. Certifikát vydaný pro něco jiného, například TLS serverový certifikát, stále může podepisovat, ale PDF čtečky označí podpis.
- Hardwarové tokeny, čipové karty, HSM a úložiště certifikátů Windows nejsou podporovány. Exportujte certifikát, spolu se soukromým klíčem a řetězcem, do PFX.
Vytvořte PFX z certifikátu a jeho soukromého klíče pomocí OpenSSL:
openssl pkcs12 -export -out signing.pfx -inkey private.key -in certificate.crt
# Heslo pro export, na které budete vyzváni, je SigningCertificate.Password.Exportujte jeden z úložiště certifikátů Windows: otevřete certmgr.msc a najděte certifikát (jeho ikona zobrazuje klíč, když je soukromý klíč přítomen). Klikněte na něj pravým tlačítkem, zvolte All Tasks → Export…, vyberte Yes, export the private key, zvolte Personal Information Exchange – PKCS #12 (.PFX) a nastavte heslo.
Kontroly při spuštění
Když je widget povolen, certifikát v SignerWidgetOptions.SigningCertificate je zkontrolován jednou, uvnitř DoconutHost.Initialize, takže špatně nakonfigurovaný PFX selže při spuštění místo při první podpisu. Tři problémy vyvolají InvalidOperationException z Application_Start a každá žádost pak vrátí prázdný 500; zpráva je v protokolu událostí Windows:
| Zpráva | Oprava |
|---|---|
Doconut Signer: the certificate file was not found at '{path}'. | Opravte PfxPath; ujistěte se, že soubor je nasazen a čitelný účtem aplikačního poolu |
Doconut Signer: the signing certificate could not be opened — the password is incorrect or the file is not a valid .pfx. | Zkontrolujte heslo; ujistěte se, že soubor je skutečný .pfx, ne .cer ani .pem |
Doconut Signer: the signing certificate has no private key. Re-export the .pfx INCLUDING the private key. | Exportujte PFX znovu s privátním klíčem |
Na ASP.NET Core host také zaznamená jeden řádek při spuštění, který uvádí certifikát, nebo varování, že je prošlý nebo nevydaný pro podepisování. DoconutHost tento řádek nezapisuje, takže na .NET Framework zkontrolujte nový certifikát podepsáním testovacího dokumentu v režimu Certified.
Rozhraní C# není kontrolováno při spuštění. Certifikát, který předáte do SignAsync, je načten při podpisu, takže špatná cesta nebo heslo způsobí selhání tohoto volání.
Vkládací widget
Povolení koncových bodů
Koncové body ?sign=open|run|download widgetu jsou poskytovány pomocí DocImage.axd a jsou ve výchozím nastavení vypnuté. Povolit je vedle registrace pluginu:
Doconut.DoconutHost.Initialize(options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
options.AddSignerWidget(widget =>
{
widget.MaxUploadMb = 25; // výchozí
widget.MaxSignatureImageKb = 512; // výchozí
// widget.SigningCertificate: viz nastavení Certificate; ponechte null pro demo (označené vodoznakem) podepisování
});
});
// System.Web načte celý upload před tím, než Doconut jej uvidí: ponechte maxRequestLength (KB) a
// maxAllowedContentLength (bytes) v Web.config nad MaxUploadMb widgetu.AddSignerWidget() bez argumentu povolí widget s výchozími nastaveními. Neposkytuje samotné podepisování: potřebuje AddPlugin<SignerPlugin>(), nebo DoconutHost.Initialize vyvolá výjimku:
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.Koncové body a skript jsou poskytovány handlerem a modulem registrovaným v 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>Modul poskytuje skript bez ohledu na to, zda je widget povolen. Bez AddSignerWidget() se widget načte a vykreslí svou oblast pro přetažení, a jeho první požadavek vrátí 404: widget pak hlásí Signing is not enabled on this server.
Limity nahrávání
ASP.NET načte celé tělo požadavku před spuštěním DocImage.axd. Nahrání nad MaxUploadMb, ale pod limity hostitele, získá vlastní JSON widgetu 413 (File is too large.). Nahrání nad limity hostitele je nejprve odmítnuto IIS, s chybovou stránkou, kterou widget nemůže přečíst. Udržujte oba limity hostitele nad limitem widgetu:
<system.web>
<httpRuntime maxRequestLength="30720" /> <!-- KILOBYTES: 30 MB -->
</system.web>
<system.webServer>
<security>
<requestFiltering>
<requestLimits maxAllowedContentLength="31457280" /> <!-- BYTES: 30 MB -->
</requestFiltering>
</security>
</system.webServer>Nahrání odeslané bez Content-Length (chunked), které překročí limity hostitele, také získá chybovou stránku IIS; pro tento případ neexistuje žádné řešení.
Vložení
Skript je dostupný na /doconut-res/js/doconutSigner.js. Jedná se o jediný, samostatný soubor bez závislostí. Nastavte basePath na obslužnou funkci:
<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) přijímá CSS selektor nebo element, vyhodí výjimku, pokud není kořen nalezen, a vrací handle. Výchozí basePath widgetu, /doconut, je ASP.NET Core endpoint; v tomto balíčku musí být '/DocImage.axd'.
Podepisující nahrává PDF nebo soubor .docx, vytváří podpis (Kreslit na plátně, Psát jméno v podpisovém fontu, nebo Obrázek z PNG, JPG či GIF), přetahuje a mění jeho velikost na stránce a podepisuje a stahuje výsledek. Widget vždy odesílá podpis jako PNG; nahraný obrázek je v prohlížeči převeden na PNG, který má rozměry 520×160.
Možnosti
| Možnost | Typ | Výchozí | Poznámky |
|---|---|---|---|
basePath | string | '/doconut' | Kde jsou poskytovány ?sign= koncové body a náhledové obrázky. Nastavte '/DocImage.axd' v tomto balíčku |
resPath | string | '/doconut-res' | Rezervováno; widget obsahuje vlastní CSS |
maxUploadMb | number | 25 | Kontrola pouze na straně klienta, takže příliš velký soubor selže okamžitě. Limit na serveru je MaxUploadMb v AddSignerWidget |
maxSignatureKb | number | 512 | Limit na straně klienta pro režim Image. Udržujte jej stejný jako serverový MaxSignatureImageKb |
previewWidth | number | 560 | Šířka v pixelech náhledu stránky |
licenseUrl | string | null | null | Převádí upozornění demo-watermark na odkaz na tuto URL |
signatureMode | string | 'certified' | Počáteční typ podpisu: 'certified' nebo 'visual'. Jakákoli jiná hodnota se stane 'certified' |
showSignatureModeToggle | boolean | true | Zobrazuje volbu Digitální podpis / Pouze vizuální. S false widget podepisuje pomocí signatureMode |
wordOutput | string | 'pdf' | Počáteční výstup pro zdroje .docx: 'pdf' nebo 'docx'. Jakákoli jiná hodnota se stane 'pdf' |
showOutputFormatToggle | boolean | true | Zobrazuje volbu PDF / Word, pouze pro zdroje .docx. S false widget používá wordOutput |
labels | object | {} | Přepisuje libovolnou podmnožinu anglických řetězců |
Skrytí přepínače nezakáže funkci; nastaví hodnotu. Dvě běžné konfigurace:
// Oba přepínače jsou zobrazeny, digitální podpis je výchozí: plnohodnotný samoslužebný podepisovatel.
Doconut.signer('#host', { basePath: '/DocImage.axd', licenseUrl: '/pricing' });// Pouze vizuální, žádný přepínač: jednoduché razítko bez nabízeného digitálního podpisu.
Doconut.signer('#host', {
basePath: '/DocImage.axd',
signatureMode: 'visual',
showSignatureModeToggle: false
});Zpětné volání
| Callback | Spouští se při | Data |
|---|---|---|
onReady | Jednou, při připojení (ne znovu na reset()) | — |
onSourceLoaded | Soubor je otevřen a zobrazen jeho náhled | { file: { token, name, pages, ext } } |
onSigned | Podpis byl úspěšný | { downloadToken, downloadName, watermarked } |
onDownload | Při každém kliknutí na Stáhnout | { downloadName, downloadToken } |
onError | Krok otevření, podpisu nebo stažení selže, nebo je soubor v režimu Image příliš velký | { message } |
Callback, který vyhodí výjimku, je zachycen a zalogován; nikdy neporuší tok widgetu.
Imperativní ovladač
| Metoda | Chování |
|---|---|
reset() | Vrací se na obrazovku pro přetažení a vyčistí aktuální tok. Znovu nevyvolá onReady. Bez akce po destroy() |
loadFile(file) | Spustí tok s File. Bez akce, pokud widget není na obrazovce pro přetažení; v případě potřeby nejprve zavolejte reset() |
destroy() | Odstraní posluchače, vyprázdní mount a zmrazí instanci |
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());Popisky
Každý řetězec má výchozí anglickou hodnotu; labels přepíše libovolnou podmnožinu a zbytek zůstane anglický. Fragmenty, které se mění za běhu, používají {placeholders}, například uploading: 'Uploading {name}…' a pages: '{n} pages'.
| Klíč | Anglický výchozí |
|---|---|
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 |
Další klíče pokrývají krok umístění, chybovou obrazovku, propojený formulář oznámení demo (demoNoticePrefix, demoNoticeLink, demoNoticeSuffix) a aria-live oznámení.
Když open nebo run odpoví 404 bez JSON chyby, widget zobrazí signingNotEnabled. JSON chyba ze serveru vždy převáží, takže zprávy jako například vypršený čas nahrávání zůstávají viditelné.
Tématizace
Widget přidá třídu dsw do svého montážního elementu a načte jeho barvy, poloměr a písma z vlastních CSS vlastností, takže jej můžete tematizovat, aniž byste zasahovali do jeho vnitřností:
#host.dsw {
--dsw-accent: #b0522b; /* odkazy, zaměření, aktivní režim */
--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; /* režim Type */
}Výchozí hodnoty: --dsw-accent: #2b6cb0, --dsw-bg: #ffffff, --dsw-fg: #1a202c, --dsw-muted: #718096, --dsw-border: #cbd5e0, --dsw-radius: 8px, systémové UI písmo a kurzívní podpisové písmo.
Vytvořte si vlastní frontend
Widget je klientem pro tuto HTTP smlouvu na DocImage.axd. Cesty odpovídají 404, dokud není zavoláno AddSignerWidget(). Chyby nesou JSON tělo, { "error": "..." }, kromě případů, kdy tabulka uvádí „pouze stav“. Neznámá hodnota ?sign= odpovídá 400.
| Cesta | Účel | Úspěšná odpověď |
|---|---|---|
POST /DocImage.axd?sign=open (multipart, one file) | Nahrajte PDF nebo .docx a otevřete jej pro náhled | 200 — { token, name, pages, ext } |
POST /DocImage.axd?sign=run (JSON body) | Podepište nahraný soubor | 200 — { downloadToken, downloadName, watermarked } |
GET /DocImage.axd?sign=download&token=<downloadToken> | Streamujte podepsaný soubor | 200 — soubor, Content-Disposition: attachment, Cache-Control: no-store |
ext v odpovědi open zahrnuje úvodní tečku (".docx"). Náhled stránky používá standardní cestu k obrázku prohlížeče, /DocImage.axd?token={token}&page={n}&thumb=1&width={px}; zobrazená stránka se stane placement.page.
Tělo 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"
}| Pole | Poznámky |
|---|---|
token | Token z open |
signature.kind | Drawn, Typed nebo Image, nerozlišující velikost písmen; cokoliv jiného se stane Drawn. Pouze nápověda: payload je vždy PNG |
signature.payload | Čistý base64 PNG bez prefixu data:. Musí být skutečný PNG a po dekódování nesmí být větší než MaxSignatureImageKb |
placement.page | Číslováno od jedné |
placement.x / y / w / h | Normalizovaný 0..1 z levého horního rohu, s x + w ≤ 1 a y + h ≤ 1 |
meta.signerName / reason / location | Volitelné. Každý je oříznut, prázdná hodnota je zahozena a každý je oříznut na 256 znaků |
wordOutput | pdf (výchozí) nebo docx; ignorováno pro PDF zdroje. Cokoliv jiného se stane pdf |
mode | certified (výchozí) nebo visual. Cokoliv jiného se stane certified |
downloadName následuje výstup: <source>-signed.pdf nebo <source>-signed.docx, a download odesílá odpovídající Content-Type.
Nahraný zdroj a podepsaný výsledek jsou uchovávány po dobu 30 minut. Poté run a download odpovídají 404 a soubor musí být znovu otevřen. Všechny tokeny jsou GUIDy.
| Cesta | Stav | Kdy | Tělo |
|---|---|---|---|
| any | 404 | Widget není povolen | pouze stav |
| any | 405 | Špatná metoda (open a run potřebují POST, download potřebuje GET) | pouze stav |
open | 400 | Není multipart nahrání | Expected a multipart file upload. |
open | 400 | Žádný soubor, nebo prázdný | No file uploaded. |
open | 400 | Cokoliv jiného než .pdf nebo .docx | Signing supports PDF and Word (.docx) files only. |
open | 413 | Nahrání překračuje MaxUploadMb (ale ne limity IIS) | File is too large. |
run | 400 | Tělo není platný JSON, nebo je prázdné | Malformed request. / Empty request. |
run | 400 | Token chybí nebo není GUID | Invalid token. |
run | 404 | Nahrání vypršelo nebo nikdy nebylo otevřeno | Upload expired — please re-open the file. |
run | 400 | Žádný podpis, nebo žádné umístění | No signature supplied. / No placement supplied. |
run | 400 | Payload není base64, je prázdný, příliš velký, nebo není 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 | Umístění je mimo stránku | The signature or its placement is invalid. |
run | 400 | Certifikovaný režim, placená licence a žádný certifikát | No signing certificate configured. |
run | 400 | Certifikovaný režim s certifikátem mimo jeho platnost | The signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd. |
open, run | 500 | Zpracování selhalo | Sanitizovaná zpráva |
download | 400 | Token chybí nebo není GUID | pouze stav |
download | 404 | Neznámý nebo vypršený token | pouze stav |
Kompletní cyklus s fetch:
// file: the File to sign; pngBase64: podpis jako čistý base64 PNG, bez předpony data:,
// například canvas.toDataURL('image/png').split(',')[1].
async function signFile(file, pngBase64) {
const base = '/DocImage.axd';
// 1. open: nahrajte soubor
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: podepište jej
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: stáhněte podepsaný soubor
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);
}Koncové body jsou same-origin: tato verze nepodporuje CORS. Servírujte své UI a skript widgetu ze stejného původu jako aplikace, nebo použijte reverse-proxy DocImage.axd a /doconut-res pod původem vašeho UI.
V produkci
-
Nainstalujte plugin vedle hlavního balíčku, ve stejné verzi:
Install-Package Doconut.NETFramework.Signer. -
Přidejte licenční soubor. Umístěte
Doconut.Viewer.Signer.licdo stejné složky jakoDoconut.Viewer.lic. -
Získejte svůj certifikát jako PFX s jeho soukromým klíčem a řetězcem vydavatele, od certifikační autority nebo vlastní PKI vaší organizace. Pro první vyzkoušení použijte demo licenci (vestavěný demo certifikát, vodoznak) nebo samopodepsaný PFX.
-
Načtěte certifikát z konfigurace, aby jeho změna nikdy nevyžadovala úpravu kódu:
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"] ?? "", }); });Uchovávejte
.pfxvApp_Data, který IIS nikdy neslouží, a držte heslo mimo prostýWeb.config: použijte šifrovanou sekci konfigurace nebo tajný úložiště, ze kterého vaše nasazení čte. -
Podepište testovací dokument v režimu Certified. Certifikát, který je prošlý nebo ještě neplatný, je odmítnut pomocí
The signing certificate expired on yyyy-MM-dd.(nebois not valid before) a PDF čtečka ukazuje, zda důvěřuje podpisu.
Důvěra v PDF čtečkách. Čtečka zobrazuje podpis jako platný, pokud důvěřuje kořenu certifikátu. S PKI vaší organizace to platí na každém počítači, který důvěřuje vašemu kořenu, což je obvykle každý počítač uvnitř organizace. Certifikáty, kterým Adobe důvěřuje na jakémkoli počítači (Adobe Approved Trust List), jsou podle našich informací vydávány se soukromým klíčem na hardwarovém tokenu nebo HSM, což tento plugin nemůže použít: podepisuje pouze z PFX. Ověřte u svého poskytovatele certifikátu, než se spolehnete na tento typ důvěry.
Webové farmy
Widget uchovává každé nahrání a jeho výsledek v paměti na serveru, který obsloužil open. Za vyvažovačem zátěže bez trvalých relací může pozdější run, download nebo požadavek na náhled dosáhnout jiného serveru a nenajít nahrání. Zaregistrujte sdílené, šifrované úložiště widgetu prostřednictvím druhého argumentu 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"; // složka, kterou může každý server číst i zapisovat
store.FarmKey = farmKey; // alespoň 32 bajtů, identické na každém serveru
// store.Ttl = TimeSpan.FromMinutes(30); // jak dlouho je nahrávka uchována (výchozí)
}));- Jeden server nepotřebuje nic: bez tohoto volání se používá úložiště v paměti.
- Nahrání a výsledky jsou šifrovány v klidu na sdíleném úložišti (AES-256, encrypt-then-MAC) a každý soubor je svázán se svým tokenem, takže jeden token nikdy nemůže přečíst soubor jiného.
FarmKeymusí mít alespoň 32 bajtů a být stejný na každém serveru. Načtěte jej z tajného úložiště; nikdy jej nezakódovávejte přímo. Registrace vyhodíArgumentException, kdyžRootPathchybí nebo jeFarmKeykratší než 32 bajtů.- Nastavte
RootPathna stejné sdílené umístění, které používá distribuovaný prohlížeč, a dejte každému serveru stejný podpisový certifikát.
Referenční příručka API
Rozhraní a možnosti widgetu jsou v oboru názvů Doconut; typy požadavků a výsledků jsou v Doconut.Core.Models.Signing. SignerPlugin je v Doconut.Plugins.Signer.
DocumentSigner
public sealed class DocumentSigner
{
public Task<SignResult> SignAsync(
Stream source, string sourceExtension, SignRequest request,
SigningCertificate? cert = null, CancellationToken ct = default);
}Vyřešeno z DoconutHost.Services; konstruktor je interní. sourceExtension je ".pdf" nebo ".docx". Pod placenou licencí se používá cert a výstup je čistý; pod dočasnou licencí se používá vestavěný demo certifikát, cert se ignoruje a výstup je vodoznakem.
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
}Jedna viditelná podpisová značka umístěná jednou, plus volitelné metadata podepisujícího.
VisibleSignature and SignatureKind
public sealed record VisibleSignature(SignatureKind Kind, byte[] PngBytes)
{
public bool IsValid { get; } // PngBytes není prázdný
}
public enum SignatureKind { Drawn, Typed, Image }PngBytes je PNG pro každý typ. Nakreslený nebo napsaný podpis je průhledný; nahraný obrázek si zachovává svou průhlednost, takže neprůhledný JPG zůstává neprůhledný. Kind je jen nápověda.
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 je číslováno od 1; X, Y, W a H jsou normalizované 0..1 od levého horního rohu.
SignatureMode and WordOutput
public enum SignatureMode { Certified, Visual } // Certified je výchozí
public enum WordOutput { Pdf, Docx } // Pdf je výchozí; ignorováno pro PDF zdrojeSignResult
public sealed record SignResult(Stream Stream, string Extension);Podepsaný dokument jako prohledávatelný stream a jeho přípona s tečkou (".pdf" nebo ".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 není prázdný, nebo PfxPath není prázdný
}Nastavte buď PfxBytes nebo PfxPath, plus Password. Nastavovače jsou pouze init: projekt vyžaduje C# 9.0 nebo novější.
SignerWidgetOptions
public sealed class SignerWidgetOptions
{
public int MaxUploadMb { get; set; } = 25;
public int MaxSignatureImageKb { get; set; } = 512;
public SigningCertificate? SigningCertificate { get; set; }
}Nastavte přes DoconutOptions.AddSignerWidget(Action<SignerWidgetOptions>? configure = null), který vrací DoconutOptions, takže volání lze řetězit. Null SigningCertificate znamená demo certifikát pod dočasnou licencí a vizuální podpisy jen pod placenou licencí.
Řešení problémů
| Příznak | Příčina | Oprava |
|---|---|---|
Každý požadavek vrací prázdný 500 po přidání pluginu; protokol událostí ukazuje The Signer plugin is registered via AddPlugin but no active license grants Signer. | Žádná licence, soubor TRIAL, licence bez Signer, nebo placená licence mimo její časové okno | Nainstalujte licenci, která poskytuje Signer, nebo odstraňte AddPlugin<SignerPlugin>() |
Protokol událostí ukazuje AddSignerWidget() was called but the Signer plugin is not registered. | Widget je povolen bez svého pluginu | Přidejte options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>() |
Protokol událostí ukazuje Doconut Signer: the certificate file was not found at '{path}'. | PfxPath ukazuje na chybějící soubor | Opravte cestu; nasadíte soubor tam, kde jej může číst účet aplikačního fondu |
Protokol událostí ukazuje Doconut Signer: the signing certificate could not be opened — the password is incorrect or the file is not a valid .pfx. | Špatné heslo, nebo to není soubor PKCS#12 | Zkontrolujte heslo; použijte skutečný .pfx |
Protokol událostí ukazuje Doconut Signer: the signing certificate has no private key. Re-export the .pfx INCLUDING the private key. | PFX byl exportován bez soukromého klíče | Exportujte jej znovu se soukromým klíčem |
new SigningCertificate { … } se nedaří zkompilovat | Projekt používá C# 7.3, který nemůže nastavit init-only vlastnosti | Nastavte <LangVersion> na 9.0 nebo novější |
Řešení DocumentSigner vyhazuje No IDocumentSigner is registered. | SignerPlugin není registrován | Přidejte AddPlugin<SignerPlugin>() v DoconutHost.Initialize |
| Výstup je vodoznakem | Licence je dočasná (Demo/NFR) | Použijte placenou licenci, která poskytuje Signer |
run odpovídá 400 No signing certificate configured. | Placená licence, Certified režim, a žádný certifikát | Nakonfigurujte SigningCertificate, nebo podepište ve vizuálním režimu |
run odpovídá 400 The signing certificate expired on yyyy-MM-dd. | Certifikát je zastaralý | Vyměňte jej; vizuální podpisy mezitím fungují |
Widget se načte, ale říká Signing is not enabled on this server. | AddSignerWidget() nebyl zavolán, nebo basePath není '/DocImage.axd' | Zavolejte AddSignerWidget(); nastavte basePath: '/DocImage.axd' |
| Velké nahrání zobrazuje chybovou stránku IIS místo zprávy widgetu | maxRequestLength / maxAllowedContentLength jsou pod MaxUploadMb | Zvyšte oba limity hosta nad MaxUploadMb |
run odpovídá 400 The signature image must be a PNG., Signature image is not valid base64. nebo Signature image is too large. | Vlastní UI poslal data: URL, JPG, nebo více než MaxSignatureImageKb | Pošlete čistý base64 PNG v rámci limitu |
open odpovídá 413 File is too large. | Nahrání překračuje MaxUploadMb | Zvyšte MaxUploadMb v AddSignerWidget; widgetův maxUploadMb je jen kontrola na straně klienta |
run nebo download odpovídá 404 Upload expired — please re-open the file. | 30‑minutové okno uplynulo, nebo jiný server ve farmě nemá nahrání | Otevřete soubor znovu; ve farmě zaregistrujte AddDoconutDistributedWidgets |
Podepsaný .docx nezobrazuje podpis v některých prohlížečích | Word výstup obsahuje podpis OOXML balíčku, který mnoho prohlížečů nezobrazuje | Podepište do PDF, výchozí |
| PDF čtečky říkají, že identita podepisujícího je neznámá | Čtečka nedůvěřuje kořenu certifikátu (demo certifikát není nikdy důvěryhodný) | Použijte certifikát z kořene, kterému vaše čtečky důvěřují |
| Widget selže, když je UI na jiném původu | Koncové body nemají podporu CORS | Poskytněte UI ze stejného původu, nebo použijte reverse-proxy na DocImage.axd a /doconut-res |
| Téma se neaplikuje | Selektor cílí na prvek uvnitř mountu | Cílový mount samotný: #host.dsw nebo #host |
Framework notes
Ve srovnání s balíčky ASP.NET Core se tento balíček liší pouze v hostování; API, smlouva o koncovém bodu, skript widgetu a licenční pravidla jsou stejné.
- Registrace je v
Application_Start, přesDoconutHost.Initialize, místobuilder.Services.AddDoconut. Služby jakoAddDoconutDistributedWidgetsjdou do jeho druhého argumentu. - Koncové body jsou poskytovány pomocí
DocImage.axda skript pomocíDoconutResourceModule, oba registrovaní vWeb.config, místoUseDoconut()aUseDoconutResources(). Widget potřebujebasePath: '/DocImage.axd'. - Selhání při spuštění se projevují jako prázdný
500u každého požadavku, s důvodem v protokolu událostí Windows. - Nahrávání je ASP.NET načteno celé předtím, než je Doconut vidí, takže limity IIS musí být nad
MaxUploadMb. - Žádná řádka v logu při spuštění o certifikátu: tři chyby certifikátu se stále vyhazují, ale řádka pojmenovávající certifikát není zapsána.
- C# 9.0 nebo novější je potřeba k nastavení init-only vlastností
SigningCertificate. - Pouze Windows, stejně jako zbytek balíčku .NET Framework.
Byla tato stránka užitečná?