Plugin pro podepisování
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í | 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í uživatelské rozhraní pro podepisování podle zdokumentované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 uloženy.
Instalace balíčku
Nainstalujte nejnovější stabilní plugin Signer:
dotnet add package Doconut.NET6.SignerPro připnutí pluginu k verzi, kterou tato dokumentace popisuje, předávejte verzi samostatně:
dotnet add package Doconut.NET6.Signer --version 26.10.0Udržujte balíček Signer ve stejné verzi jako Doconut.NET6. ID balíčku je Doconut.NET6.Signer; .<version> se objevuje jen 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 Doconut.NET6 běží: 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() vyhodí výjimku při spuštění, 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.Vyhodí 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, vodoznak (watermarked: true) | S vodoznakem |
Žádná licence, starý soubor TRIAL, licence bez Signer, nebo placená licence mimo její časové okno | AddDoconut() vyhodí | — | — |
Pravidlo je stejné pro C# fasádu i widget: výstup je opatřen vodoznakem, pokud licence není placenou licencí 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í 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 výchozí hodnota je Certified (viditelný podpis + digitální pečeť); WordOutput výchozí hodnota je 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á vstupní stream, jeho příponu (".pdf" nebo ".docx"), požadavek a certifikát pro toto volání. Facade nečte SignerWidgetOptions.SigningCertificate; toto nastavení je určeno pro widget. Předávejte null pod demo licencí, nebo ve Visual režimu.
SignResult obsahuje podepsaný dokument jako seekovatelný stream, plus jeho Extension (".pdf" nebo ".docx"), abyste mohli pojmenovat soubor. Vlastníte stream: uvolněte jej, 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);Word zdroj 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 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 určuje, zda je podpis zapečetěn.
| Režim | Co vytváří | Certifikát | Ověřitelný |
|---|---|---|---|
SignatureMode.Certified (výchozí) | Viditelný podpis plus digitální pečeť | Vyžadováno pod placenou licencí | 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četi 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řenu, může vytvořit řetězec. Wordové nativní pečeti jsou OOXML balíčkové podpisy a nesou pouze certifikát podepisujícího.
Word dokumenty
Pro .docx zdroj, SignRequest.WordOutput volí výstup. Ignoruje se pro PDF zdroje, které vždy vytvářejí PDF.
| Výstup | Co se stane | Podpora ověřovatele |
|---|---|---|
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ů |
Zachovejte PDF, pokud příjemce nepotřebuje editovatelný Word soubor a nepřijímá omezenou podporu ověřovatele.
Nastavení certifikátu
Pro zapečetění vlastní identitou poskytněte pluginu soubor PFX (PKCS#12), který obsahuje soukromý klíč. Pro widget nastavte SignerWidgetOptions.SigningCertificate; pro C# fasádu předávejte certifikát do SignAsync. Poskytněte buď bajty nebo cestu, plus heslo:
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 v chybové zprávě.
Požadavky:
- PFX / PKCS#12 balíček 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. Vypršený 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, o které budete požádá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ě 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. | 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 vypršený, 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.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í pouze 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í
Povolení koncových bodů
Koncové body widgetu ?sign=open|run|download 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 (s vodoznakem) podepisování
});
});AddSignerWidget() bez argumentu povolí widget s výchozími nastaveními. Neposkytuje podepisování samo o sobě: 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= kódem 404. Skript je stále poskytován, takže se widget načte a vykreslí svou oblast pro přetahování, poté při prvním požadavku nahlásí Signing is not enabled on this server..
Vložit
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.
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 či 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 o rozměrech 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 | 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 v pixelech náhledu stránky |
licenseUrl | string | null | null | Přemění upozornění demo-watermark na odkaz na tuto URL |
signatureMode | string | 'certified' | Počáteční typ podpisu: 'certified' nebo 'visual'. Jakákoli jiná hodnota se změní na '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 změní na '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ý podepisovatel
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
});Callbacky
| Callback | Spouští se při | Payload |
|---|---|---|
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í, podepsání 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 nepřeruší tok widgetu.
Imperativní obsluha
| Metoda | Chování |
|---|---|
reset() | Vrátí se na obrazovku upuštění a vymaže aktuální tok. Znovu nespustí onReady. Žádná operace po destroy() |
loadFile(file) | Spustí tok s File. Žádná operace, pokud widget není na své obrazovce upuštění; 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());Štítky
Každý řetězec má výchozí anglickou verzi; labels přepíše libovolnou podmnožinu a zbytek zůstane anglický. Fragmenty, které se mění za běhu, používají {placeholders}, například uploading: 'Uploading {name}…' a pages: '{n} pages'.
| Klíč | Anglický výchozí |
|---|---|
dropPrompt | Drag & drop a PDF or Word file here |
dropHint | PDF or Word (.docx) |
chooseFile | Choose file |
signatureHeading | Your signature |
modeDraw / modeType / modeImage | Draw / Type / Image |
metaSummary | Signature details (optional) |
metaSignerName / metaReason / metaLocation | Signer name / Reason / Location |
signatureType | Signature type |
modeCertified / modeVisual | Digital signature / Visual only |
modeVisualNote | No certificate — a visible mark only, not cryptographically verifiable. |
outputFormat | Output format |
outputPdf / outputWord | PDF / Word (.docx) |
signAction | Sign document |
download | Download |
demoNotice | Demo — signed with the Doconut demo certificate; output is watermarked. |
signingNotEnabled | Signing is not enabled on this server. |
page / pages | 1 page / {n} pages |
Další klíče pokrývají krok umístění, chybovou obrazovku, propojený formulář oznámení demo (demoNoticePrefix, demoNoticeLink, demoNoticeSuffix) a aria-live oznámení.
Když open nebo run odpoví 404 bez JSON chyby, widget zobrazí signingNotEnabled. JSON chyba ze serveru 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, do kterého je připojen, a načte jeho barvy, poloměr a fonty z vlastních CSS vlastností, takže jej můžete tematizovat, aniž byste zasahovali do jeho vnitřností:
#host.dsw {
--dsw-accent: #b0522b; /* odkazy, zaměření, aktivní režim */
--dsw-bg: #fffaf3;
--dsw-fg: #3b2a1a;
--dsw-muted: #8a7a68;
--dsw-border: #e0cbb0;
--dsw-radius: 14px;
--dsw-font: Georgia, "Times New Roman", serif;
--dsw-signature-font: "Segoe Script", "Brush Script MT", cursive; /* režim Type */
}Výchozí: --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 leží pod cestou, kde je UseDoconut() připojen (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, one file) | Nahrajte PDF nebo .docx a otevřete jej pro náhled | 200 — { token, name, pages, ext } |
POST ?sign=run (JSON body) | 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 zahrnuje ú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 od open |
signature.kind | Drawn, Typed nebo Image, nerozlišující 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 rozbalení nesmí být větší než MaxSignatureImageKb |
placement.page | Číslování od jedné |
placement.x / y / w / h | Normalizovaný 0..1 od 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 zkrácen 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í 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 jeho platnost | The signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd. |
open, run | 500 | Zpracování selhalo | Sanitizovaná zpráva |
download | 400 | Token chybí nebo není GUID | pouze stav |
download | 404 | Neznámý nebo vypršený token | pouze stav |
Kompletní cyklus s fetch:
// file: soubor 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 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.NET6.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ěřujte PDF čtečkám. Č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í dependency injection; konstruktor je interní. sourceExtension je ".pdf" nebo ".docx". Při placené licenci je používáno cert a výstup je čistý; při dočasné licenci je používán vestavěný demo certifikát, cert je ignorován 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 a 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á průhlednost, takže neprůhledný JPG zůstane neprůhledný. Kind je pouze 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 založeno na 1; X, Y, W a H jsou normalizované 0..1 od levého horního rohu.
SignatureMode a 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ý 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 při dočasné licenci a vizuální podpisy pouze při placené licenci.
Řešení problémů
| Příznak | Příčina | Řešení |
|---|---|---|
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; nasadíte soubor tam, kde ho 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í PKCS#12 soubor | 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. | Placená licence, Certified mode, 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 odeslalo 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ávání překračuje MaxUploadMb | Zvyšte MaxUploadMb v AddSignerWidget; kontrola maxUploadMb widgetu je jen na klientské straně |
run or download answers 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 podpis v některých prohlížečích | Word výstup obsahuje OOXML balíčkový podpis, který mnoho prohlížečů nezobrazuje | Podepište do PDF, výchozí |
| Čtečky PDF 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 selže, když je UI na jiném původu | Koncové body nemají podporu CORS | Podávejte UI ze stejného původu, 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á?