Wtyczka Signer
Podpisz dokumenty PDF i Word widoczną sygnaturą oraz cyfrową pieczęcią
Wtyczka Signer umieszcza widoczną sygnaturę w dokumencie i domyślnie zabezpiecza go cyfrowym podpisem, który może zweryfikować czytnik PDF. Podpisuje pliki PDF i Word (.docx). Widoczna sygnatura jest zawsze obrazem PNG: narysowanym, wpisanym lub przesłanym przez podpisującego.
| Powierzchnia | Kiedy używać |
|---|---|
DocumentSigner (C#) | Podpisujesz na serwerze, bez udziału przeglądarki |
Drop-in widget (doconutSigner.js) | Chcesz gotowy ekran przesyłania, podpisywania i pobierania na swojej stronie |
HTTP endpoints (?sign=open|run|download) | Budujesz własny interfejs podpisywania w oparciu o udokumentowany kontrakt serwera |
Każdy podpis jest umieszczany raz, na jednej stronie. Imię i nazwisko podpisującego, powód oraz lokalizacja mogą być z nim powiązane.
Instalacja pakietu
Zainstaluj najnowszą stabilną wtyczkę Signer:
dotnet add package Doconut.NET6.SignerAby przypiąć wtyczkę do wersji opisanej w tej dokumentacji, przekaż wersję osobno:
dotnet add package Doconut.NET6.Signer --version 26.10.0Utrzymuj pakiet Signer w tej samej wersji co Doconut.NET6. Identyfikator pakietu to Doconut.NET6.Signer; .<version> pojawia się tylko w pobranej nazwie pliku .nupkg.
Plik licencji wtyczki, Doconut.Viewer.Signer.lic, znajduje się w tym samym folderze co Doconut.Viewer.lic; jest odczytywany razem z licencją przeglądarki.
Platformy. Wtyczka działa wszędzie tam, gdzie działa Doconut.NET6: Windows oraz Linux oparty na glibc na architekturze x64 (nie Alpine ani inne dystrybucje oparte na musl). Na Linuxie zainstaluj bibliotekę konfiguracyjną czcionek przed otwarciem pierwszego dokumentu:
apt-get update && apt-get install -y libfontconfig1Na RHEL, Fedorze i podobnych dystrybucjach pakiet to fontconfig. Bez niego otwieranie dokumentu kończy się niepowodzeniem z The system library libfontconfig1 is missing. Install it (Debian/Ubuntu: apt-get install -y libfontconfig1) and see the Linux section of the Doconut documentation.
Rejestracja wtyczki
Podobnie jak każda wtyczka Doconut, Signer rejestruje się w AddPlugin<TPlugin>() wewnątrz AddDoconut():
builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
});To wszystko, czego potrzebuje warstwa C#. Widżet i jego endpointy HTTP są oddzielnym elementem opcjonalnym, AddSignerWidget() (zobacz Widżet wbudowany).
Wtyczka wymaga licencji, która przyznaje możliwość Signer. Bez niej, AddDoconut() zgłasza wyjątek przy uruchamianiu, zanim aplikacja obsłuży żądanie:
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.Zgłasza wyjątek przy braku licencji, starszym pliku TRIAL, licencji bez Signer oraz płatnej licencji użytej poza jej oknem wersji. Tymczasowe licencje Demo/NFR są akceptowane. Zobacz Konfiguracja licencji, aby dowiedzieć się, jak ładowane są licencje.
Licencjonowanie i znak wodny
| Stan licencji | Uruchomienie | Certyfikowany podpis | Wizualny podpis |
|---|---|---|---|
Płatna licencja przyznająca Signer, certyfikat skonfigurowany | Uruchamia się | Zapieczętowany twoim certyfikatem, czysty (watermarked: false) | Czysty |
Płatna licencja przyznająca Signer, brak certyfikatu | Uruchamia się | Odrzucony: No signing certificate configured. | Czysty |
| Płatna licencja, certyfikat wygasły lub jeszcze nieważny | Uruchamia się (z włączonym widżetem, logowane jest Ostrzeżenie) | Odrzucony: The signing certificate expired on yyyy-MM-dd. | Czysty |
| Tymczasowa licencja Demo/NFR, aktywna lub wygasła | Uruchamia się | Zapieczętowany wbudowanym certyfikatem demo, znakowany (watermarked: true) | Znakowany |
Brak licencji, starszy plik TRIAL, licencja bez Signer, lub płatna licencja poza oknem wersji | AddDoconut() zgłasza wyjątek | — | — |
Zasada jest taka sama dla warstwy C# i widżetu: wyjście jest znakowane, gdy licencja nie jest płatną licencją przeglądarki lub jest tymczasowa. Podczas tymczasowej licencji wtyczka zawsze podpisuje się wbudowanym certyfikatem demo, a każdy skonfigurowany przez Ciebie certyfikat nie jest używany.
Certyfikat demo tworzy prawdziwą pieczęć, ale czytniki PDF go nie ufają. Integrację można zbudować i przetestować od początku do końca na licencji ewaluacyjnej; aby uzyskać czyste, zaufane wyjście, potrzebujesz zarówno płatnej licencji, jak i własnego certyfikatu podpisu.
Użycie z C#
DocumentSigner jest rejestrowany przez AddDoconut() i rozwiązywany z wstrzykiwania zależności. Jego konstruktor jest wewnętrzny, więc nigdy nie new go. Rozwiązywanie go bez AddPlugin<SignerPlugin>() powoduje rzucenie 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");
// Tryb domyślnie ustawiony na Certified (widoczny podpis + cyfrowa pieczęć); WordOutput domyślnie ustawiony na 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 przyjmuje strumień źródłowy, jego rozszerzenie (".pdf" lub ".docx"), żądanie oraz certyfikat dla tego wywołania. Fasada nie odczytuje SignerWidgetOptions.SigningCertificate; to ustawienie jest przeznaczone dla widżetu. Przekaż null w ramach licencji demonstracyjnej lub w trybie Visual.
SignResult przechowuje podpisany dokument jako strumień z możliwością przewijania, plus jego Extension (".pdf" lub ".docx"), abyś mógł nazwać plik. Strumień jest Twoją własnością: zwolnij go, gdy skończysz.
Podpis Visual nakłada tylko obraz i nie wymaga certyfikatu:
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);Źródło Word jest podpisywane do PDF, chyba że poprosisz o wyjście w formacie Word. Nazwij wynik 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 rzuca wyjątek zamiast zwracać, gdy wywołanie nie może się powieść:
| Wyjątek | Komunikat | Kiedy |
|---|---|---|
InvalidOperationException | No signing certificate configured. | Tryb Certified, płatna licencja i brak przekazanego certyfikatu |
InvalidOperationException | The signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd. | Tryb Certified z certyfikatem poza okresem ważności |
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. | Puste bajty PNG lub nieprawidłowe umiejscowienie |
NotSupportedException | The signer supports PDF and Word (.docx) documents; got '{extension}'. | Dowolny inny typ źródła |
Tryby podpisywania, wyjście Word i certyfikaty
Tryby podpisywania
SignRequest.Mode wybiera, czy podpis jest uszczelniony.
| Tryb | Co produkuje | Certyfikat | Weryfikowalny |
|---|---|---|---|
SignatureMode.Certified (domyślnie) | Widoczny podpis plus cyfrowy znak | Wymagany przy płatnej licencji | Tak |
SignatureMode.Visual | Tylko widoczny podpis | Nigdy nie potrzebny | Nie: to jest obraz |
Używaj Certified, gdy podpis musi być weryfikowalny: zatwierdzenia, umowy, wszystko, co weryfikator musi sprawdzić pod kątem tożsamości i integralności. Używaj Visual, gdy potrzebny jest jedynie wygląd podpisu lub nie masz certyfikatu. Tymczasowa licencja dodaje znak wodny do obu.
Pieczęcie PDF są odłączonymi podpisami PKCS#7 (adbe.pkcs7.detached) z SHA-256, dla kluczy RSA lub ECDSA. Zawierają certyfikaty wystawcy znalezione w Twoim pliku PFX, więc czytnik, który ufa Twojemu głównemu certyfikatowi, może zbudować łańcuch. Pieczęcie natywne dla Word to podpisy pakietu OOXML i zawierają tylko certyfikat podpisującego.
Dokumenty Word
Dla źródła .docx, SignRequest.WordOutput wybiera wyjście. Jest ignorowane dla źródeł PDF, które zawsze generują PDF.
| Wyjście | Co się dzieje | Obsługa weryfikatora |
|---|---|---|
WordOutput.Pdf (domyślnie) | Dokument jest konwertowany do PDF, następnie podpisywany i uszczelniany | Szeroka: podpisany PDF weryfikuje się wszędzie |
WordOutput.Docx | Dokument pozostaje w formacie Word: obraz podpisu jest w nim umieszczany, plus podpis pakietu OOXML | Ograniczona: nie każdy przeglądarka wyświetla podpisy pakietu OOXML |
Zachowaj PDF, chyba że odbiorca potrzebuje edytowalnego pliku Word i akceptuje ograniczoną obsługę weryfikatora.
Konfiguracja certyfikatu
Aby uszczelnić własną tożsamością, podaj wtyczce plik PFX (PKCS#12) zawierający klucz prywatny. Dla widżetu ustaw SignerWidgetOptions.SigningCertificate; dla fasady C# przekaż certyfikat do SignAsync. Dostarcz albo bajty, albo ścieżkę, plus hasło:
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"],
};
});
});Certyfikat jest przechowywany wyłącznie w pamięci. Nigdy nie jest logowany, zwracany klientowi ani zapisywany, a hasło nigdy nie pojawia się w linii logu ani w komunikacie o błędzie.
Wymagania:
- Pakiet PFX / PKCS#12 z kluczem prywatnym. Plik zawierający tylko klucz publiczny (
.cer,.crt) nie może podpisywać. Wyeksportuj łańcuch wystawcy razem z nim, aby pieczęcie PDF mogły go zawierać. - Poprawne hasło.
- W jego oknie ważności. Wygasły lub jeszcze nieważny certyfikat nie zatrzymuje aplikacji: jest logowany jako Ostrzeżenie przy uruchomieniu, a podpisy Certyfikowane są odrzucane, dopóki nie zostanie zastąpiony. Podpisy wizualne pozostają niezmienione.
- Wydany do podpisywania dokumentów: użycie klucza z digital signature lub non-repudiation, oraz rozszerzone użycie klucza, jeśli istnieje, które zezwala na podpisywanie dokumentów, ochronę e‑mail lub uwierzytelnianie klienta. Certyfikat wydany do innego celu, np. certyfikat serwera TLS, nadal może podpisywać, ale jest logowany jako Ostrzeżenie i czytniki PDF oznaczają podpis.
- Tokeny sprzętowe, karty inteligentne, HSM oraz magazyn certyfikatów Windows nie są obsługiwane. Wyeksportuj certyfikat wraz z kluczem prywatnym i łańcuchem do pliku PFX.
Utwórz PFX z certyfikatu i jego klucza prywatnego przy użyciu OpenSSL:
openssl pkcs12 -export -out signing.pfx -inkey private.key -in certificate.crt
# Hasło eksportu, o które jesteś pytany, to SigningCertificate.Password.Wyeksportuj jeden z magazynu certyfikatów Windows: otwórz certmgr.msc i znajdź certyfikat (jego ikona pokazuje klucz, gdy klucz prywatny jest dostępny). Kliknij prawym przyciskiem, wybierz All Tasks → Export…, zaznacz Yes, export the private key, wybierz Personal Information Exchange – PKCS #12 (.PFX) i ustaw hasło.
Kontrole przy uruchomieniu
Gdy widżet jest włączony, certyfikat w SignerWidgetOptions.SigningCertificate jest sprawdzany raz, wewnątrz AddDoconut(), więc niepoprawnie skonfigurowany PFX powoduje błąd przy uruchomieniu, a nie przy pierwszym podpisie. Trzy problemy generują InvalidOperationException:
| Komunikat | Rozwiązanie |
|---|---|
Doconut Signer: the certificate file was not found at '{path}'. | Popraw PfxPath; upewnij się, że plik jest wdrożony i czytelny dla konta aplikacji |
Doconut Signer: the signing certificate could not be opened — the password is incorrect or the file is not a valid .pfx. | Sprawdź hasło; upewnij się, że plik jest prawdziwym .pfx, a nie .cer lub .pem |
Doconut Signer: the signing certificate has no private key. Re-export the .pfx INCLUDING the private key. | Wyeksportuj ponownie PFX z kluczem prywatnym |
W przeciwnym razie host zapisuje jedną linię w logu przy uruchomieniu. Informacja, gdy certyfikat jest gotowy:
Doconut Signer: using certificate '{subject}' (valid until yyyy-MM-dd). Signatures are digitally sealed.Ostrzeżenie, gdy jest wygasły, jeszcze nieważny lub nie wydany do podpisywania dokumentów:
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.I informacja, gdy żaden certyfikat nie jest skonfigurowany:
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.Ta ostatnia linia jest taka sama we wszystkich licencjach. W płatnej licencji certyfikat demonstracyjny nigdy nie jest używany: bez certyfikatu działają tylko podpisy wizualne.
Fasada C# nie jest sprawdzana przy uruchomieniu. Certyfikat, który przekazujesz do SignAsync, jest odczytywany podczas podpisywania, więc nieprawidłowa ścieżka lub hasło powodują błąd tego wywołania.
Widżet Drop-in
Włącz punkty końcowe
Punkty końcowe ?sign=open|run|download widżetu są wyłączone domyślnie. Włącz je obok rejestracji wtyczki:
builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
options.AddSignerWidget(widget =>
{
widget.MaxUploadMb = 25; // wartość domyślna
widget.MaxSignatureImageKb = 512; // wartość domyślna
// widget.SigningCertificate: zobacz konfigurację certyfikatu; pozostaw null dla demo (z znakiem wodnym) podpisu
});
});AddSignerWidget() bez argumentu włącza widżet z ustawieniami domyślnymi. Nie przyznaje samodzielnie możliwości podpisywania: wymaga AddPlugin<SignerPlugin>(), albo AddDoconut() zgłasza wyjątek:
AddSignerWidget() was called but the Signer plugin is not registered. Add options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>() (the widget needs it), or remove the AddSignerWidget() call.Bez AddSignerWidget(), każde żądanie ?sign= zwraca 404. Sam skrypt jest nadal serwowany, więc widżet ładuje się i rysuje swoją strefę upuszczania, a następnie zgłasza Signing is not enabled on this server. przy pierwszym żądaniu.
Osadź go
UseDoconutResources() udostępnia skrypt pod adresem {ResourcesPath}/js/doconutSigner.js (domyślnie /doconut-res/js/doconutSigner.js). To pojedynczy, samodzielny plik bez zależności:
<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) przyjmuje selektor CSS lub element, zgłasza wyjątek, jeśli miejsce montażu nie zostanie znalezione, i zwraca uchwyt.
Podpisujący przesyła plik PDF lub .docx, tworzy podpis (Rysuj na płótnie, Wpisz imię w czcionce podpisu, lub Obraz z PNG, JPG lub GIF), przeciąga i zmienia jego rozmiar na stronie, a następnie podpisuje i pobiera wynik. Widżet zawsze wysyła podpis jako PNG; przesłany obraz jest konwertowany w przeglądarce na PNG o wymiarach 520×160.
Opcje
| Opcja | Typ | Domyślnie | Uwagi |
|---|---|---|---|
basePath | string | '/doconut' | Gdzie serwowane są punkty końcowe ?sign= i obrazy podglądu |
resPath | string | '/doconut-res' | Zarezerwowane; widżet zawiera własny CSS |
maxUploadMb | number | 25 | Sprawdzanie tylko po stronie klienta, więc zbyt duży plik od razu zostaje odrzucony. Limit serwera wynosi MaxUploadMb w AddSignerWidget |
maxSignatureKb | number | 512 | Limit po stronie klienta dla trybu Obraz. Utrzymuj go równym limitowi serwera MaxSignatureImageKb |
previewWidth | number | 560 | Szerokość w pikselach podglądu strony |
licenseUrl | string | null | null | Zamienia powiadomienie demo-watermark w link do tego URL |
signatureMode | string | 'certified' | Początkowy typ podpisu: 'certified' lub 'visual'. Każda inna wartość staje się 'certified' |
showSignatureModeToggle | boolean | true | Wyświetla wybór Podpis cyfrowy / Tylko wizualny. Z false, widżet podpisuje się przy użyciu signatureMode |
wordOutput | string | 'pdf' | Początkowy format wyjścia dla źródeł .docx: 'pdf' lub 'docx'. Każda inna wartość staje się 'pdf' |
showOutputFormatToggle | boolean | true | Wyświetla wybór PDF / Word, tylko dla źródeł .docx. Z false, widżet używa wordOutput |
labels | object | {} | Zastępuje dowolny podzbiór angielskich ciągów |
Ukrycie przełącznika nie wyłącza funkcji; ustawia wartość na stałą. Dwie typowe konfiguracje:
// Oba przełączniki wyświetlone, podpis cyfrowy domyślnie: pełny podpisujący samoobsługowy
Doconut.signer('#host', { basePath: '/doconut', licenseUrl: '/pricing' });// Tylko wizualnie, bez przełącznika: prosty stempel bez oferowanego podpisu cyfrowego
Doconut.signer('#host', {
basePath: '/doconut',
signatureMode: 'visual',
showSignatureModeToggle: false
});Wywołania zwrotne
| Wywołanie zwrotne | Wywoływane gdy | Dane |
|---|---|---|
onReady | Raz, przy montażu (nie ponownie przy reset()) | — |
onSourceLoaded | Plik jest otwierany i wyświetlany jest jego podgląd | { file: { token, name, pages, ext } } |
onSigned | Podpisanie powiodło się | { downloadToken, downloadName, watermarked } |
onDownload | Przy każdym kliknięciu Pobierz | { downloadName, downloadToken } |
onError | Krok otwarcia, podpisu lub pobrania nie powiódł się, lub plik w trybie Obraz jest za duży | { message } |
Wywołanie zwrotne, które zgłasza wyjątek, jest przechwytywane i logowane; nigdy nie przerywa działania widżetu.
Obsługa imperatywna
| Metoda | Zachowanie |
|---|---|
reset() | Powraca do ekranu upuszczania i czyści bieżący przepływ. Nie wywołuje ponownie onReady. Brak działania po destroy() |
loadFile(file) | Rozpoczyna przepływ z File. Brak działania, chyba że widżet znajduje się na ekranie upuszczania; w razie potrzeby najpierw wywołaj reset() |
destroy() | Usuwa nasłuchiwacze, opróżnia montaż i zamraża instancję |
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());Etykiety
Każdy ciąg ma domyślnie angielską wersję; labels nadpisuje dowolny podzbiór, a pozostałe pozostają po angielsku. Fragmenty, które zmieniają się w czasie działania, używają {placeholders}, takie jak uploading: 'Uploading {name}…' i pages: '{n} pages'.
| Klucz | Domyślny angielski |
|---|---|
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 |
Dalsze klucze obejmują krok umiejscowienia, ekran błędu, powiązaną formę powiadomienia demo (demoNoticePrefix, demoNoticeLink, demoNoticeSuffix) oraz ogłoszenia aria-live.
Gdy open lub run odpowiada 404 bez błędu JSON, widżet wyświetla signingNotEnabled. Błąd JSON z serwera zawsze ma pierwszeństwo, więc komunikaty takie jak wygasłe przesłanie pozostają widoczne.
Motywy
Widżet dodaje klasę dsw do swojego elementu montującego i odczytuje jego kolory, promień i czcionki z własności CSS, dzięki czemu możesz zmienić motyw bez modyfikowania jego wewnętrznych elementów:
#host.dsw {
--dsw-accent: #b0522b; /* linki, skupienie, tryb aktywny */
--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; /* tryb Type */
}Domyślne: --dsw-accent: #2b6cb0, --dsw-bg: #ffffff, --dsw-fg: #1a202c, --dsw-muted: #718096, --dsw-border: #cbd5e0, --dsw-radius: 8px, systemowa czcionka UI oraz kursywna czcionka podpisu.
Zbuduj własny frontend
Widżet jest klientem tego kontraktu HTTP. Wszystkie trzy trasy znajdują się pod ścieżką, w której zamontowano UseDoconut() (zwykle /doconut), i odpowiadają 404 aż do wywołania AddSignerWidget(). Błędy zawierają ciało JSON, { "error": "..." }, z wyjątkiem przypadków, gdy tabela podaje „tylko status”. Nieznana wartość ?sign= odpowiada 400.
| Trasa | Cel | Odpowiedź sukcesu |
|---|---|---|
POST ?sign=open (multipart, jeden plik) | Prześlij PDF lub .docx i otwórz go w podglądzie | 200 — { token, name, pages, ext } |
POST ?sign=run (ciało JSON) | Podpisz przesłany plik | 200 — { downloadToken, downloadName, watermarked } |
GET ?sign=download&token=<downloadToken> | Strumieniuj podpisany plik | 200 — plik, Content-Disposition: attachment, Cache-Control: no-store |
ext w odpowiedzi open zawiera wiodącą kropkę (".docx"). Podgląd strony używa standardowej trasy obrazu przeglądarki, {basePath}?token={token}&page={n}&thumb=1&width={px}; wyświetlana strona staje się placement.page.
Ciało 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 | Uwagi |
|---|---|
token | Token z open |
signature.kind | Drawn, Typed lub Image, bez rozróżniania wielkości liter; wszystko inne staje się Drawn. Tylko podpowiedź: ładunek zawsze jest PNG |
signature.payload | Czysty base64 PNG, bez prefiksu data:. Musi być prawdziwym PNG i po dekodowaniu nie większy niż MaxSignatureImageKb |
placement.page | Liczony od 1 |
placement.x / y / w / h | Znormalizowany 0..1 od lewego górnego rogu, z x + w ≤ 1 i y + h ≤ 1 |
meta.signerName / reason / location | Opcjonalne. Każdy jest przycinany, pusta wartość jest pomijana, a każdy jest obcinany do 256 znaków |
wordOutput | pdf (domyślnie) lub docx; ignorowane dla źródeł PDF. Wszystko inne staje się pdf |
mode | certified (domyślnie) lub visual. Wszystko inne staje się certified |
downloadName następuje po wyjściu: <source>-signed.pdf lub <source>-signed.docx, a download wysyła pasujący Content-Type.
Przesłane źródło i podpisany wynik są przechowywane przez 30 minut. Po tym czasie run i download odpowiadają 404 i plik musi zostać ponownie otwarty. Wszystkie tokeny są GUID-ami.
| Trasa | Status | Kiedy | Ciało |
|---|---|---|---|
| dowolna | 404 | Widżet nie jest włączony | tylko status |
| dowolna | 405 | Nieprawidłowy czasownik (open i run wymagają POST, download wymaga GET) | tylko status |
open | 400 | Nie jest przesyłaniem multipart | Expected a multipart file upload. |
open | 400 | Brak pliku lub pusty plik | No file uploaded. |
open | 400 | Wszystko inne niż .pdf lub .docx | Signing supports PDF and Word (.docx) files only. |
open | 413 | Przesył przekracza MaxUploadMb | File is too large. |
run | 400 | Ciało nie jest prawidłowym JSON-em lub jest puste | Malformed request. / Empty request. |
run | 400 | Token jest brakujący lub nie jest GUID-em | Invalid token. |
run | 404 | Przesył wygasł lub nigdy nie został otwarty | Upload expired — please re-open the file. |
run | 400 | Brak podpisu lub brak umiejscowienia | No signature supplied. / No placement supplied. |
run | 400 | Ładunek nie jest base64, jest pusty, za duży lub nie jest 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 | Umiejscowienie jest poza stroną | The signature or its placement is invalid. |
run | 400 | Tryb certyfikowany, płatna licencja i brak certyfikatu | No signing certificate configured. |
run | 400 | Tryb certyfikowany z certyfikatem poza okresem ważności | The signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd. |
open, run | 500 | Przetwarzanie nie powiodło się | Zsanityzowana wiadomość |
download | 400 | Token jest brakujący lub nie jest GUID-em | tylko status |
download | 404 | Nieznany lub wygasły token | tylko status |
Pełny cykl z fetch:
// file: plik do podpisania; pngBase64: podpis jako czysty base64 PNG, bez prefiksu data:
// na przykład canvas.toDataURL('image/png').split(',')[1].
async function signFile(file, pngBase64) {
const base = '/doconut';
// 1. open: prześlij plik
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: podpisz go
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: pobierz podpisany plik
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);
}Punkty końcowe są same-origin: ta wersja nie obsługuje CORS. Udostępnij swój interfejs UI i skrypt widgetu z tego samego pochodzenia co Doconut, lub odwrócone proxy oba /doconut ścieżki (ścieżkę warstwy pośredniej i ścieżkę zasobów) pod pochodzeniem Twojego UI.
W produkcji
-
Zainstaluj wtyczkę obok pakietu podstawowego, w tej samej wersji:
dotnet add package Doconut.NET6.Signer. -
Dodaj plik licencji. Umieść
Doconut.Viewer.Signer.licw tym samym folderze coDoconut.Viewer.lic. -
Uzyskaj swój certyfikat w formacie PFX wraz z kluczem prywatnym i łańcuchem wystawcy, od urzędu certyfikacji lub własnej PKI organizacji. Aby najpierw przetestować, użyj licencji demonstracyjnej (wbudowanego certyfikatu demo, z znakiem wodnym) lub samopodpisanego PFX.
-
Odczytaj certyfikat z konfiguracji, aby zmiana nie wymagała modyfikacji kodu:
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"] ?? "", }); });Trzymaj
.pfxpozawwwrooti zachowaj hasło pozaappsettings.json: sekrety użytkownika w środowisku deweloperskim (dotnet user-secrets set "DoconutSigner:Password" "<password>"), zmienną środowiskową (DoconutSigner__Password) lub skarbcem w produkcji. -
Sprawdź log uruchomienia. Powinien zawierać
using certificate '{subject}' (valid until …). Signatures are digitally sealed.. Ostrzeżenie zamiast tego oznacza, że certyfikat jest wygasły, jeszcze nieważny lub nie został wydany do podpisywania dokumentów.
Zaufanie w czytnikach PDF. Czytnik wyświetla podpis jako ważny, gdy ufa korzeniowi certyfikatu. W przypadku PKI Twojej organizacji obowiązuje to na każdym komputerze, który ufa Twojemu korzeniowi, co zazwyczaj oznacza wszystkie maszyny w organizacji. Certyfikaty, którym Adobe ufa na dowolnym komputerze (Adobe Approved Trust List), są – o ile wiemy – wydawane z kluczem prywatnym na tokenie sprzętowym lub HSM, czego ta wtyczka nie może używać: podpisuje wyłącznie z PFX. Potwierdź to u dostawcy certyfikatu, zanim będziesz polegać na takim zaufaniu.
Farmy sieciowe
Widget przechowuje każde przesłanie i jego wynik w pamięci na węźle, który obsłużył open. Za load balancerem bez sesji przyklejonych, późniejsze żądanie run, download lub podglądu może trafić na inny węzeł i nie znaleźć przesłanego pliku. Zarejestruj współdzielony, zaszyfrowany magazyn widgetu raz, po AddDoconut():
byte[] farmKey = Convert.FromBase64String(builder.Configuration["Doconut:FarmKey"]);
builder.Services.AddDoconutDistributedWidgets(store =>
{
store.RootPath = @"\\fileshare\doconut"; // folder, który każdy węzeł może odczytywać i zapisywać
store.FarmKey = farmKey; // co najmniej 32 bajty, identyczne na każdym węźle
// store.Ttl = TimeSpan.FromMinutes(30); // jak długo przechowywane jest przesłanie (domyślnie)
});- Pojedynczy serwer nie potrzebuje nic: bez tego wywołania używany jest magazyn w pamięci.
- Przesyłane pliki i wyniki są szyfrowane w spoczynku na udziale (AES-256, encrypt-then-MAC), a każdy plik jest powiązany ze swoim tokenem, więc żaden token nie może odczytać pliku innego tokenu.
FarmKeymusi mieć co najmniej 32 bajty i być taki sam na każdym węźle. Załaduj go z magazynu sekretów; nigdy nie koduj na stałe. Rejestracja zgłaszaArgumentException, gdyRootPathjest brakujący lubFarmKeyjest krótszy niż 32 bajty.- Skieruj
RootPathna tę samą współdzieloną lokalizację, której używa rozproszony przeglądacz, i zapewnij każdemu węzłowi ten sam certyfikat podpisujący.
Referencja API
Fasada i opcje widżetu znajdują się w przestrzeni nazw Doconut; typy żądań i wyników znajdują się w Doconut.Core.Models.Signing. SignerPlugin znajduje się w Doconut.Plugins.Signer.
DocumentSigner
public sealed class DocumentSigner
{
public Task<SignResult> SignAsync(
Stream source, string sourceExtension, SignRequest request,
SigningCertificate? cert = null, CancellationToken ct = default);
}Rozwiązywany przez wstrzykiwanie zależności; konstruktor jest wewnętrzny. sourceExtension jest ".pdf" lub ".docx". Przy płatnej licencji używany jest cert i wynik jest czysty; przy licencji tymczasowej używany jest wbudowany certyfikat demonstracyjny, cert jest ignorowany, a wynik jest znakowany wodą.
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 widoczna sygnatura umieszczona raz, plus opcjonalne metadane podpisującego.
VisibleSignature i SignatureKind
public sealed record VisibleSignature(SignatureKind Kind, byte[] PngBytes)
{
public bool IsValid { get; } // PngBytes nie jest pusty
}
public enum SignatureKind { Drawn, Typed, Image }PngBytes jest plikiem PNG dla każdego rodzaju. Rysowana lub wpisana sygnatura jest przezroczysta; przesłany obraz zachowuje swoją przezroczystość, więc nieprzezroczysty JPG pozostaje nieprzezroczysty. Kind jest jedynie wskazówką.
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 jest liczony od 1; X, Y, W i H są znormalizowane 0..1 od lewego górnego rogu.
SignatureMode i WordOutput
public enum SignatureMode { Certified, Visual } // Certified jest domyślny
public enum WordOutput { Pdf, Docx } // Pdf jest domyślny; ignorowane dla źródeł PDFSignResult
public sealed record SignResult(Stream Stream, string Extension);Podpisany dokument jako strumień z możliwością przewijania oraz jego rozszerzenie z kropką (".pdf" lub ".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 nie jest pusty, lub PfxPath nie jest pusty
}Ustaw albo PfxBytes, albo 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; }
}Ustawione przez DoconutOptions.AddSignerWidget(Action<SignerWidgetOptions>? configure = null), który zwraca DoconutOptions, aby wywołania mogły być łańcuchowane. Null SigningCertificate oznacza certyfikat demonstracyjny przy licencji tymczasowej, a sygnatury wizualne tylko przy płatnej.
Rozwiązywanie problemów
| Objaw | Przyczyna | Rozwiązanie |
|---|---|---|
AddDoconut() throws The Signer plugin is registered via AddPlugin but no active license grants Signer. | Brak licencji, plik TRIAL, licencja bez Signer lub płatna licencja poza swoim oknem wersji | Zainstaluj licencję, która przyznaje Signer, lub usuń AddPlugin<SignerPlugin>() |
AddDoconut() throws AddSignerWidget() was called but the Signer plugin is not registered. | Widżet jest włączony bez swojej wtyczki | Dodaj options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>() |
AddDoconut() throws Doconut Signer: the certificate file was not found at '{path}'. | PfxPath wskazuje na brakujący plik | Napraw ścieżkę; wdroż plik w miejscu, gdzie konto aplikacji może go odczytać |
AddDoconut() throws Doconut Signer: the signing certificate could not be opened — the password is incorrect or the file is not a valid .pfx. | Nieprawidłowe hasło lub plik nie jest PKCS#12 | Sprawdź hasło; użyj prawdziwego .pfx |
AddDoconut() throws Doconut Signer: the signing certificate has no private key. Re-export the .pfx INCLUDING the private key. | Plik PFX został wyeksportowany bez klucza prywatnego | Wyeksportuj go ponownie z kluczem prywatnym |
Rozwiązywanie DocumentSigner powoduje błąd No IDocumentSigner is registered. | SignerPlugin nie jest zarejestrowane | Dodaj AddPlugin<SignerPlugin>() wewnątrz AddDoconut() |
| Wynik jest znakowany wodą | Licencja jest tymczasowa (Demo/NFR) | Użyj płatnej licencji, która przyznaje Signer |
run odpowiada 400 No signing certificate configured. | Płatna licencja, tryb Certified i brak certyfikatu | Skonfiguruj SigningCertificate, lub podpisz w trybie Visual |
run odpowiada 400 The signing certificate expired on yyyy-MM-dd. | Certyfikat jest nieaktualny | Zastąp go; sygnatury wizualne działają w międzyczasie |
| Log mówi, że wynik "używa wbudowanego certyfikatu demonstracyjnego", jednak płatna licencja odrzuca sygnatury Certified | Ten komunikat jest zapisywany zawsze, gdy nie skonfigurowano certyfikatu, niezależnie od licencji | Skonfiguruj SigningCertificate |
Widżet ładuje się, ale wyświetla Signing is not enabled on this server. | AddSignerWidget() nie został wywołany, lub basePath nie pasuje do miejsca, w którym UseDoconut() jest zamontowany | Wywołaj AddSignerWidget(); napraw basePath |
run odpowiada 400 The signature image must be a PNG., Signature image is not valid base64. lub Signature image is too large. | Niestandardowy interfejs wysłał URL data:, JPG lub więcej niż MaxSignatureImageKb | Wyślij czysty PNG w formacie base64 w granicach limitu |
open odpowiada 413 File is too large. | Przesyłanie przekracza MaxUploadMb | Zwiększ MaxUploadMb w AddSignerWidget; maxUploadMb widżetu jest jedynie kontrolą po stronie klienta |
run lub download odpowiada 404 Upload expired — please re-open the file. | Okno 30‑minutowe upłynęło, lub węzeł farmy sieciowej nie ma przesłanego pliku | Otwórz plik ponownie; w farmie, zarejestruj AddDoconutDistributedWidgets |
Podpisany .docx nie wyświetla podpisu w niektórych przeglądarkach | Wyjście Word zawiera podpis pakietu OOXML, którego wiele przeglądarek nie wyświetla | Podpisz do PDF, domyślnie |
| Czytniki PDF mówią, że tożsamość podpisującego jest nieznana | Czytnik nie ufa głównemu certyfikatowi (certyfikat demonstracyjny nigdy nie jest zaufany) | Użyj certyfikatu z głównym certyfikatem, któremu Twoi czytelnicy ufają |
| Widżet nie działa, gdy interfejs UI znajduje się na innym pochodzeniu | Punkty końcowe nie obsługują CORS | Udostępnij UI z tego samego pochodzenia, lub użyj reverse‑proxy dla ścieżek Doconut |
| Motyw nie jest stosowany | Selektor celuje w element wewnątrz montowania | Celuj w samo montowanie: #host.dsw lub #host |
Czy ta strona była pomocna?