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:
dotnet add package Doconut.NETStandard.SignerPro připnutí pluginu k verzi, kterou tato dokumentace popisuje, předávejte verzi samostatně:
dotnet add package Doconut.NETStandard.Signer --version 26.10.0Udrž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():
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:
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 licence | Spuštění | Certifikovaný podpis | Vizuální podpis |
|---|---|---|---|
Placená licence poskytující Signer, certifikát nakonfigurován | Spustí se | Zapečetěno vaším certifikátem, čisté (watermarked: false) | Čisté |
Placená licence poskytující Signer, bez certifikátu | Spustí se | Refused: 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í se | 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 | AddDoconut() 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>().
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:
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:
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ýjimka | Zpráva | Kdy |
|---|---|---|
InvalidOperationException | No signing certificate configured. | Certifikovaný režim, placená licence a žádný certifikát nebyl př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 platnost |
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 volí, 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 v 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é 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ýstup | Co se stane | Podpora 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.Docx | Dokument zůstane ve formátu Word: do něj se vloží obrázek podpisu a také OOXML balíčkový podpis | Omezená: 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:
builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
options.AddSignerWidget(widget =>
{
widget.SigningCertificate = new SigningCertificate
{
PfxBytes = File.ReadAllBytes("/secure/signing.pfx"),
Password = builder.Configuration["Signing:PfxPassword"],
};
});
});builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
options.AddSignerWidget(widget =>
{
widget.SigningCertificate = new SigningCertificate
{
PfxPath = "/secure/signing.pfx",
Password = builder.Configuration["Signing:PfxPassword"],
};
});
});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:
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áva | Oprava |
|---|---|
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:
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ů:
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:
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:
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í:
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í:
<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žnost | Typ | Výchozí | Poznámky |
|---|---|---|---|
basePath | string | '/doconut' | Kde jsou poskytovány koncové body ?sign= a náhledové obrázky |
resPath | string | '/doconut-res' | Rezervováno; widget balí vlastní CSS |
maxUploadMb | number | 25 | Pouze kontrola na straně klienta, takže příliš velký soubor selže rychle. Limit na serveru je MaxUploadMb v AddSignerWidget |
maxSignatureKb | number | 512 | Limit na straně klienta pro režim Image. Udržujte ho stejný jako serverový MaxSignatureImageKb |
previewWidth | number | 560 | Šířka náhledu stránky v pixelech |
licenseUrl | string | null | null | Přemění oznámení 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 Digital signature / Visual only. 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řepíše libovolnou podmnožinu anglických řetězců |
Skrytí přepínače nezakáže funkci; pouze fixuje hodnotu. Dvě běžné konfigurace:
// Oba přepínače zobrazeny, digitální podpis jako výchozí: plnohodnotný samoobslužný podepisovač.
Doconut.signer('#host', { basePath: '/doconut', licenseUrl: '/pricing' });// 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 |
|---|---|---|
onReady | Jednou při připojení (znovu ne při reset()) | — |
onSourceLoaded | Soubor je otevřen a jeho náhled zobrazen | { file: { token, name, pages, ext } } |
onSigned | Podepsání uspěje | { 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í ovládání
| Metoda | Chová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 |
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 |
|---|---|
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 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:
#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áhled | 200 — { token, name, pages, ext } |
POST ?sign=run (JSON tělo) | Podepsat nahraný soubor | 200 — { downloadToken, downloadName, watermarked } |
GET ?sign=download&token=<downloadToken> | Streamovat podepsaný soubor | 200 — 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:
{
"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, 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 / 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 změní na pdf |
mode | certified (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.
| Cesta | Stav | Kdy | Tělo |
|---|---|---|---|
| any | 404 | Widget není povolen | status only |
| any | 405 | Špatná metoda (open a run vyžadují POST, download potřebuje GET) | status only |
open | 400 | Není multipart upload | Expected a multipart file upload. |
open | 400 | Chybí soubor nebo je prázdný | No file uploaded. |
open | 400 | Cokoliv jiného než .pdf nebo .docx | Signing supports PDF and Word (.docx) files only. |
open | 413 | Upload překračuje MaxUploadMb | 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 | Upload vypršel nebo nikdy nebyl otevřen | Upload expired — please re-open the file. |
run | 400 | Chybí podpis nebo 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 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 | status only |
download | 404 | Neznámý nebo vypršelý token | status only |
Kompletní round‑trip s fetch:
// 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);
}Koncové 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
-
Nainstalujte plugin vedle hlavního balíčku, ve stejné verzi:
dotnet add package Doconut.NETStandard.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.
-
Čtěte certifikát z konfigurace, aby jeho změna nikdy nevyžadovala úpravu kódu:
json"DoconutSigner": { "PfxPath": "certs/your-certificate.pfx" }csharpvar signerSettings = builder.Configuration.GetSection("DoconutSigner"); builder.Services.AddDoconut(options => { options.LicensePath = "Doconut.Viewer.lic"; options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>(); options.AddSignerWidget(widget => widget.SigningCertificate = new SigningCertificate { PfxPath = Path.Combine(builder.Environment.ContentRootPath, signerSettings["PfxPath"]), Password = signerSettings["Password"] ?? "", }); });Uchovávejte
.pfxmimowwwroota držte heslo mimoappsettings.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. -
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():
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.
FarmKeymusí 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ž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 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
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
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
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
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
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 vyhledávatelný proud 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.
SignerWidgetOptions
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říznak | Příčina | Oprava |
|---|---|---|
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é okno | Nainstalujte 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 pluginu | Př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í soubor | Opravte 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#12 | Zkontrolujte 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íče | Exportujte jej znovu se soukromým klíčem |
Resolving DocumentSigner throws No IDocumentSigner is registered. | SignerPlugin není registrován | Přidejte AddPlugin<SignerPlugin>() uvnitř AddDoconut() |
| Výstup je vodoznakem | Licence 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át | Nakonfigurujte 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é podpisy | Tento řádek je zapsán vždy, když není nastaven žádný certifikát, bez ohledu na licenci | Nakonfigurujte 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án | Zavolejte 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ž MaxSignatureImageKb | Pošlete čistý base64 PNG v rámci limitu |
open answers 413 File is too large. | Nahrání překračuje MaxUploadMb | Zvyš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 podpis | Word výstup obsahuje OOXML balíčkový podpis, který mnoho prohlížečů nezobrazuje | Podepiš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ího | Použ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ůvodu | Koncové body nemají podporu CORS | Poskytněte UI ze stejného původu, nebo použijte reverse-proxy pro cesty Doconut |
| Téma se neaplikuje | Selektor cílí na prvek uvnitř mountu | Cílovat samotný mount: #host.dsw nebo #host |
Byla tato stránka užitečná?