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

powershell
Install-Package Doconut.NETFramework.Signer

Aby byl plugin připnut k verzi, kterou tato dokumentace popisuje:

powershell
Install-Package Doconut.NETFramework.Signer -Version 26.10.0

Udrž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:

csharp
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:

text
The Signer plugin is registered via AddPlugin but no active license grants Signer. Remove the AddPlugin<...>() call or install a license (or trial/demo) that includes Signer.

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 licenceSpuštěníCertifikovaný podpisVizuální podpis
Placená licence poskytující Signer, certifikát nakonfigurovánSpouštíZapečetěno vaším certifikátem, čisté (watermarked: false)Čisté
Placená licence poskytující Signer, bez certifikátuSpouš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é oknoApplication_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>().

csharp
using Doconut;
using Doconut.Core.Models.Signing;

public sealed class ContractSigning
{
    private readonly DocumentSigner _signer;

    public ContractSigning(DocumentSigner signer) => _signer = signer;

    public async Task<byte[]> SignAsync(Stream pdf, byte[] signaturePng, SigningCertificate certificate, CancellationToken ct)
    {
        var request = new SignRequest(
            new VisibleSignature(SignatureKind.Drawn, signaturePng),
            new SignaturePlacement(Page: 1, X: 0.58, Y: 0.80, W: 0.32, H: 0.12),
            SignerName: "Ada Lovelace",
            Reason: "I approve this document",
            Location: "London, UK");
        // Mode 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:

csharp
[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:

csharp
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ýjimkaZprávaKdy
InvalidOperationExceptionNo signing certificate configured.Certifikovaný režim, placená licence a žádný certifikát nepředán
InvalidOperationExceptionThe 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í
ArgumentExceptionThe 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é
NotSupportedExceptionThe 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žimCo vytváříCertifikátOvěřitelné
SignatureMode.Certified (default)Viditelný podpis plus digitální pečeťVyžadováno při placené licenciAno
SignatureMode.VisualPouze viditelný podpisNikdy 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ýstupCo se stanePodpora 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.DocxDokument zůstane ve Wordu: obrázek podpisu je do něj vložen, plus podpis OOXML balíčkuOmezená: 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ží:

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

bash
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ávaOprava
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:

csharp
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:

text
AddSignerWidget() was called but the Signer plugin is not registered. Add options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>() (the widget needs it), or remove the AddSignerWidget() call.

Koncové body a skript jsou poskytovány handlerem a modulem registrovaným v Web.config:

xml
<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:

xml
<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:

html
<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žnostTypVýchozíPoznámky
basePathstring'/doconut'Kde jsou poskytovány ?sign= koncové body a náhledové obrázky. Nastavte '/DocImage.axd' v tomto balíčku
resPathstring'/doconut-res'Rezervováno; widget obsahuje vlastní CSS
maxUploadMbnumber25Kontrola pouze na straně klienta, takže příliš velký soubor selže okamžitě. Limit na serveru je MaxUploadMb v AddSignerWidget
maxSignatureKbnumber512Limit na straně klienta pro režim Image. Udržujte jej stejný jako serverový MaxSignatureImageKb
previewWidthnumber560Šířka v pixelech náhledu stránky
licenseUrlstring | nullnullPřevádí upozornění demo-watermark na odkaz na tuto URL
signatureModestring'certified'Počáteční typ podpisu: 'certified' nebo 'visual'. Jakákoli jiná hodnota se stane 'certified'
showSignatureModeTogglebooleantrueZobrazuje volbu Digitální podpis / Pouze vizuální. S false widget podepisuje pomocí signatureMode
wordOutputstring'pdf'Počáteční výstup pro zdroje .docx: 'pdf' nebo 'docx'. Jakákoli jiná hodnota se stane 'pdf'
showOutputFormatTogglebooleantrueZobrazuje volbu PDF / Word, pouze pro zdroje .docx. S false widget používá wordOutput
labelsobject{}Přepisuje libovolnou podmnožinu anglických řetězců

Skrytí přepínače nezakáže funkci; nastaví hodnotu. Dvě běžné konfigurace:

javascript
// 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' });
javascript
// 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í

CallbackSpouští se přiData
onReadyJednou, při připojení (ne znovu na reset())—
onSourceLoadedSoubor je otevřen a zobrazen jeho náhled{ file: { token, name, pages, ext } }
onSignedPodpis byl úspěšný{ downloadToken, downloadName, watermarked }
onDownloadPři každém kliknutí na Stáhnout{ downloadName, downloadToken }
onErrorKrok 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č

MetodaChová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
javascript
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í
dropPromptDrag & drop a PDF or Word file here
dropHintPDF or Word (.docx)
chooseFileChoose file
signatureHeadingYour signature
modeDraw / modeType / modeImageDraw / Type / Image
metaSummarySignature details (optional)
metaSignerName / metaReason / metaLocationSigner name / Reason / Location
signatureTypeSignature type
modeCertified / modeVisualDigital signature / Visual only
modeVisualNoteNo certificate — a visible mark only, not cryptographically verifiable.
outputFormatOutput format
outputPdf / outputWordPDF / Word (.docx)
signActionSign document
downloadDownload
demoNoticeDemo — signed with the Doconut demo certificate; output is watermarked.
signingNotEnabledSigning is not enabled on this server.
page / pages1 page / {n} pages

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í:

css
#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áhled200 — { token, name, pages, ext }
POST /DocImage.axd?sign=run (JSON body)Podepište nahraný soubor200 — { downloadToken, downloadName, watermarked }
GET /DocImage.axd?sign=download&token=<downloadToken>Streamujte podepsaný soubor200 — 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:

json
{
  "token": "GUID-from-open",
  "signature": { "kind": "Drawn", "payload": "<base64 PNG, no data: prefix>" },
  "placement": { "page": 1, "x": 0.58, "y": 0.80, "w": 0.32, "h": 0.12 },
  "meta": { "signerName": "Ada Lovelace", "reason": "I approve", "location": "London, UK" },
  "wordOutput": "pdf",
  "mode": "certified"
}
PolePoznámky
tokenToken z open
signature.kindDrawn, 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 / hNormalizovaný 0..1 z levého horního rohu, s x + w ≤ 1 a y + h ≤ 1
meta.signerName / reason / locationVolitelné. Každý je oříznut, prázdná hodnota je zahozena a každý je oříznut na 256 znaků
wordOutputpdf (výchozí) nebo docx; ignorováno pro PDF zdroje. Cokoliv jiného se stane pdf
modecertified (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.

CestaStavKdyTělo
any404Widget není povolenpouze stav
any405Špatná metoda (open a run potřebují POST, download potřebuje GET)pouze stav
open400Není multipart nahráníExpected a multipart file upload.
open400Žádný soubor, nebo prázdnýNo file uploaded.
open400Cokoliv jiného než .pdf nebo .docxSigning supports PDF and Word (.docx) files only.
open413Nahrání překračuje MaxUploadMb (ale ne limity IIS)File is too large.
run400Tělo není platný JSON, nebo je prázdnéMalformed request. / Empty request.
run400Token chybí nebo není GUIDInvalid token.
run404Nahrání vypršelo nebo nikdy nebylo otevřenoUpload expired — please re-open the file.
run400Žádný podpis, nebo žádné umístěníNo signature supplied. / No placement supplied.
run400Payload není base64, je prázdný, příliš velký, nebo není PNGSignature image is not valid base64. / Signature image is empty. / Signature image is too large. / The signature image must be a PNG.
run400Umístění je mimo stránkuThe signature or its placement is invalid.
run400Certifikovaný režim, placená licence a žádný certifikátNo signing certificate configured.
run400Certifikovaný režim s certifikátem mimo jeho platnostThe signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd.
open, run500Zpracování selhaloSanitizovaná zpráva
download400Token chybí nebo není GUIDpouze stav
download404Neznámý nebo vypršený tokenpouze stav

Kompletní cyklus s fetch:

javascript
// 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

  1. Nainstalujte plugin vedle hlavního balíčku, ve stejné verzi: Install-Package Doconut.NETFramework.Signer.

  2. Přidejte licenční soubor. Umístěte Doconut.Viewer.Signer.lic do stejné složky jako Doconut.Viewer.lic.

  3. 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.

  4. 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>
    csharp
    var 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 .pfx v App_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.

  5. 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. (nebo is 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:

csharp
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.
  • FarmKey musí 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ž RootPath chybí nebo je FarmKey kratší než 32 bajtů.
  • Nastavte RootPath na 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

csharp
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

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

Jedna viditelná podpisová značka umístěná jednou, plus volitelné metadata podepisujícího.

VisibleSignature and SignatureKind

csharp
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

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

Page je číslováno od 1; X, Y, W a H jsou normalizované 0..1 od levého horního rohu.

SignatureMode and WordOutput

csharp
public enum SignatureMode { Certified, Visual }   // Certified je výchozí
public enum WordOutput { Pdf, Docx }              // Pdf je výchozí; ignorováno pro PDF zdroje

SignResult

csharp
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

csharp
public sealed class SigningCertificate
{
    public byte[]? PfxBytes { get; init; }
    public string? PfxPath  { get; init; }
    public string  Password { get; init; } = "";
    public bool    HasMaterial { get; }   // PfxBytes 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

csharp
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říznakPříčinaOprava
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é oknoNainstalujte 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 pluginuPř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í souborOpravte 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#12Zkontrolujte 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íčeExportujte jej znovu se soukromým klíčem
new SigningCertificate { … } se nedaří zkompilovatProjekt používá C# 7.3, který nemůže nastavit init-only vlastnostiNastavte <LangVersion> na 9.0 nebo novější
Řešení DocumentSigner vyhazuje No IDocumentSigner is registered.SignerPlugin není registrovánPřidejte AddPlugin<SignerPlugin>() v DoconutHost.Initialize
Výstup je vodoznakemLicence 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átNakonfigurujte 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 widgetumaxRequestLength / maxAllowedContentLength jsou pod MaxUploadMbZvyš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ž MaxSignatureImageKbPošlete čistý base64 PNG v rámci limitu
open odpovídá 413 File is too large.Nahrání překračuje MaxUploadMbZvyš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číchWord výstup obsahuje podpis OOXML balíčku, který mnoho prohlížečů nezobrazujePodepiš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ůvoduKoncové body nemají podporu CORSPoskytněte UI ze stejného původu, nebo použijte reverse-proxy na DocImage.axd a /doconut-res
Téma se neaplikujeSelektor cílí na prvek uvnitř mountuCí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řes DoconutHost.Initialize, místo builder.Services.AddDoconut. Služby jako AddDoconutDistributedWidgets jdou do jeho druhého argumentu.
  • Koncové body jsou poskytovány pomocí DocImage.axd a skript pomocí DoconutResourceModule, oba registrovaní v Web.config, místo UseDoconut() a UseDoconutResources(). Widget potřebuje basePath: '/DocImage.axd'.
  • Selhání při spuštění se projevují jako prázdný 500 u 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á?