Plugin pro podepisování
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ť 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í | Kdy použít |
|---|---|
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í ve 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.NET8.SignerPro přichycení pluginu k verzi, kterou tato dokumentace popisuje, předávejte verzi samostatně:
dotnet add package Doconut.NET8.Signer --version 26.10.0Udržujte balíček Signer ve stejné verzi jako Doconut.NET8. ID balíčku je Doconut.NET8.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čten spolu s licencí prohlížeče.
Platformy. Plugin běží kdekoliv běží Doconut.NET8: Windows a Linux založený na glibc na x64 (ne Alpine ani jiné distribuce založené na musl). Na Linuxu nainstalujte knihovnu pro konfiguraci fontů před otevřením prvního dokumentu:
apt-get update && apt-get install -y libfontconfig1Na distribucích RHEL, Fedora a podobných je balíček fontconfig. Bez něj selže otevření dokumentu s chybou The system library libfontconfig1 is missing. Install it (Debian/Ubuntu: apt-get install -y libfontconfig1) and see the Linux section of the Doconut documentation.
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 C# fasáda potřebuje. Widget a jeho HTTP koncové body jsou samostatná volitelná funkce, AddSignerWidget() (viz Widget pro vložení).
Plugin potřebuje licenci, která poskytuje schopnost Signer. Bez ní AddDoconut() vyvolá výjimku při spuštění, ještě před tí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 | Odmítnuto: No signing certificate configured. | Čistý |
| Placená licence, certifikát vypršel nebo ještě není platný | Spustí se (s povoleným widgetem, je zaznamenáno varování) | Odmítnuto: The signing certificate expired on yyyy-MM-dd. | Čistý |
| Dočasná Demo/NFR licence, aktivní nebo vypršená | 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á. 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áří pravou 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í v C#
DocumentSigner je registrován pomocí AddDoconut() a získán z injekce závislostí. Jeho konstruktor je interní, takže jej nikdy new. 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ý proud, jeho příponu (".pdf" nebo ".docx"), požadavek a certifikát pro toto volání. Fasáda 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ý proud, plus jeho Extension (".pdf" nebo ".docx"), takže můžete pojmenovat soubor. Proud vlastníte vy: uvolněte jej, až budete hotovi.
Vizuální 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);Zdroj ve formátu Word je podepsán do PDF, pokud nepožadujete 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 návratu, když volání nemůže uspět:
| Výjimka | Zpráva | Kdy |
|---|---|---|
InvalidOperationException | No signing certificate configured. | Certifikovaný režim, placená licence a žádný certifikát nepředán |
InvalidOperationException | The signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd. | Certifikovaný režim s certifikátem mimo jeho 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 určuje, zda je podpis zapečetěn.
| Režim | Co vytváří | Certifikát | Ověřitelný |
|---|---|---|---|
SignatureMode.Certified (default) | Viditelný podpis plus digitální pečeť | Vyžadováno při placené licenci | Ano |
SignatureMode.Visual | Pouze viditelný podpis | Nikdy nepotřebný | Ne: je to obrázek |
Použijte Certified, když musí být podpis prokazatelný: schválení, smlouvy, cokoliv, co ověřovatel potřebuje zkontrolovat pro identitu a integritu. Použijte Visual, když potřebujete pouze vzhled podpisu, nebo nemáte certifikát. Dočasná licence obě označí vodoznakem.
PDF pečetě jsou oddělené PKCS#7 podpisy (adbe.pkcs7.detached) s SHA-256, pro klíče RSA nebo ECDSA. Nese 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 podpisy OOXML balíčků a nesou pouze certifikát podepisujícího.
Word dokumenty
Pro .docx zdroj, SignRequest.WordOutput volí výstup. Pro PDF zdroje se ignoruje, vždy se vytvoří 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 Wordu: do něj se vloží obrázek podpisu a také podpis OOXML balíčku | Omezená: ne každý prohlížeč zobrazuje podpisy OOXML balíčků |
Ponechte PDF, pokud příjemce nepotřebuje editovatelný Word soubor a neakceptuje omezenou podporu ověřovače.
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:
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 se neukládá do logu, nevrací se klientovi ani neukládá trvale a heslo se nikdy neobjeví v řádku logu ani ve zprávě o chybě.
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 s ním řetězec vydavatele, 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 neblokuje aplikaci: při spuštění se zaznamená jako varování a certifikované podpisy jsou odmítnuty, dokud není nahrazen. Vizuální 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 jiný účel, například TLS serverový certifikát, stále může podepisovat, ale zaznamená se jako varování a PDF čtečky označí 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, 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 (ikona zobrazuje klíč, pokud je soukromý klíč přítomen). Klikněte 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 se jednou zkontroluje, uvnitř AddDoconut(), takže špatně nastavený 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. | Znovu exportujte PFX se soukromým klíčem |
Jinak host zapíše 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.Varová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 se při spuštění nekontroluje. Certifikát, který předáte do SignAsync, se načte při podpisu, takže špatná cesta nebo heslo způsobí selhání tohoto 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; nechte null pro demo (vodoznakové) podepisování
});
});AddSignerWidget() bez argumentu povolí widget s výchozími nastaveními. Sám o sobě nepovoluje 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() odpovídá každý požadavek ?sign= s 404. Skript je stále poskytován, takže se widget načte a vykreslí svou oblast pro přetahování, pak při prvním požadavku 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 připojení nalezeno, a vrátí handle.
Podepisovatel nahrává PDF nebo soubor .docx, vytvoří podpis (Draw na plátně, Type jméno ve fontu pro podpis, nebo Image z PNG, JPG či GIF), přetáhne jej a změní 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 obsahuje vlastní CSS |
maxUploadMb | number | 25 | Kontrola pouze na klientovi, takže příliš velký soubor selže okamžitě. Limit na serveru je MaxUploadMb v AddSignerWidget |
maxSignatureKb | number | 512 | Limit na klientovi 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ý samoservisní 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í (ne znovu 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í, podepsání nebo stažení selže, nebo je soubor v režimu Image příliš velký | { message } |
Zpětné volání, které vyhodí výjimku, je zachyceno a zalogováno; nikdy neporuší tok widgetu.
Imperativní obsluha
| Metoda | Chování |
|---|---|
reset() | Vrátí se na obrazovku drop a vyčistí aktuální tok. Znovu nespustí onReady. Bez operace po destroy() |
loadFile(file) | Spustí tok s File. Bez operace, pokud widget není na své drop obrazovce; v případě potřeby nejprve zavolejte reset() |
destroy() | Odstraní posluchače, vyprázdní mount 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());Štítky
Každý řetězec má výchozí anglickou hodnotu; labels přepíše libovolnou podmnožinu a zbytek zůstane v angličtině. 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 (demoNoticePrefix, demoNoticeLink, demoNoticeSuffix) a aria-live oznámení.
Když open nebo run odpoví 404 bez JSON chyby, widget zobrazí signingNotEnabled. JSON chyba ze serveru má vždy přednost, takže zprávy jako vypršený upload zůstávají viditelné.
Tématizace
Widget přidá třídu dsw k elementu mount a načte jeho barvy, poloměr a fonty z CSS vlastních vlastností, takže jej můžete tematizovat, aniž byste zasahovali do jeho vnitřností:
#host.dsw {
--dsw-accent: #b0522b; /* odkazy, zaměření, aktivní režim */
--dsw-bg: #fffaf3;
--dsw-fg: #3b2a1a;
--dsw-muted: #8a7a68;
--dsw-border: #e0cbb0;
--dsw-radius: 14px;
--dsw-font: Georgia, "Times New Roman", serif;
--dsw-signature-font: "Segoe Script", "Brush Script MT", cursive; /* režim Type */
}Výchozí hodnoty: --dsw-accent: #2b6cb0, --dsw-bg: #ffffff, --dsw-fg: #1a202c, --dsw-muted: #718096, --dsw-border: #cbd5e0, --dsw-radius: 8px, systémový UI font a kurzívní podpisový font.
Vytvořte si vlastní frontend
Widget je klientem pro tuto HTTP smlouvu. Všechny tři cesty jsou pod cestou, kde je UseDoconut() namontován (obvykle /doconut), a 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 ?sign=open (multipart, jeden soubor) | Nahrajte PDF nebo .docx a otevřete jej pro náhled | 200 — { token, name, pages, ext } |
POST ?sign=run (JSON tělo) | Podepište nahraný soubor | 200 — { downloadToken, downloadName, watermarked } |
GET ?sign=download&token=<downloadToken> | Streamujte 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 k obrázku prohlížeče, {basePath}?token={token}&page={n}&thumb=1&width={px}; zobrazená stránka se stane placement.page.
Tělo run:
{
"token": "GUID-from-open",
"signature": { "kind": "Drawn", "payload": "<base64 PNG, no data: prefix>" },
"placement": { "page": 1, "x": 0.58, "y": 0.80, "w": 0.32, "h": 0.12 },
"meta": { "signerName": "Ada Lovelace", "reason": "I approve", "location": "London, UK" },
"wordOutput": "pdf",
"mode": "certified"
}| Pole | Poznámky |
|---|---|
token | Token z open |
signature.kind | Drawn, Typed nebo Image, bez ohledu 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 1 |
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. Cokoli jiného se změní na pdf |
mode | certified (výchozí) nebo visual. Cokoli 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 dobu 30 minut. Poté run a download odpovídají 404 a soubor musí být znovu otevřen. Všechny tokeny jsou GUIDy.
| Cesta | Stav | Kdy | Tělo |
|---|---|---|---|
| any | 404 | Widget není povolen | pouze stav |
| any | 405 | Špatná metoda (open a run potřebují POST, download potřebuje GET) | pouze stav |
open | 400 | Není multipart upload | Expected a multipart file upload. |
open | 400 | Žádný soubor, nebo prázdný | No file uploaded. |
open | 400 | Cokoliv jiného než .pdf nebo .docx | Signing supports PDF and Word (.docx) files only. |
open | 413 | 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 nebyl nikdy otevřen | Upload expired — please re-open the file. |
run | 400 | Žádný podpis, nebo žádné umístění | No signature supplied. / No placement supplied. |
run | 400 | Payload není base64, je prázdný, příliš velký, nebo není PNG | Signature image is not valid base64. / Signature image is empty. / Signature image is too large. / The signature image must be a PNG. |
run | 400 | Umístění je mimo stránku | The signature or its placement is invalid. |
run | 400 | Certifikovaný režim, placená licence a žádný certifikát | No signing certificate configured. |
run | 400 | Certifikovaný režim s certifikátem mimo 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 | Očistěná zpráva |
download | 400 | Token chybí nebo není GUID | pouze stav |
download | 404 | Neznámý nebo vypršený token | pouze stav |
Kompletní cyklus s fetch:
// file: File k podepsání; pngBase64: podpis jako čistý base64 PNG, bez prefixu data:,
// například canvas.toDataURL('image/png').split(',')[1].
async function signFile(file, pngBase64) {
const base = '/doconut';
// 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 Doconut, nebo provádějte reverzní proxy obě /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.NET8.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, takže jeho změna nikdy nevyžaduje změnu 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ěřujte PDF čtečkám. Čtečka zobrazuje podpis jako platný, když 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é 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ý upload a jeho výsledek v paměti na uzlu, který obsloužil open. Za load balancerem bez sticky sessions může pozdější run, download nebo požadavek na náhled dosáhnout jiného uzlu a nenajít upload. 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ý node číst i zapisovat
store.FarmKey = farmKey; // alespoň 32 bajtů, identické na každém node
// 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.
- Uploady 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 poskytněte 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í dependency injection; 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 podpisovatele.
VisibleSignature and SignatureKind
public sealed record VisibleSignature(SignatureKind Kind, byte[] PngBytes)
{
public bool IsValid { get; } // PngBytes není prázdný
}
public enum SignatureKind { Drawn, Typed, Image }PngBytes je PNG pro každý typ. Nakreslený nebo napsaný podpis je průhledný; nahraný obrázek si zachovává svou průhlednost, takže neprůhledný JPG zůstává neprůhledný. Kind je jen nápověda.
SignaturePlacement
public readonly record struct SignaturePlacement(int Page, double X, double Y, double W, double H)
{
public bool IsValid { get; } // Page >= 1; X, Y >= 0; W, H > 0; X + W <= 1; Y + H <= 1
}Page je číslováno od jedné; 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ýdefault; ignorováno pro PDF zdrojeSignResult
public sealed record SignResult(Stream Stream, string Extension);Podepsaný dokument jako seekovatelný stream a jeho přípona s tečkou (".pdf" nebo ".docx").
SigningCertificate
public sealed class SigningCertificate
{
public byte[]? PfxBytes { get; init; }
public string? PfxPath { get; init; }
public string Password { get; init; } = "";
public bool HasMaterial { get; } // PfxBytes není prázdný, nebo PfxPath není prázdný
}Nastavte buď PfxBytes nebo PfxPath, plus Password.
SignerWidgetOptions
public sealed class SignerWidgetOptions
{
public int MaxUploadMb { get; set; } = 25;
public int MaxSignatureImageKb { get; set; } = 512;
public SigningCertificate? SigningCertificate { get; set; }
}Nastavte přes DoconutOptions.AddSignerWidget(Action<SignerWidgetOptions>? configure = null), který vrací DoconutOptions, takže volání lze řetězit. Null SigningCertificate znamená demo certifikát pod dočasnou licencí a vizuální podpisy jen pod placenou licencí.
Řešení problémů
| Příznak | Příčina | Řešení |
|---|---|---|
AddDoconut() vyvolá 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() vyvolá 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() vyvolá Doconut Signer: the certificate file was not found at '{path}'. | PfxPath ukazuje na chybějící soubor | Opravte cestu; nasadíte soubor tam, kde jej může číst účet aplikace |
AddDoconut() vyvolá Doconut Signer: the signing certificate could not be opened — the password is incorrect or the file is not a valid .pfx. | Špatné heslo nebo nejedná se o soubor PKCS#12 | Zkontrolujte heslo; použijte skutečný .pfx |
AddDoconut() vyvolá 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 |
Řešení DocumentSigner vyvolá 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 odpovídá 400 No signing certificate configured. | Placená licence, Certified režim a žádný certifikát | Nakonfigurujte SigningCertificate, nebo podepište ve vizuálním režimu |
run odpovídá 400 The signing certificate expired on yyyy-MM-dd. | Certifikát je neplatný | Vyměňte jej; vizuální podpisy mezitím fungují |
| Log říká, že výstup "používá vestavěný demo certifikát", ale placená licence odmítá Certified 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 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 URL data:, JPG, nebo více než MaxSignatureImageKb | Pošlete čistý base64 PNG v rámci limitu |
open odpovídá 413 File is too large. | Nahrávání překračuje MaxUploadMb | Zvyšte MaxUploadMb v AddSignerWidget; widgetův maxUploadMb je jen kontrola na straně klienta |
run nebo download odpovídá 404 Upload expired — please re-open the file. | 30minutové okno vypršelo, nebo uzel web-farmy nemá nahraný soubor | Otevřete soubor znovu; ve farmě zaregistrujte AddDoconutDistributedWidgets |
Podepsaný .docx neukazuje žádný podpis v některých prohlížečích | Word výstup obsahuje podpis OOXML balíčku, který mnoho prohlížečů nezobrazuje | Podepište do PDF, výchozí |
| PDF čtečky říkají, že identita podpisovatele je neznámá | Čtečka nedůvěřuje kořeni 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 originu | Endpointy nemají podporu CORS | Poskytněte UI ze stejného originu, nebo použijte reverse-proxy pro cesty Doconut |
| Motiv se neaplikuje | Selektor cílí na prvek uvnitř mountu | Cílovat samotný mount: #host.dsw nebo #host |
Byla tato stránka užitečná?