Wtyczka Signer

Podpisuj dokumenty PDF i Word przy użyciu widocznego podpisu i cyfrowej pieczęci

Wtyczka Signer umieszcza widoczny podpis na dokumencie i domyślnie uszczelnia go cyfrowym podpisem, który może zweryfikować czytnik PDF. Podpisuje PDF i Word (.docx) pliki. Widoczny podpis jest zawsze obrazem PNG: narysowany, wpisany lub przesłany przez podpisującego.

PowierzchniaUżyj, gdy
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 zgodnie z udokumentowanym kontraktem serwera

Każdy podpis jest umieszczany raz, na jednej stronie. Imię i nazwisko podpisującego, powód oraz lokalizacja mogą podążać za nim.

Zainstaluj pakiet

Zainstaluj najnowszą stabilną wtyczkę Signer:

bash
dotnet add package Doconut.NETStandard.Signer

Aby przypiąć wtyczkę do wersji opisanej w tej dokumentacji, przekaż wersję osobno:

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

Utrzymuj pakiet Signer w tej samej wersji co Doconut.NETStandard. Identyfikator pakietu to Doconut.NETStandard.Signer; .<version> pojawia się tylko w nazwie pobranego 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.

Zarejestruj wtyczkę

Podobnie jak każda wtyczka Doconut, Signer rejestruje się przy użyciu AddPlugin<TPlugin>() wewnątrz AddDoconut():

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
});

To wszystko, czego potrzebuje fasada C#. Widget i jego endpointy HTTP są oddzielnym elementem opcjonalnym, AddSignerWidget() (zobacz Widget Drop-in).

Wtyczka wymaga licencji, która przyznaje możliwość Signer. Bez niej, AddDoconut() zgłasza wyjątek przy uruchomieniu, zanim aplikacja obsłuży żądanie:

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.

Zgłasza wyjątek przy braku licencji, starszym pliku TRIAL, licencji bez Signer oraz płatnej licencji użytej poza okresem jej wersji. Tymczasowe licencje Demo/NFR są akceptowane. Zobacz Ustawienia licencji, aby dowiedzieć się, jak ładowane są licencje.

Licencjonowanie i znak wodny

Stan licencjiUruchomieniePodpis certyfikowanyPodpis wizualny
Płatna licencja przyznająca Signer, certyfikat skonfigurowanyUruchamia sięUszczelniona Twoim certyfikatem, czysta (watermarked: false)Czysty
Płatna licencja przyznająca Signer, brak certyfikatuUruchamia sięOdrzucona: No signing certificate configured.Czysty
Płatna licencja, certyfikat wygasły lub jeszcze nieważnyUruchamia się (przy włączonym widgetcie, rejestrowane jest ostrzeżenie)Odrzucona: The signing certificate expired on yyyy-MM-dd.Czysty
Tymczasowa licencja Demo/NFR, aktywna lub wygasłaUruchamia sięUszczelniona wbudowanym certyfikatem demo, znakowana (watermarked: true)Znakowana
Brak licencji, starszy plik TRIAL, licencja bez Signer lub płatna licencja poza okresem wersjiAddDoconut() zgłasza wyjątek——

Zasada jest taka sama dla fasady C# i widgetu: 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 generuje prawdziwą pieczęć, ale czytniki PDF go nie ufają. Integrację można zbudować i przetestować end‑to‑end 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ązanie go bez AddPlugin<SignerPlugin>() powoduje rzucenie 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 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 widgetu. 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. Ty jesteś właścicielem strumienia: zwolnij go, gdy skończysz.

Podpis Visual nakłada tylko obraz i nie wymaga certyfikatu:

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);

Źródło Word jest podpisywane do PDF, chyba że poprosisz o wyjście w formacie Word. Nazwij wynik 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 rzuca wyjątek zamiast zwracać, gdy wywołanie nie może się powieść:

WyjątekKomunikatKiedy
InvalidOperationExceptionNo signing certificate configured.Tryb Certified, płatna licencja i brak przekazanego certyfikatu
InvalidOperationExceptionThe 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
ArgumentExceptionThe 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 pozycja, która nie jest prawidłowa
NotSupportedExceptionThe 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.

TrybCo produkujeCertyfikatWeryfikowalny
SignatureMode.Certified (default)Widoczny podpis plus cyfrowa pieczęćRequired under a paid licenseTak
SignatureMode.VisualTylko widoczny podpisNever neededNie: to jest obraz

Używaj Certified, gdy podpis musi być dowodny: 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 rootowi, może zbudować łańcuch. Pieczęcie natywne dla Word są podpisami 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ścieCo się dziejeObsługa weryfikatora
WordOutput.Pdf (default)Dokument jest konwertowany do PDF, a następnie podpisywany i uszczelnianySzeroka: podpisany PDF jest weryfikowany wszędzie
WordOutput.DocxDokument pozostaje w formacie Word: obraz podpisu jest w nim umieszczany, plus podpis pakietu OOXMLOgraniczona: 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 widgetu ustaw SignerWidgetOptions.SigningCertificate; dla fasady C# przekaż certyfikat do SignAsync. Dostarcz albo bajty, albo ścieżkę, plus hasło:

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"],
        };
    });
});

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 wyłącznie 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 Certified są odrzucane, dopóki nie zostanie zastąpiony. Podpisy wizualne pozostają nienaruszone.
  • 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 i 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:

bash
openssl pkcs12 -export -out signing.pfx -inkey private.key -in certificate.crt
# Hasło eksportu, o które jesteś pytany, to SigningCertificate.Password.

Wyeksportuj go 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 widget jest włączony, certyfikat w SignerWidgetOptions.SigningCertificate jest sprawdzany raz, wewnątrz AddDoconut(), więc źle skonfigurowany PFX powoduje błąd przy uruchomieniu, a nie przy pierwszym podpisie. Trzy problemy generują InvalidOperationException:

Wiadomość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.Ponownie wyeksportuj PFX z kluczem prywatnym

W przeciwnym razie host zapisuje jedną linię w logu przy uruchomieniu. Informacja, gdy certyfikat jest gotowy:

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

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.

Informacja, gdy żaden certyfikat nie jest skonfigurowany:

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.

Ostatnia linia jest taka sama we wszystkich licencjach. W płatnej licencji certyfikat demonstracyjny nigdy nie jest używany: bez certyfikatu działają wyłącznie podpisy Visual.

Fasada C# nie jest sprawdzana przy uruchomieniu. Certyfikat przekazany do SignAsync jest odczytywany podczas podpisywania, więc nieprawidłowa ścieżka lub hasło powodują błąd wywołania.

Widżet typu 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:

csharp
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 demonstracyjnego (z znakiem wodnym) podpisu
    });
});

AddSignerWidget() bez argumentu włącza widżet z ustawieniami domyślnymi. Nie przyznaje on samodzielnie podpisywania: potrzebuje AddPlugin<SignerPlugin>(), w przeciwnym razie AddDoconut() zgłasza błąd:

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(), każde żądanie ?sign= zwraca 404. Sam skrypt jest nadal dostarczany, 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). Jest to pojedynczy, samodzielny plik bez zależności:

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) przyjmuje selektor CSS lub element, zgłasza błąd, jeśli miejsce montażu nie zostanie znalezione, i zwraca uchwyt.

Podpisujący przesyła plik PDF lub .docx, tworzy podpis (Draw na płótnie, Type nazwę w czcionce podpisu lub Image z pliku 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 w przeglądarce konwertowany na PNG o wymiarach 520×160.

Opcje

OpcjaTypDomyślnieUwagi
basePathstring'/doconut'Gdzie są serwowane punkty końcowe ?sign= i obrazy podglądu
resPathstring'/doconut-res'Zarezerwowane; widżet zawiera własny CSS
maxUploadMbnumber25Sprawdzanie tylko po stronie klienta, więc zbyt duży plik odrzucany jest natychmiast. Limit serwera wynosi MaxUploadMb w AddSignerWidget
maxSignatureKbnumber512Limit po stronie klienta dla trybu Obraz. Utrzymaj go równy limitowi serwera MaxSignatureImageKb
previewWidthnumber560Szerokość w pikselach podglądu strony
licenseUrlstring | nullnullZamienia powiadomienie demo-watermark w link do tego URL
signatureModestring'certified'Początkowy typ podpisu: 'certified' lub 'visual'. Każda inna wartość zostaje zamieniona na 'certified'
showSignatureModeTogglebooleantrueWyświetla wybór Digital signature / Visual only. Z false, widżet podpisuje się przy użyciu signatureMode
wordOutputstring'pdf'Początkowy format wyjścia dla źródeł .docx: 'pdf' lub 'docx'. Każda inna wartość zostaje zamieniona na 'pdf'
showOutputFormatTogglebooleantrueWyświetla wybór PDF / Word, tylko dla źródeł .docx. Z false, widżet używa wordOutput
labelsobject{}Zastępuje dowolny podzbiór angielskich ciągów

Ukrycie przełącznika nie wyłącza funkcji; ustawia wartość na stałą. Dwie typowe konfiguracje:

javascript
// Oba przełączniki wyświetlane, podpis cyfrowy domyślnie: pełny podpisujący w trybie samoobsługowym.
Doconut.signer('#host', { basePath: '/doconut', licenseUrl: '/pricing' });
javascript
// Tylko wizualny, bez przełącznika: prosty stempel bez oferowanego podpisu cyfrowego.
Doconut.signer('#host', {
  basePath: '/doconut',
  signatureMode: 'visual',
  showSignatureModeToggle: false
});

Callbacki

CallbackWywoływany gdyDane
onReadyRaz przy montowaniu (nie ponownie przy reset())—
onSourceLoadedPlik jest otwierany i wyświetlany podgląd{ file: { token, name, pages, ext } }
onSignedPodpisanie powiodło się{ downloadToken, downloadName, watermarked }
onDownloadPrzy każdym kliknięciu Pobierz{ downloadName, downloadToken }
onErrorKrok otwarcia, podpisu lub pobrania nie powiódł się, lub plik w trybie obrazu jest za duży{ message }

Callback, który rzuca wyjątek, jest przechwytywany i logowany; nigdy nie przerywa przepływu widgetu.

Obsługa imperatywna

MetodaZachowanie
reset()Powraca do ekranu upuszczania i czyści bieżący przepływ. Nie wywołuje ponownie onReady. Nie robi nic po destroy()
loadFile(file)Rozpoczyna przepływ z File. Nie robi nic, chyba że widget znajduje się na ekranie upuszczania; w razie potrzeby najpierw wywołaj reset()
destroy()Usuwa nasłuchiwacze, opróżnia montowanie i zamraża instancję
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());

Etykiety

Każdy ciąg ma domyślnie angielską wersję; labels nadpisuje dowolny podzbiór, a pozostałe pozostają po angielsku. Fragmenty zmieniające się w czasie działania używają {placeholders}, takie jak uploading: 'Uploading {name}…' i pages: '{n} pages'.

KluczDomyślnie po angielsku
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

Dalsze klucze obejmują krok umieszczania, 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, widget wyświetla signingNotEnabled. Błąd JSON z serwera zawsze ma pierwszeństwo, więc komunikaty takie jak wygasłe przesłanie pozostają widoczne.

Tematyzacja

Widget dodaje klasę dsw do elementu montującego i odczytuje jego kolory, promień i czcionki z własności CSS, dzięki czemu możesz tematyzować go bez modyfikacji wewnętrznych elementów:

css
#host.dsw {
  --dsw-accent: #b0522b;       /* linki, focus, 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 kursywa dla podpisu.

Zbuduj własny frontend

Widget 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 w tabeli podano „tylko status”. Nieznana wartość ?sign= odpowiada 400.

TrasaCelOdpowiedź sukcesu
POST ?sign=open (multipart, jeden plik)Prześlij PDF lub .docx i otwórz podgląd200 — { token, name, pages, ext }
POST ?sign=run (ciało JSON)Podpisz przesłany plik200 — { downloadToken, downloadName, watermarked }
GET ?sign=download&token=<downloadToken>Strumieniuj podpisany plik200 — 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:

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"
}
PoleUwagi
tokenToken z open
signature.kindDrawn, Typed lub Image, bez rozróżniania wielkości liter; wszystko inne staje się Drawn. Tylko wskazówka: ładunek zawsze jest PNG
signature.payloadSurowy PNG w base64, bez prefiksu data:. Musi być prawdziwym PNG i nie większy niż MaxSignatureImageKb po dekodowaniu
placement.pageNumeracja od 1
placement.x / y / w / hZnormalizowane 0..1 od lewego górnego rogu, z x + w ≤ 1 i y + h ≤ 1
meta.signerName / reason / locationOpcjonalne. Każdy jest przycinany, pusta wartość jest pomijana, a każdy jest ograniczany do 256 znaków
wordOutputpdf (domyślnie) lub docx; ignorowane dla źródeł PDF. Wszystko inne staje się pdf
modecertified (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.

TrasaStatusKiedyCiało
dowolna404Widget nie jest włączonytylko status
dowolna405Nieprawidłowa metoda (open i run wymagają POST, download wymaga GET)tylko status
open400Nie jest to przesyłanie multipartExpected a multipart file upload.
open400Brak pliku lub pusty plikNo file uploaded.
open400Cokolwiek innego niż .pdf lub .docxSigning supports PDF and Word (.docx) files only.
open413Przesyłanie przekracza MaxUploadMbFile is too large.
run400Ciało nie jest prawidłowym JSON‑em lub jest pusteMalformed request. / Empty request.
run400Brak tokenu lub nie jest GUID‑emInvalid token.
run404Przesyłanie wygasło lub nigdy nie zostało otwarteUpload expired — please re-open the file.
run400Brak podpisu lub brak umiejscowieniaNo signature supplied. / No placement supplied.
run400Ładunek nie jest base64, jest pusty, za duży lub nie jest PNGSignature image is not valid base64. / Signature image is empty. / Signature image is too large. / The signature image must be a PNG.
run400Umiejscowienie jest poza stronąThe signature or its placement is invalid.
run400Tryb certyfikowany, płatna licencja i brak certyfikatuNo signing certificate configured.
run400Tryb certyfikowany z certyfikatem poza okresem ważnościThe signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd.
open, run500Przetwarzanie nie powiodło sięZsanityzowana wiadomość
download400Brak tokenu lub nie jest GUID‑emtylko status
download404Nieznany lub wygasły tokentylko status

Pełny cykl z fetch:

javascript
// 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 zastosuj reverse‑proxy dla obu ścieżek /doconut (ścieżki pośredniczącej i ścieżki zasobów) pod pochodzeniem Twojego UI.

W produkcji

  1. Zainstaluj wtyczkę obok pakietu core, w tej samej wersji: dotnet add package Doconut.NETStandard.Signer.

  2. Dodaj plik licencji. Umieść Doconut.Viewer.Signer.lic w tym samym folderze co Doconut.Viewer.lic.

  3. Uzyskaj swój certyfikat jako 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.

  4. Odczytaj certyfikat z konfiguracji, aby jego zmiana nigdy nie wymagała zmiany kodu:

    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"] ?? "",
        });
    });

    Trzymaj .pfx poza wwwroot, i przechowuj hasło poza appsettings.json: sekrety użytkownika w środowisku deweloperskim (dotnet user-secrets set "DoconutSigner:Password" "<password>"), zmienną środowiskową (DoconutSigner__Password) lub skarbcem w produkcji.

  5. 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 ramach PKI Twojej organizacji obowiązuje to na każdym komputerze, który ufa Twojemu korzeniowi, co zazwyczaj oznacza wszystkie maszyny w organizacji. Certyfikaty, które 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 odnaleźć przesłanego pliku. Zarejestruj współdzielony, zaszyfrowany magazyn widgetu raz, po AddDoconut():

csharp
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 odczytać i zapisać
    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)
});
  • Jeden serwer nie potrzebuje niczego: 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 jeden token nigdy nie może odczytać pliku innego tokena.
  • FarmKey musi 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łasza ArgumentException, gdy RootPath jest brakujący lub FarmKey jest krótszy niż 32 bajty.
  • Wskaż RootPath na tę samą współdzieloną lokalizację, której używa rozproszony podgląd, i zapewnij każdemu węzłowi ten sam certyfikat podpisu.

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 jest w 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);
}

Rozwiązywane przez wstrzykiwanie zależności; konstruktor jest wewnętrzny. sourceExtension jest ".pdf" lub ".docx". Przy płatnej licencji cert jest używany i wynik jest czysty; przy licencji tymczasowej używany jest wbudowany certyfikat demonstracyjny, cert jest ignorowany, a wynik jest oznaczony znakiem wodnym.

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 widoczna sygnatura umieszczona raz, plus opcjonalne metadane podpisującego.

VisibleSignature and SignatureKind

csharp
public sealed record VisibleSignature(SignatureKind Kind, byte[] PngBytes)
{
    public bool IsValid { get; }   // PngBytes nie jest pusty
}

public enum SignatureKind { Drawn, Typed, Image }

PngBytes jest 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 tylko wskazówką.

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 jest indeksowane od 1; X, Y, W i H są znormalizowane 0..1 od lewego górnego rogu.

SignatureMode and WordOutput

csharp
public enum SignatureMode { Certified, Visual }   // Certified jest domyślny
public enum WordOutput { Pdf, Docx }              // Pdf jest domyślny; ignorowane dla źródeł PDF

SignResult

csharp
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

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 nie jest pusty, lub PfxPath nie jest pusty
}

Ustaw albo PfxBytes, albo 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; }
}

Ustawiane przez DoconutOptions.AddSignerWidget(Action<SignerWidgetOptions>? configure = null), który zwraca DoconutOptions, więc wywołania mogą być łańcuchowane. Null SigningCertificate oznacza certyfikat demonstracyjny przy licencji tymczasowej, a sygnatury wizualne tylko przy płatnej.

Rozwiązywanie problemów

ObjawPrzyczynaRozwiązanie
AddDoconut() rzuca 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 wersjiZainstaluj licencję, która przyznaje Signer, lub usuń AddPlugin<SignerPlugin>()
AddDoconut() rzuca AddSignerWidget() was called but the Signer plugin is not registered.Widżet jest włączony bez swojej wtyczkiDodaj options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>()
AddDoconut() rzuca Doconut Signer: the certificate file was not found at '{path}'.PfxPath wskazuje na brakujący plikNapraw ścieżkę; wdroż plik w miejscu, gdzie konto aplikacji może go odczytać
AddDoconut() rzuca 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 nie jest to plik PKCS#12Sprawdź hasło; użyj prawdziwego .pfx
AddDoconut() rzuca Doconut Signer: the signing certificate has no private key. Re-export the .pfx INCLUDING the private key.PFX został wyeksportowany bez klucza prywatnegoWyeksportuj go ponownie z kluczem prywatnym
Rozwiązywanie DocumentSigner rzuca No IDocumentSigner is registered.SignerPlugin nie jest zarejestrowanyDodaj AddPlugin<SignerPlugin>() wewnątrz AddDoconut()
Wynik jest oznaczony znakiem wodnymLicencja 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 certyfikatuSkonfiguruj SigningCertificate, lub podpisz w trybie Visual
run odpowiada 400 The signing certificate expired on yyyy-MM-dd.Certyfikat jest nieaktualnyZastą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 CertifiedTen wiersz jest zapisywany zawsze, gdy nie skonfigurowano certyfikatu, niezależnie od licencjiSkonfiguruj SigningCertificate
Widżet ładuje się, ale mówi Signing is not enabled on this server.AddSignerWidget() nie został wywołany, lub basePath nie pasuje do miejsca, gdzie zamontowano UseDoconut()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ż MaxSignatureImageKbWyślij czysty PNG w base64 w granicach limitu
open odpowiada 413 File is too large.Przesyłanie przekracza MaxUploadMbZwiększ MaxUploadMb w AddSignerWidget; maxUploadMb widżetu to tylko kontrola po stronie klienta
run lub download odpowiada 404 Upload expired — please re-open the file.Upłynęło 30 minut, lub węzeł farmy web nie ma przesłanego plikuOtwórz plik ponownie; w farmie zarejestruj AddDoconutDistributedWidgets
Podpisany .docx nie pokazuje podpisu w niektórych przeglądarkachWyjście Word zawiera podpis pakietu OOXML, który wiele przeglądarek nie wyświetlaPodpisz do PDF, domyślnie
Czytniki PDF mówią, że tożsamość podpisującego jest nieznanaCzytnik nie ufa głównemu certyfikatowi (certyfikat demonstracyjny nigdy nie jest zaufany)Użyj certyfikatu z korzenia, któremu twoi czytnicy ufają
Widżet nie działa, gdy UI jest na innym pochodzeniuPunkty końcowe nie mają obsługi CORSSerwuj UI z tego samego pochodzenia, lub użyj reverse-proxy dla ścieżek Doconut
Motyw nie jest stosowanySelektor celuje w element wewnątrz montażuCeluj w sam montaż: #host.dsw lub #host

Czy ta strona była pomocna?