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:

bash
dotnet add package Doconut.NET6.Signer

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

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

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

bash
apt-get update && apt-get install -y libfontconfig1

Na 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():

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

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

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

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

public sealed class ContractSigning
{
    private readonly DocumentSigner _signer;

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

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

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

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

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

Word zdroj je podepsán do PDF, pokud nepožadujete výstup ve Wordu. Pojmenujte výsledek z result.Extension:

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

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

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

SignAsync vyhodí výjimku místo návratu, když volání nemůže uspět:

VýjimkaZprávaKdy
InvalidOperationExceptionNo signing certificate configured.certifikovaný režim, placená licence a žádný certifikát nebyl předán
InvalidOperationExceptionThe signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd.certifikovaný režim s certifikátem mimo jeho platnost
ArgumentExceptionThe sign request is invalid: the visible signature needs PNG bytes and the placement must be a normalized rectangle on a 1-based page.prázdné PNG bajty nebo umístění, které není platné
NotSupportedExceptionThe signer supports PDF and Word (.docx) documents; got '{extension}'.jakýkoli jiný typ zdroje

Režimy podepisování, výstup Word a certifikáty

Režimy podepisování

SignRequest.Mode určuje, zda je podpis zapečetěn.

RežimCo vytváříCertifikátOvěřitelný
SignatureMode.Certified (výchozí)Viditelný podpis plus digitální pečeťVyžadováno pod placenou licencíAno
SignatureMode.VisualPouze viditelný podpisNikdy nepotřebnýNe: je to obrázek

Použijte Certified, když musí být podpis prokazatelný: schválení, smlouvy, cokoliv, co ověřovatel potřebuje zkontrolovat pro identitu a integritu. Použijte Visual, když potřebujete jen vzhled podpisu, nebo nemáte certifikát. Dočasná licence přidá vodoznak k oběma.

PDF peč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ýstupCo se stanePodpora 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.DocxDokument zůstane ve Wordu: do něj se vloží obrázek podpisu a také podpis OOXML balíčkuOmezená: 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:

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

Certifikát je uchováván pouze v paměti. Nikdy 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:

bash
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ávaOprava
Doconut Signer: the certificate file was not found at '{path}'.Opravte PfxPath; ujistěte se, že soubor je nasazen a čitelný účtem aplikace
Doconut Signer: the signing certificate could not be opened — the password is incorrect or the file is not a valid .pfx.Zkontrolujte heslo; ujistěte se, že soubor je skutečný .pfx, ne .cer ani .pem
Doconut Signer: the signing certificate has no private key. Re-export the .pfx INCLUDING the private key.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:

text
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ů:

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

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

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

Poslední řádek je stejný u všech licencí. U placené licence se demo certifikát nikdy nepoužívá: bez certifikátu fungují 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:

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
    options.AddSignerWidget(widget =>
    {
        widget.MaxUploadMb = 25;           // výchozí
        widget.MaxSignatureImageKb = 512;  // výchozí
        // widget.SigningCertificate: viz nastavení certifikátu; 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í:

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

Bez AddSignerWidget() 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í:

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

Doconut.signer(selectorOrElement, options) přijímá CSS selektor nebo element, vyhodí chybu, pokud není místo 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žnostTypVýchozíPoznámky
basePathstring'/doconut'Kde jsou poskytovány koncové body ?sign= a náhledové obrázky
resPathstring'/doconut-res'Rezervováno; widget obsahuje vlastní CSS
maxUploadMbnumber25Pouze kontrola na straně klienta, takže příliš velký soubor selže rychle. Limit na serveru je MaxUploadMb v AddSignerWidget
maxSignatureKbnumber512Limit na straně klienta pro režim Image. Udržujte ho stejný jako serverový MaxSignatureImageKb
previewWidthnumber560Šířka v pixelech náhledu stránky
licenseUrlstring | nullnullPřemění upozornění demo-watermark na odkaz na tuto URL
signatureModestring'certified'Počáteční typ podpisu: 'certified' nebo 'visual'. Jakákoli jiná hodnota se změní na 'certified'
showSignatureModeTogglebooleantrueZobrazuje volbu Digital signature / Visual only. S false widget podepisuje pomocí signatureMode
wordOutputstring'pdf'Počáteční výstup pro zdroje .docx: 'pdf' nebo 'docx'. Jakákoli jiná hodnota se změní na 'pdf'
showOutputFormatTogglebooleantrueZobrazuje volbu PDF / Word, pouze pro zdroje .docx. S false widget používá wordOutput
labelsobject{}Přepíše libovolnou podmnožinu anglických řetězců

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

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

Callbacky

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

MetodaChová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
javascript
const signerWidget = Doconut.signer('#host', {
  basePath: '/doconut',
  onSigned: (result) => console.log('signed', result.downloadName, result.watermarked),
  onError: (error) => console.warn(error.message)
});
document.getElementById('start-over').addEventListener('click', () => signerWidget.reset());

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

Další klíče pokrývají krok umístění, chybovou obrazovku, propojený formulář oznámení demo (demoNoticePrefix, demoNoticeLink, demoNoticeSuffix) a aria-live oznámení.

Když open nebo run odpoví 404 bez JSON chyby, widget zobrazí signingNotEnabled. JSON chyba ze serveru 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í:

css
#host.dsw {
  --dsw-accent: #b0522b;       /* odkazy, zaměření, aktivní režim */
  --dsw-bg: #fffaf3;
  --dsw-fg: #3b2a1a;
  --dsw-muted: #8a7a68;
  --dsw-border: #e0cbb0;
  --dsw-radius: 14px;
  --dsw-font: Georgia, "Times New Roman", serif;
  --dsw-signature-font: "Segoe Script", "Brush Script MT", cursive;   /* režim Type */
}

Výchozí: --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áhled200 — { token, name, pages, ext }
POST ?sign=run (JSON body)Podepište nahraný soubor200 — { downloadToken, downloadName, watermarked }
GET ?sign=download&token=<downloadToken>Streamujte podepsaný soubor200 — soubor, Content-Disposition: attachment, Cache-Control: no-store

ext v odpovědi open zahrnuje úvodní tečku (".docx"). Náhled stránky používá standardní cestu k obrázku prohlížeče, {basePath}?token={token}&page={n}&thumb=1&width={px}; zobrazená stránka se stane placement.page.

Tělo run:

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

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

Kompletní cyklus s fetch:

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

  1. Nainstalujte plugin vedle hlavního balíčku, ve stejné verzi: dotnet add package Doconut.NET6.Signer.

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

  3. Získejte svůj certifikát jako PFX s jeho soukromým klíčem a řetězcem vydavatele, od certifikační autority nebo vlastní PKI vaší organizace. Pro první vyzkoušení použijte demo licenci (vestavěný demo certifikát, vodoznak) nebo samopodepsaný PFX.

  4. Čtěte certifikát z konfigurace, aby jeho změna nikdy nevyžadovala úpravu kódu:

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

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

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

Důvěř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():

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

builder.Services.AddDoconutDistributedWidgets(store =>
{
    store.RootPath = @"\\fileshare\doconut";   // složka, kterou může každý uzel číst i zapisovat
    store.FarmKey = farmKey;                   // alespoň 32 bajtů, identické na každém uzlu
    // store.Ttl = TimeSpan.FromMinutes(30);   // jak dlouho je nahrání uchováno (výchozí)
});
  • Jeden server nepotřebuje nic: bez tohoto volání se používá úložiště v paměti.
  • Nahrané soubory a výsledky jsou šifrovány v klidu na sdíleném úložišti (AES-256, encrypt-then-MAC) a každý soubor je svázán se svým tokenem, takže jeden token nikdy nemůže přečíst soubor jiného.
  • FarmKey musí mít alespoň 32 bajtů a být stejný na každém uzlu. Načtěte jej z tajného úložiště; nikdy jej nezakódujte přímo. Registrace vyhodí ArgumentException, když RootPath chybí nebo je FarmKey kratší než 32 bajtů.
  • Nastavte RootPath na stejné sdílené umístění, které používá distribuovaný prohlížeč, a dejte každému uzlu stejný podpisový certifikát.

Referenční API

Fasáda a možnosti widgetu jsou v jmenném prostoru Doconut; typy požadavků a výsledků jsou v Doconut.Core.Models.Signing. SignerPlugin je v Doconut.Plugins.Signer.

DocumentSigner

csharp
public sealed class DocumentSigner
{
    public Task<SignResult> SignAsync(
        Stream source, string sourceExtension, SignRequest request,
        SigningCertificate? cert = null, CancellationToken ct = default);
}

Získáno pomocí 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

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

Jedna viditelná podpis umístěná jednou, plus volitelné metadata podepisujícího.

VisibleSignature a SignatureKind

csharp
public sealed record VisibleSignature(SignatureKind Kind, byte[] PngBytes)
{
    public bool IsValid { get; }   // PngBytes není prázdný
}

public enum SignatureKind { Drawn, Typed, Image }

PngBytes je PNG pro každý typ. Nakreslený nebo napsaný podpis je průhledný; nahraný obrázek si zachová průhlednost, takže neprůhledný JPG zůstane neprůhledný. Kind je pouze nápověda.

SignaturePlacement

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

Page je založeno na 1; X, Y, W a H jsou normalizované 0..1 od levého horního rohu.

SignatureMode a WordOutput

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

SignResult

csharp
public sealed record SignResult(Stream Stream, string Extension);

Podepsaný dokument jako vyhledávatelný stream a jeho přípona s tečkou (".pdf" nebo ".docx").

SigningCertificate

csharp
public sealed class SigningCertificate
{
    public byte[]? PfxBytes { get; init; }
    public string? PfxPath  { get; init; }
    public string  Password { get; init; } = "";
    public bool    HasMaterial { get; }   // PfxBytes není prázdný, nebo PfxPath není prázdný
}

Nastavte buď PfxBytes nebo PfxPath, plus Password.

SignerWidgetOptions

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

Nastavte přes DoconutOptions.AddSignerWidget(Action<SignerWidgetOptions>? configure = null), který vrací DoconutOptions, takže volání lze řetězit. Null SigningCertificate znamená demo certifikát při dočasné licenci a vizuální podpisy pouze při placené licenci.

Řešení problémů

PříznakPříč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é oknoNainstalujte licenci, která poskytuje Signer, nebo odstraňte AddPlugin<SignerPlugin>()
AddDoconut() throws AddSignerWidget() was called but the Signer plugin is not registered.Widget je povolen bez svého pluginuPřidejte options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>()
AddDoconut() throws Doconut Signer: the certificate file was not found at '{path}'.PfxPath ukazuje na chybějící souborOpravte cestu; 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 souborZkontrolujte heslo; použijte skutečný .pfx
AddDoconut() throws Doconut Signer: the signing certificate has no private key. Re-export the .pfx INCLUDING the private key.PFX byl exportován bez soukromého klíčeExportujte jej znovu se soukromým klíčem
Resolving DocumentSigner throws No IDocumentSigner is registered.SignerPlugin není registrovánPřidejte AddPlugin<SignerPlugin>() uvnitř AddDoconut()
Výstup je vodoznakemLicence je dočasná (Demo/NFR)Použijte placenou licenci, která poskytuje Signer
run answers 400 No signing certificate configured.Placená licence, Certified mode, a žádný certifikátNakonfigurujte SigningCertificate, nebo podepište ve vizuálním režimu
run answers 400 The signing certificate expired on yyyy-MM-dd.Certifikát je neplatnýVyměňte jej; vizuální podpisy mezitím fungují
Log uvádí, že výstup „používá vestavěný demo certifikát“, přesto placená licence odmítá certifikované podpisyTento řádek je zapsán vždy, když není nastaven žádný certifikát, bez ohledu na licenciNakonfigurujte SigningCertificate
Widget se načte, ale říká Signing is not enabled on this server.AddSignerWidget() nebyl zavolán, nebo basePath neodpovídá místu, kde je UseDoconut() namontovánZavolejte AddSignerWidget(); opravte basePath
run answers 400 The signature image must be a PNG., Signature image is not valid base64. or Signature image is too large.Vlastní UI odeslalo URL data:, JPG, nebo více než MaxSignatureImageKbPošlete čistý base64 PNG v rámci limitu
open answers 413 File is too large.Nahrávání překračuje MaxUploadMbZvyš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ý souborOtevřete soubor znovu; ve farmě zaregistrujte AddDoconutDistributedWidgets
Podepsaný .docx neukazuje podpis v některých prohlížečíchWord výstup obsahuje OOXML balíčkový podpis, který mnoho prohlížečů nezobrazujePodepiš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íhoPoužijte certifikát z kořene, kterému vaše čtečky důvěřují
Widget selže, když je UI na jiném původuKoncové body nemají podporu CORSPodávejte UI ze stejného původu, nebo použijte reverse-proxy pro cesty Doconut
Motiv se neaplikujeSelektor cílí na prvek uvnitř mountuCílovat samotný mount: #host.dsw nebo #host

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