Plugin Signer

Podepisujte PDF a Word dokumenty viditelným podpisem a digitální pečetí

Plugin Signer umisťuje viditelný podpis do dokumentu a ve výchozím nastavení jej zapečeťuje digitálním podpisem, který může PDF čtečka ověřit. 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
Drop-in widget (doconutSigner.js)Chcete připravenou obrazovku pro nahrání, podepsání a stažení na své stránce
HTTP endpoints (?sign=open|run|download)Vytvoříte si 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 být s ním spojeny.

Instalace balíčku

Nainstalujte nejnovější stabilní plugin Signer:

bash
dotnet add package Doconut.NETStandard.Signer

Pro připnutí pluginu k verzi, kterou tato dokumentace popisuje, předávejte verzi samostatně:

bash
dotnet add package Doconut.NETStandard.Signer --version 26.10.0

Udržujte balíček Signer ve stejné verzi jako Doconut.NETStandard. ID balíčku je Doconut.NETStandard.Signer; .<version> se objevuje pouze v názvu staženého souboru .nupkg.

Licenční soubor pluginu, Doconut.Viewer.Signer.lic, umístěte do stejné složky jako Doconut.Viewer.lic; je načítán společně s licencí prohlížeče.

Registrace pluginu

Stejně jako každý Doconut plugin, Signer se registruje pomocí AddPlugin<TPlugin>() uvnitř AddDoconut():

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
});

To je vše, co potřebuje C# fasáda. 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í AddDoconut() vyvolá výjimku při spuštění, ještě předtím, než aplikace obslouží požadavek:

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.

Vyvolá výjimku při chybějící licenci, 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 pro způsob načítání licencí.

Licencování a vodoznak

Stav licenceSpuštěníCertifikovaný podpisVizuální podpis
Placená licence poskytující Signer, certifikát nakonfigurovánSpustí seZapečetěno vaším certifikátem, čisté (watermarked: false)Čisté
Placená licence poskytující Signer, bez certifikátuSpustí seRefused: No signing certificate configured.Čisté
Placená licence, certifikát prošel nebo ještě není platnýSpustí se (s povoleným widgetem, je zaznamenáno varování)Refused: The signing certificate expired on yyyy-MM-dd.Čisté
Dočasná Demo/NFR licence, aktivní nebo prošláSpustí seZapeč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é oknoAddDoconut() vyvolá výjimku——

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á. Při dočasné licenci 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áří skutečnou 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í AddDoconut() a získán z dependency injection. Jeho konstruktor je interní, takže ho nikdy nenew. Pokus o získání 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 má výchozí hodnotu Certified (viditelný podpis + digitální pečeť); WordOutput má výchozí hodnotu Pdf.

        SignResult result = await _signer.SignAsync(pdf, ".pdf", request, certificate, ct);
        using (result.Stream)
        using (var output = new MemoryStream())
        {
            await result.Stream.CopyToAsync(output, ct);
            return output.ToArray();
        }
    }
}

SignAsync přijímá 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"), takže můžete pojmenovat soubor. Vlastníte stream: uvolněte jej, až budete hotovi.

Visual podpis pouze otiskne obrázek a nevyžaduje žádný certifikát:

csharp
var signer = app.Services.GetRequiredService<DocumentSigner>();
byte[] signaturePng = File.ReadAllBytes("signature.png");

var request = new SignRequest(
    new VisibleSignature(SignatureKind.Image, signaturePng),
    new SignaturePlacement(Page: 1, X: 0.58, Y: 0.80, W: 0.32, H: 0.12),
    Mode: SignatureMode.Visual);

SignResult result = await signer.SignAsync(stream, ".pdf", request, ct: ct);

Wordový zdroj je podepsán do PDF, pokud nepožádáte o výstup ve Wordu. Pojmenujte výsledek z result.Extension:

csharp
var signer = app.Services.GetRequiredService<DocumentSigner>();
byte[] signaturePng = File.ReadAllBytes("signature.png");

var request = new SignRequest(
    new VisibleSignature(SignatureKind.Drawn, signaturePng),
    new SignaturePlacement(Page: 1, X: 0.58, Y: 0.80, W: 0.32, H: 0.12),
    WordOutput: WordOutput.Docx);

SignResult result = await signer.SignAsync(stream, ".docx", request, ct: ct);
string downloadName = "contract-signed" + result.Extension;   // ".docx"

SignAsync 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 nebyl př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 platnost
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 volí, 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 v 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é PKCS#7 podpisy (adbe.pkcs7.detached) s SHA-256, pro RSA nebo ECDSA klíče. Nesou certifikáty vydavatele nalezené ve vašem PFX, takže čtečka, která důvěřuje vašemu kořeni, může vytvořit řetězec. Wordové nativní pečetě jsou OOXML balíčkové podpisy a nesou pouze certifikát podepisujícího.

Word dokumenty

Pro .docx zdroj SignRequest.WordOutput vybírá výstup. Pro PDF zdroje se ignoruje, vždy vytváří PDF.

VýstupCo se stanePodpora ověřovače
WordOutput.Pdf (výchozí)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 formátu Word: do něj se vloží obrázek podpisu a také OOXML balíčkový podpisOmezená: ne každý prohlížeč zobrazuje OOXML balíčkové podpisy

Ponechte PDF, pokud příjemce nepotřebuje editovatelný Word soubor a neakceptuje omezenou podporu ověřovače.

Nastavení certifikátu

Cílem je zapečetět 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:

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
    options.AddSignerWidget(widget =>
    {
        widget.SigningCertificate = new SigningCertificate
        {
            PfxBytes = File.ReadAllBytes("/secure/signing.pfx"),
            Password = builder.Configuration["Signing:PfxPassword"],
        };
    });
});
csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
    options.AddSignerWidget(widget =>
    {
        widget.SigningCertificate = new SigningCertificate
        {
            PfxPath = "/secure/signing.pfx",
            Password = builder.Configuration["Signing:PfxPassword"],
        };
    });
});

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 řádku logu ani 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 spolu s ním, aby PDF pečetě mohly být přenášeny.
  • Správné heslo.
  • V rámci jeho období platnosti. Expirující nebo ještě neplatný certifikát neblokuje aplikaci: při spuštění se zaznamená jako Upozornění a certifikované podpisy jsou odmítnuty, dokud není nahrazen. Vizuální podpisy zůstávají nedotčeny.
  • 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 jiný účel, například TLS serverový certifikát, stále podepisuje, ale je zaznamenán jako Upozornění a PDF čtečky označují podpis.
  • Hardwarové tokeny, čipové karty, HSM a úložiště certifikátů Windows nejsou podporovány. Exportujte certifikát 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, o 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 (ikona ukazuje klíč, pokud je soukromý klíč přítomen). Klikněte pravým tlačítkem, zvolte Všechny úkoly → Export…, vyberte Ano, exportovat soukromý klíč, zvolte Osobní výměna informací – PKCS #12 (.PFX) a nastavte heslo.

Kontroly při spuštění

Když je widget povolen, certifikát v SignerWidgetOptions.SigningCertificate je jednou zkontrolován, uvnitř AddDoconut(), takže špatně nakonfigurovaný PFX selže při spuštění místo při prvním podpisu. Tři problémy vyvolají InvalidOperationException:

ZprávaOprava
Doconut Signer: the certificate file was not found at '{path}'.Opravte PfxPath; ujistěte se, že soubor je nasazen a čitelný účtem aplikace
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 se soukromým klíčem

Jinak host zapisuje jeden řádek do logu při spuštění. Informace, když je certifikát připraven:

text
Doconut Signer: using certificate '{subject}' (valid until yyyy-MM-dd). Signatures are digitally sealed.

Upozornění, když je expirovaný, ještě neplatný nebo není vydán pro podepisování dokumentů:

text
Doconut Signer: the signing certificate '{subject}' expired on yyyy-MM-dd. Certified signatures will be refused until it is replaced.
Doconut Signer: the signing certificate '{subject}' is not valid before yyyy-MM-dd. Certified signatures will be refused until then.
Doconut Signer: the signing certificate '{subject}' is not issued for document signing (its key usage excludes it). PDF readers will flag these signatures.

A informace, když není nastaven žádný certifikát:

text
Doconut Signer: no signing certificate configured — output uses the built-in demo certificate and is watermarked. Set SignerWidgetOptions.SigningCertificate to sign with your own certificate.

Poslední řádek je stejný u všech licencí. U placené licence se demo certifikát nikdy nepoužívá: bez certifikátu fungují jen vizuální podpisy.

C# fasáda není kontrolována 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 selže při tomto volání.

Widget pro vložení

Povolit koncové body

Koncové body ?sign=open|run|download widgetu jsou ve výchozím nastavení vypnuté. Povolit je vedle registrace pluginu:

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath = "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í certifikátu; ponechte null pro demo (vodoznakové) podepisování
    });
});

AddSignerWidget() bez argumentu povolí widget s výchozími nastaveními. Sám o sobě nepřiděluje podepisování: potřebuje AddPlugin<SignerPlugin>(), nebo AddDoconut() vyhodí:

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.

Bez AddSignerWidget() každá žádost ?sign= odpovídá 404. Skript je stále poskytován, takže se widget načte a vykreslí svou oblast pro přetažení, poté při první žádosti nahlásí Signing is not enabled on this server..

Vložit jej

UseDoconutResources() poskytuje skript na adrese {ResourcesPath}/js/doconutSigner.js (výchozí /doconut-res/js/doconutSigner.js). Jedná se o jediný, samostatný soubor bez závislostí:

html
<div id="host"></div>
<script src="/doconut-res/js/doconutSigner.js"></script>
<script>
  const handle = Doconut.signer('#host', { basePath: '/doconut' });
</script>

Doconut.signer(selectorOrElement, options) přijímá CSS selektor nebo element, vyhodí chybu, pokud není místo nalezeno, a vrátí handle.

Podepisující nahrává PDF nebo soubor .docx, vytvoří podpis (Draw na plátně, Type jméno v podpisovém fontu, nebo Image z PNG, JPG nebo GIF), přetáhne a změní jeho velikost na stránce a podepíše a stáhne 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 koncové body ?sign= a náhledové obrázky
resPathstring'/doconut-res'Rezervováno; widget balí vlastní CSS
maxUploadMbnumber25Pouze kontrola na straně klienta, takže příliš velký soubor selže rychle. Limit na serveru je MaxUploadMb v AddSignerWidget
maxSignatureKbnumber512Limit na straně klienta pro režim Image. Udržujte ho stejný jako serverový MaxSignatureImageKb
previewWidthnumber560Šířka náhledu stránky v pixelech
licenseUrlstring | nullnullPřemění oznámení 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 Digital signature / Visual only. 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řepíše libovolnou podmnožinu anglických řetězců

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

javascript
// Oba přepínače zobrazeny, digitální podpis jako výchozí: plnohodnotný samoobslužný podepisovač.
Doconut.signer('#host', { basePath: '/doconut', licenseUrl: '/pricing' });
javascript
// Pouze vizuální, bez přepínače: jednoduché razítko bez digitálního podpisu.
Doconut.signer('#host', {
  basePath: '/doconut',
  signatureMode: 'visual',
  showSignatureModeToggle: false
});

Zpětná volání

Zpětné voláníSpouští se, kdyžData
onReadyJednou při připojení (znovu ne při reset())—
onSourceLoadedSoubor je otevřen a jeho náhled zobrazen{ file: { token, name, pages, ext } }
onSignedPodepsání uspěje{ 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í ovládání

MetodaChování
reset()Vrátí se na obrazovku pro přetažení a vymaže aktuální tok. Znovu nevyvolá onReady. Žádná operace po destroy()
loadFile(file)Spustí tok s File. Žádná operace, pokud widget není na obrazovce pro přetažení; v případě potřeby nejprve zavolejte reset()
destroy()Odstraní posluchače, vyprázdní připojení a zmrazí instanci
javascript
const signerWidget = Doconut.signer('#host', {
  basePath: '/doconut',
  onSigned: (result) => console.log('signed', result.downloadName, result.watermarked),
  onError: (error) => console.warn(error.message)
});
document.getElementById('start-over').addEventListener('click', () => signerWidget.reset());

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íčVýchozí anglický text
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 verze (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řebije, takže zprávy jako „vypršelý upload“ zůstávají viditelné.

Tématizace

Widget přidá třídu dsw k elementu připojení a načte jeho barvy, poloměry a fonty z CSS vlastních proměnných, takže jej můžete tematizovat, aniž byste zasahovali do jeho vnitřní struktury:

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 font a kurzívní font pro podpis.

Vytvořte si vlastní frontend

Widget je klientem pro tuto HTTP smlouvu. Všechny tři cesty jsou pod cestou, kde je připojen UseDoconut() (obvykle /doconut), a odpovídají 404, dokud není zavoláno AddSignerWidget(). Chyby obsahují 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 ?sign=open (multipart, jeden soubor)Nahrát PDF nebo .docx a otevřít jej pro náhled200 — { token, name, pages, ext }
POST ?sign=run (JSON tělo)Podepsat nahraný soubor200 — { downloadToken, downloadName, watermarked }
GET ?sign=download&token=<downloadToken>Streamovat podepsaný soubor200 — soubor, Content-Disposition: attachment, Cache-Control: no-store

ext v odpovědi open obsahuje úvodní tečku (".docx"). Náhled stránky používá standardní cestu pro obrázek prohlížeče, {basePath}?token={token}&page={n}&thumb=1&width={px}; zobrazovaná 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, neberoucí ohled na velikost písmen; cokoli jiného se změní na Drawn. Pouze nápověda: payload je vždy PNG
signature.payloadČistý base64 PNG bez prefixu data:. Musí to být skutečný PNG a po dekódování nesmí být větší než MaxSignatureImageKb
placement.pageČíslování 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 změní na pdf
modecertified (výchozí) nebo visual. Cokoliv jiného se změní na 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 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í povolenstatus only
any405Špatná metoda (open a run vyžadují POST, download potřebuje GET)status only
open400Není multipart uploadExpected a multipart file upload.
open400Chybí soubor nebo je prázdnýNo file uploaded.
open400Cokoliv jiného než .pdf nebo .docxSigning supports PDF and Word (.docx) files only.
open413Upload překračuje MaxUploadMbFile is too large.
run400Tělo není platný JSON nebo je prázdnéMalformed request. / Empty request.
run400Token chybí nebo není GUIDInvalid token.
run404Upload vypršel nebo nikdy nebyl otevřenUpload expired — please re-open the file.
run400Chybí podpis nebo 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 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í GUIDstatus only
download404Neznámý nebo vypršelý tokenstatus only

Kompletní round‑trip s fetch:

javascript
// file: soubor k podepsání; 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 = '/doconut';

  // 1. open: nahrát 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: podepsat ho
  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áhnout 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);
}

Kon­cové body jsou same-origin: tato verze nepodporuje CORS. Servírujte své UI a skript widgetu ze stejného původu jako Doconut, nebo reverzní proxy oba /doconut cesty (cestu middleware a cestu zdrojů) pod původem vašeho UI.

V produkci

  1. Nainstalujte plugin vedle hlavního balíčku, ve stejné verzi: dotnet add package Doconut.NETStandard.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. Čtěte certifikát z konfigurace, aby jeho změna nikdy nevyžadovala úpravu kódu:

    json
    "DoconutSigner": { "PfxPath": "certs/your-certificate.pfx" }
    csharp
    var signerSettings = builder.Configuration.GetSection("DoconutSigner");
    
    builder.Services.AddDoconut(options =>
    {
        options.LicensePath = "Doconut.Viewer.lic";
        options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
        options.AddSignerWidget(widget => widget.SigningCertificate = new SigningCertificate
        {
            PfxPath = Path.Combine(builder.Environment.ContentRootPath, signerSettings["PfxPath"]),
            Password = signerSettings["Password"] ?? "",
        });
    });

    Uchovávejte .pfx mimo wwwroot a držte heslo mimo appsettings.json: uživatelské tajemství v vývoji (dotnet user-secrets set "DoconutSigner:Password" "<password>"), proměnnou prostředí (DoconutSigner__Password) nebo úložiště v produkci.

  5. Zkontrolujte spouštěcí log. Měl by obsahovat using certificate '{subject}' (valid until …). Signatures are digitally sealed.. Varování místo toho znamená, že certifikát je prošlý, ještě není platný, nebo není vydán pro podepisování dokumentů.

Důvěra v PDF čtečky. Čtečka zobrazuje podpis jako platný, když důvěřuje kořeni certifikátu. S PKI vaší organizace to platí na každém počítači, který důvěřuje vašemu kořeni, což je obvykle každý počítač uvnitř organizace. Certifikáty, které 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 uzlu, který obsloužil open. Za load balancerem bez sticky session může pozdější run, download nebo požadavek na náhled dorazit na jiný uzel a nenajít nahrané soubory. Zaregistrujte sdílené, šifrované úložiště widgetu jednou, po AddDoconut():

csharp
byte[] farmKey = Convert.FromBase64String(builder.Configuration["Doconut:FarmKey"]);

builder.Services.AddDoconutDistributedWidgets(store =>
{
    store.RootPath = @"\\fileshare\doconut";   // složka, kterou může každý uzel číst i zapisovat
    store.FarmKey = farmKey;                   // alespoň 32 bajtů, identické na každém uzlu
    // store.Ttl = TimeSpan.FromMinutes(30);   // jak dlouho je nahrání uchováno (výchozí)
});
  • Jeden server nepotřebuje nic: bez tohoto volání se používá úložiště v paměti.
  • Nahrané soubory 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 uzlu. Načtěte jej z tajného úložiště; nikdy jej nezakódujte 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 uzlu stejný podpisový certifikát.

Referenční API

Fasáda a možnosti widgetu jsou v jmenném prostoru 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);
}

Získáno pomocí injekce závislostí; 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á podpis 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 zachovává svou průhlednost, takže neprůhledný JPG zůstává neprůhledný. Kind je jen vodítko.

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 založeno na 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 vyhledávatelný proud 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.

SignerWidgetOptions

csharp
public sealed class SignerWidgetOptions
{
    public int MaxUploadMb { get; set; } = 25;
    public int MaxSignatureImageKb { get; set; } = 512;
    public SigningCertificate? SigningCertificate { get; set; }
}

Nastavte pomocí 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
AddDoconut() throws 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>()
AddDoconut() throws AddSignerWidget() was called but the Signer plugin is not registered.Widget je povolen bez svého pluginuPřidejte options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>()
AddDoconut() throws Doconut Signer: the certificate file was not found at '{path}'.PfxPath ukazuje na chybějící souborOpravte cestu; nasadte soubor tam, kde jej může číst účet aplikace
AddDoconut() throws Doconut Signer: the signing certificate could not be opened — the password is incorrect or the file is not a valid .pfx.Špatné heslo, nebo není soubor PKCS#12Zkontrolujte heslo; použijte skutečný .pfx
AddDoconut() throws 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
Resolving DocumentSigner throws No IDocumentSigner is registered.SignerPlugin není registrovánPřidejte AddPlugin<SignerPlugin>() uvnitř AddDoconut()
Výstup je vodoznakemLicence je dočasná (Demo/NFR)Použijte placenou licenci, která poskytuje Signer
run answers 400 No signing certificate configured.Placena licence, Certified režim, a žádný certifikátNakonfigurujte SigningCertificate, nebo podepište ve vizuálním režimu
run answers 400 The signing certificate expired on yyyy-MM-dd.Certifikát je neplatnýVyměňte jej; vizuální podpisy mezitím fungují
Log uvádí, že výstup „používá vestavěný demo certifikát“, přesto placená licence odmítá certifikované podpisyTento řádek je zapsán vždy, když není nastaven žádný certifikát, bez ohledu na licenciNakonfigurujte SigningCertificate
Widget se načte, ale říká Signing is not enabled on this server.AddSignerWidget() nebyl zavolán, nebo basePath neodpovídá místu, kde je UseDoconut() namontovánZavolejte AddSignerWidget(); opravte basePath
run answers 400 The signature image must be a PNG., Signature image is not valid base64. or Signature image is too large.Vlastní UI poslala URL data:, JPG, nebo více než MaxSignatureImageKbPošlete čistý base64 PNG v rámci limitu
open answers 413 File is too large.Nahrání překračuje MaxUploadMbZvyšte MaxUploadMb v AddSignerWidget; maxUploadMb widgetu je jen kontrola na straně klienta
run or download answers 404 Upload expired — please re-open the file.30minutové okno uplynulo, nebo uzel web-farmy nemá nahráníOtevřete soubor znovu; ve farmě zaregistrujte AddDoconutDistributedWidgets
Podepsaný .docx v některých prohlížečích neukazuje podpisWord výstup obsahuje OOXML balíčkový podpis, který mnoho prohlížečů nezobrazujePodepište do PDF, výchozí
PDF čtečky uvádějí, že identita podepisujícího je neznámáČtečka PDF nezná identitu podepisujícíhoPoužijte certifikát z kořene, kterému vaše čtečky důvěřují
Widget selhává, když je UI na jiném původuKoncové body nemají podporu CORSPoskytněte UI ze stejného původu, nebo použijte reverse-proxy pro cesty Doconut
Téma se neaplikujeSelektor cílí na prvek uvnitř mountuCílovat samotný mount: #host.dsw nebo #host

Byla tato stránka užitečná?