Plugin Penandatangan
Tanda tangani PDF dan dokumen Word dengan tanda tangan yang terlihat serta segel digital
Plugin Penandatangan menempatkan tanda tangan yang terlihat pada sebuah dokumen dan, secara default, menutupinya dengan tanda tangan digital yang dapat diverifikasi oleh pembaca PDF. Ia menandatangani file PDF dan Word (.docx). Tanda tangan yang terlihat selalu berupa gambar PNG: digambar, diketik, atau diunggah oleh penandatangan.
| Antarmuka | Gunakan ketika |
|---|---|
DocumentSigner (C#) | Anda menandatangani di server, tanpa melibatkan browser |
Drop-in widget (doconutSigner.js) | Anda menginginkan layar unggah, tanda tangan, dan unduh siap pakai di halaman Anda |
HTTP endpoints (?sign=open|run|download) | Anda membangun UI penandatanganan Anda sendiri berdasarkan kontrak server yang terdokumentasi |
Setiap tanda tangan ditempatkan sekali, pada satu halaman. Nama penandatangan, alasan, dan lokasi dapat menyertainya.
Instal paket
Instal plugin Penandatangan terbaru yang stabil:
dotnet add package Doconut.NET8.SignerUntuk mengunci plugin ke rilis yang dijelaskan dalam dokumentasi ini, berikan versi secara terpisah:
dotnet add package Doconut.NET8.Signer --version 26.10.0Pertahankan paket Penandatangan pada versi yang sama dengan Doconut.NET8. ID paketnya adalah Doconut.NET8.Signer; .<version> hanya muncul dalam nama file .nupkg yang diunduh.
File lisensi plugin, Doconut.Viewer.Signer.lic, diletakkan di folder yang sama dengan Doconut.Viewer.lic; file ini dibaca bersama lisensi penampil.
Platform. Plugin berjalan di mana pun Doconut.NET8 berjalan: Windows, dan Linux berbasis glibc pada x64 (bukan Alpine atau distribusi berbasis musl lainnya). Di Linux, instal pustaka konfigurasi font sebelum dokumen pertama dibuka:
apt-get update && apt-get install -y libfontconfig1Pada RHEL, Fedora, dan distribusi serupa paketnya adalah fontconfig. Tanpa itu, membuka dokumen gagal dengan The system library libfontconfig1 is missing. Install it (Debian/Ubuntu: apt-get install -y libfontconfig1) and see the Linux section of the Doconut documentation.
Daftarkan plugin
Seperti setiap plugin Doconut, Penandatangan mendaftar dengan AddPlugin<TPlugin>() di dalam AddDoconut():
builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
});Itu semua yang dibutuhkan oleh antarmuka C#. Widget dan endpoint HTTP-nya merupakan opt‑in terpisah, AddSignerWidget() (lihat Widget Drop‑in).
Plugin memerlukan lisensi yang memberikan kemampuan Signer. Tanpa lisensi, AddDoconut() akan melempar kesalahan saat startup, sebelum aplikasi melayani permintaan:
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.Kesalahan ini terjadi karena tidak ada lisensi, file legacy TRIAL, lisensi tanpa Signer, dan lisensi berbayar yang digunakan di luar jendela versinya. Lisensi Demo/NFR sementara diterima. Lihat Pengaturan Lisensi untuk cara memuat lisensi.
Lisensi & watermark
| Status lisensi | Mulai | Tanda tangan bersertifikat | Tanda tangan visual |
|---|---|---|---|
Lisensi berbayar yang memberikan Signer, sertifikat dikonfigurasi | Mulai | Ditutup dengan sertifikat Anda, bersih (watermarked: false) | Bersih |
Lisensi berbayar yang memberikan Signer, tanpa sertifikat | Mulai | Refused: No signing certificate configured. | Bersih |
| Lisensi berbayar, sertifikat kedaluwarsa atau belum valid | Mulai (dengan widget diaktifkan, peringatan dicatat) | Refused: The signing certificate expired on yyyy-MM-dd. | Bersih |
| Lisensi Demo/NFR sementara, aktif atau kedaluwarsa | Mulai | Ditutup dengan sertifikat demo bawaan, diberi watermark (watermarked: true) | Diberi watermark |
Tidak ada lisensi, file legacy TRIAL, lisensi tanpa Signer, atau lisensi berbayar di luar jendela versinya | AddDoconut() melempar | — | — |
Aturannya sama untuk antarmuka C# dan widget: output akan diberi watermark ketika lisensi bukan lisensi penampil berbayar atau bersifat sementara. Di bawah lisensi sementara plugin selalu menandatangani dengan sertifikat demo bawaan, dan sertifikat apa pun yang Anda konfigurasi tidak akan digunakan.
Sertifikat demo menghasilkan segel yang asli, tetapi pembaca PDF tidak mempercayainya. Integrasi dapat dibangun dan diuji secara menyeluruh dengan lisensi evaluasi; untuk mendapatkan output yang bersih dan tepercaya, Anda memerlukan lisensi berbayar serta sertifikat penandatanganan Anda sendiri.
Penggunaan dari C#
DocumentSigner didaftarkan oleh AddDoconut() dan di‑resolve dari dependency injection. Konstruktornya internal, jadi jangan pernah new itu. Menyelesaikannya tanpa AddPlugin<SignerPlugin>() akan melempar No IDocumentSigner is registered. Add the signing plugin: options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>().
using Doconut;
using Doconut.Core.Models.Signing;
public sealed class ContractSigning
{
private readonly DocumentSigner _signer;
public ContractSigning(DocumentSigner signer) => _signer = signer;
public async Task<byte[]> SignAsync(Stream pdf, byte[] signaturePng, SigningCertificate certificate, CancellationToken ct)
{
var request = new SignRequest(
new VisibleSignature(SignatureKind.Drawn, signaturePng),
new SignaturePlacement(Page: 1, X: 0.58, Y: 0.80, W: 0.32, H: 0.12),
SignerName: "Ada Lovelace",
Reason: "I approve this document",
Location: "London, UK");
// Mode default ke Certified (tanda tangan terlihat + segel digital); WordOutput default ke 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 mengambil aliran sumber, ekstensi‑nya (".pdf" atau ".docx"), permintaan, dan sertifikat untuk panggilan ini. Fasade tidak membaca SignerWidgetOptions.SigningCertificate; pengaturan itu untuk widget. Berikan null dengan lisensi demo, atau dalam mode Visual.
SignResult menyimpan dokumen yang ditandatangani sebagai aliran yang dapat dicari, plus Extension‑nya (".pdf" atau ".docx") sehingga Anda dapat memberi nama file. Anda memiliki aliran: dispose it ketika selesai.
Tanda tangan Visual hanya menstempel gambar dan tidak memerlukan sertifikat:
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);Sumber Word ditandatangani menjadi PDF kecuali Anda meminta output Word. Beri nama hasil dari 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 melempar alih‑alih mengembalikan ketika panggilan tidak dapat berhasil:
| Pengecualian | Pesan | Kapan |
|---|---|---|
InvalidOperationException | No signing certificate configured. | Mode Certified, lisensi berbayar, dan tidak ada sertifikat yang diberikan |
InvalidOperationException | The signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd. | Mode Certified dengan sertifikat di luar jendela validitasnya |
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. | Byte PNG kosong, atau penempatan yang tidak valid |
NotSupportedException | The signer supports PDF and Word (.docx) documents; got '{extension}'. | Jenis sumber lain apa pun |
Mode penandatanganan, output Word, dan sertifikat
Mode penandatanganan
SignRequest.Mode memilih apakah tanda tangan disegel.
| Mode | Apa yang dihasilkan | Sertifikat | Dapat diverifikasi |
|---|---|---|---|
SignatureMode.Certified (bawaan) | Tanda tangan yang terlihat plus segel digital | Diperlukan dengan lisensi berbayar | Ya |
SignatureMode.Visual | Hanya tanda tangan yang terlihat | Tidak pernah diperlukan | Tidak: itu adalah gambar |
Gunakan Certified ketika tanda tangan harus dapat dibuktikan: persetujuan, kontrak, apa pun yang perlu diverifikasi untuk memeriksa identitas dan integritas. Gunakan Visual ketika Anda hanya membutuhkan tampilan tanda tangan, atau tidak memiliki sertifikat. Lisensi sementara menambahkan watermark pada keduanya.
Segel PDF adalah tanda tangan terpisah PKCS#7 (adbe.pkcs7.detached) dengan SHA-256, untuk kunci RSA atau ECDSA. Mereka membawa sertifikat penerbit yang ditemukan dalam PFX Anda, sehingga pembaca yang mempercayai root Anda dapat membangun rantai. Segel native Word adalah tanda tangan paket OOXML dan hanya membawa sertifikat penandatangan.
Word documents
Untuk sumber .docx, SignRequest.WordOutput memilih output. Ini diabaikan untuk sumber PDF, yang selalu menghasilkan PDF.
| Output | Apa yang terjadi | Dukungan verifikator |
|---|---|---|
WordOutput.Pdf (default) | Dokumen dikonversi ke PDF, lalu ditandatangani dan disegel | Luas: PDF yang ditandatangani dapat diverifikasi di mana saja |
WordOutput.Docx | Dokumen tetap dalam format Word: gambar tanda tangan ditempatkan di dalamnya, plus tanda tangan paket OOXML | Terbatas: tidak semua penampil menampilkan tanda tangan paket OOXML |
Pertahankan PDF kecuali penerima membutuhkan file Word yang dapat diedit dan menerima dukungan verifikator yang terbatas.
Penyiapan Sertifikat
Untuk menyegel dengan identitas Anda sendiri, berikan plugin file PFX (PKCS#12) yang mencakup kunci pribadi. Untuk widget, atur SignerWidgetOptions.SigningCertificate; untuk antarmuka C#, berikan sertifikat ke SignAsync. Sediakan baik byte maupun jalur, plus kata sandi:
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"],
};
});
});Sertifikat hanya disimpan dalam memori. Sertifikat tidak pernah dicatat, dikembalikan ke klien, atau disimpan secara permanen, dan kata sandi tidak pernah muncul dalam baris log atau pesan kesalahan.
Persyaratan:
- Sebuah bundel PFX / PKCS#12 dengan kunci privatnya. File hanya kunci publik (
.cer,.crt) tidak dapat menandatangani. Ekspor rantai penerbit bersama dengannya, sehingga segel PDF dapat menyertakannya. - Kata sandi yang benar.
- Di dalam jangka waktu validitasnya. Sertifikat yang kedaluwarsa atau belum berlaku tidak menghentikan aplikasi: akan dicatat sebagai Peringatan saat startup, dan tanda tangan Bersertifikat ditolak hingga diganti. Tanda tangan Visual tidak terpengaruh.
- Dikeluarkan untuk penandatanganan dokumen: penggunaan kunci dengan digital signature atau non-repudiation, dan penggunaan kunci tambahan, jika ada, yang memungkinkan penandatanganan dokumen, perlindungan email, atau otentikasi klien. Sertifikat yang dikeluarkan untuk hal lain, seperti sertifikat server TLS, tetap dapat menandatangani, tetapi akan dicatat sebagai Peringatan dan pembaca PDF menandai tanda tangan tersebut.
- Token perangkat keras, kartu pintar, HSM, dan penyimpanan sertifikat Windows tidak didukung. Ekspor sertifikat, beserta kunci privat dan rantainya, ke dalam PFX.
Buat PFX dari sertifikat dan kunci privatnya dengan OpenSSL:
openssl pkcs12 -export -out signing.pfx -inkey private.key -in certificate.crt
# Kata sandi ekspor yang diminta adalah SigningCertificate.Password.Ekspor satu dari penyimpanan sertifikat Windows: buka certmgr.msc dan temukan sertifikat (ikonnya menunjukkan kunci ketika kunci privat ada). Klik kanan, pilih All Tasks → Export…, pilih Yes, export the private key, pilih Personal Information Exchange – PKCS #12 (.PFX), dan tetapkan kata sandi.
Pemeriksaan Startup
Ketika widget diaktifkan, sertifikat di SignerWidgetOptions.SigningCertificate diperiksa sekali, di dalam AddDoconut(), sehingga PFX yang salah konfigurasi gagal saat startup bukan pada tanda tangan pertama. Tiga masalah menghasilkan InvalidOperationException:
| Pesan | Perbaikan |
|---|---|
Doconut Signer: the certificate file was not found at '{path}'. | Benarkan PfxPath; pastikan file dideploy dan dapat dibaca oleh akun aplikasi |
Doconut Signer: the signing certificate could not be opened — the password is incorrect or the file is not a valid .pfx. | Periksa kata sandi; pastikan file adalah .pfx yang sebenarnya, bukan .cer atau .pem |
Doconut Signer: the signing certificate has no private key. Re-export the .pfx INCLUDING the private key. | Ekspor PFX lagi dengan kunci privat |
Jika tidak, host menulis satu baris ke log saat dimulai. Informasi ketika sertifikat siap:
Doconut Signer: using certificate '{subject}' (valid until yyyy-MM-dd). Signatures are digitally sealed.Sebuah Peringatan ketika sertifikat kedaluwarsa, belum berlaku, atau tidak dikeluarkan untuk penandatanganan dokumen:
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.Dan Informasi ketika tidak ada sertifikat yang dikonfigurasi:
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.Baris terakhir itu sama di semua lisensi. Pada lisensi berbayar sertifikat demo tidak pernah digunakan: tanpa sertifikat, hanya tanda tangan Visual yang berfungsi.
Antarmuka C# tidak diperiksa saat startup. Sertifikat yang Anda berikan ke SignAsync dibaca saat menandatangani, sehingga jalur atau kata sandi yang salah menyebabkan panggilan itu gagal.
Widget yang dapat disisipkan
Aktifkan endpoint
Endpoint ?sign=open|run|download widget dinonaktifkan secara default. Aktifkan mereka di sebelah pendaftaran plugin:
builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
options.AddSignerWidget(widget =>
{
widget.MaxUploadMb = 25; // bawaan
widget.MaxSignatureImageKb = 512; // bawaan
// widget.SigningCertificate: lihat penyiapan Certificate; biarkan null untuk penandatanganan demo (berwatermark)
});
});AddSignerWidget() tanpa argumen mengaktifkan widget dengan nilai bawaan. Itu tidak memberikan hak menandatangani sendiri: ia membutuhkan AddPlugin<SignerPlugin>(), atau AddDoconut() melempar:
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.Tanpa AddSignerWidget(), setiap permintaan ?sign= menjawab 404. Skrip itu sendiri tetap disajikan, sehingga widget memuat dan menggambar zona drop‑nya, kemudian melaporkan Signing is not enabled on this server. pada permintaan pertama.
Sisipkan
UseDoconutResources() menyajikan skrip di {ResourcesPath}/js/doconutSigner.js (default /doconut-res/js/doconutSigner.js). Ini adalah file tunggal yang mandiri tanpa ketergantungan:
<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) mengambil selector CSS atau elemen, melempar jika mount tidak ditemukan, dan mengembalikan handle.
Penandatangan mengunggah file PDF atau file .docx, membuat tanda tangan (Draw pada kanvas, Type nama dengan font tanda tangan, atau Image dari PNG, JPG, atau GIF), menyeret dan mengubah ukurannya pada halaman, lalu menandatangani dan mengunduh hasilnya. Widget selalu mengirimkan tanda tangan sebagai PNG; gambar yang diunggah dikonversi di browser menjadi PNG dengan ukuran 520×160.
Opsi
| Opsi | Tipe | Bawaan | Catatan |
|---|---|---|---|
basePath | string | '/doconut' | Di mana endpoint ?sign= dan gambar pratinjau disajikan |
resPath | string | '/doconut-res' | Cadangan; widget menyertakan CSS‑nya sendiri |
maxUploadMb | number | 25 | Hanya pemeriksaan sisi klien, sehingga file yang terlalu besar gagal cepat. Batas server adalah MaxUploadMb dalam AddSignerWidget |
maxSignatureKb | number | 512 | Batas sisi klien untuk mode Gambar. Jaga agar sama dengan MaxSignatureImageKb server |
previewWidth | number | 560 | Lebar piksel pratinjau halaman |
licenseUrl | string | null | null | Mengubah pemberitahuan demo-watermark menjadi tautan ke URL ini |
signatureMode | string | 'certified' | Tipe tanda tangan awal: 'certified' atau 'visual'. Nilai lain menjadi 'certified' |
showSignatureModeToggle | boolean | true | Menampilkan pilihan Digital signature / Visual only. Dengan false, widget menandatangani dengan signatureMode |
wordOutput | string | 'pdf' | Output awal untuk sumber .docx: 'pdf' atau 'docx'. Nilai lain menjadi 'pdf' |
showOutputFormatToggle | boolean | true | Menampilkan pilihan PDF / Word, hanya untuk sumber .docx. Dengan false, widget menggunakan wordOutput |
labels | object | {} | Menimpa subset apa pun dari string bahasa Inggris |
Menyembunyikan toggle tidak menonaktifkan fitur; itu menetapkan nilai. Dua konfigurasi umum:
// Kedua saklar ditampilkan, tanda tangan digital secara default: penandatangan layanan mandiri penuh.
Doconut.signer('#host', { basePath: '/doconut', licenseUrl: '/pricing' });// Hanya visual, tanpa saklar: stempel sederhana tanpa tanda tangan digital yang ditawarkan.
Doconut.signer('#host', {
basePath: '/doconut',
signatureMode: 'visual',
showSignatureModeToggle: false
});Panggilan balik
| Panggilan balik | Terpicu ketika | Muatan |
|---|---|---|
onReady | Sekali, saat mount (tidak lagi pada reset()) | — |
onSourceLoaded | File dibuka dan pratinjau ditampilkan | { file: { token, name, pages, ext } } |
onSigned | Penandatanganan berhasil | { downloadToken, downloadName, watermarked } |
onDownload | Setiap kali klik Download | { downloadName, downloadToken } |
onError | Langkah buka, tanda tangan, atau unduh gagal, atau file mode Gambar terlalu besar | { message } |
Callback yang melempar akan ditangkap dan dicatat; itu tidak pernah menghentikan alur widget.
Penanganan Imperatif
| Metode | Perilaku |
|---|---|
reset() | Kembali ke layar drop dan mengosongkan alur saat ini. Tidak memicu onReady lagi. Tidak melakukan apa-apa setelah destroy() |
loadFile(file) | Memulai alur dengan sebuah File. Tidak melakukan apa-apa kecuali widget berada di layar drop; panggil reset() terlebih dahulu jika diperlukan |
destroy() | Menghapus pendengar, mengosongkan mount, dan membekukan instance |
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());Label
Setiap string memiliki default bahasa Inggris; labels menggantikan sebagian subset dan sisanya tetap bahasa Inggris. Fragmen yang berubah pada runtime menggunakan {placeholders}, seperti uploading: 'Uploading {name}…' dan pages: '{n} pages'.
| Kunci | Default bahasa Inggris |
|---|---|
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 |
Kunci lebih lanjut mencakup langkah penempatan, layar error, formulir terhubung dari pemberitahuan demo (demoNoticePrefix, demoNoticeLink, demoNoticeSuffix) dan pengumuman aria-live.
Ketika open atau run menjawab 404 tanpa error JSON, widget menampilkan signingNotEnabled. Error JSON dari server selalu diutamakan, sehingga pesan seperti unggahan yang kedaluwarsa tetap terlihat.
Penataan Tema
Widget menambahkan kelas dsw ke elemen mount-nya dan membaca warna, radius, serta font dari properti khusus CSS, sehingga Anda dapat menata temanya tanpa menyentuh bagian internalnya:
#host.dsw {
--dsw-accent: #b0522b; /* tautan, fokus, mode aktif */
--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; /* mode Type */
}Default: --dsw-accent: #2b6cb0, --dsw-bg: #ffffff, --dsw-fg: #1a202c, --dsw-muted: #718096, --dsw-border: #cbd5e0, --dsw-radius: 8px, font UI sistem, dan font tanda tangan bergaya kursif.
Bangun frontend Anda sendiri
Widget adalah klien untuk kontrak HTTP ini. Semua tiga rute berada di bawah jalur tempat UseDoconut() dipasang (biasanya /doconut), dan mereka menjawab 404 sampai AddSignerWidget() dipanggil. Error membawa badan JSON, { "error": "..." }, kecuali dimana tabel menyatakan "status only". Nilai ?sign= yang tidak dikenal menjawab 400.
| Rute | Tujuan | Respons sukses |
|---|---|---|
POST ?sign=open (multipart, satu file) | Unggah PDF atau .docx dan buka untuk pratinjau | 200 — { token, name, pages, ext } |
POST ?sign=run (badan JSON) | Tandatangani file yang diunggah | 200 — { downloadToken, downloadName, watermarked } |
GET ?sign=download&token=<downloadToken> | Alirkan file yang ditandatangani | 200 — file, Content-Disposition: attachment, Cache-Control: no-store |
ext dalam respons open menyertakan titik depan (".docx"). Pratinjau halaman menggunakan rute gambar penampil standar, {basePath}?token={token}&page={n}&thumb=1&width={px}; halaman yang ditampilkan menjadi placement.page.
Badan 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"
}| Bidang | Catatan |
|---|---|
token | Token dari open |
signature.kind | Drawn, Typed atau Image, tidak sensitif huruf; apa pun yang lain menjadi Drawn. Hanya petunjuk: muatan selalu PNG |
signature.payload | PNG base64 mentah, tanpa awalan data:. Harus berupa PNG asli dan tidak lebih besar dari MaxSignatureImageKb setelah didekode |
placement.page | Berbasis 1 |
placement.x / y / w / h | 0..1 yang dinormalisasi dari sudut kiri atas, dengan x + w ≤ 1 dan y + h ≤ 1 |
meta.signerName / reason / location | Opsional. Setiap nilai dipangkas, nilai kosong diabaikan, dan setiap dipotong pada 256 karakter |
wordOutput | pdf (default) atau docx; diabaikan untuk sumber PDF. Apa pun yang lain menjadi pdf |
mode | certified (default) atau visual. Apa pun yang lain menjadi certified |
downloadName mengikuti output: <source>-signed.pdf atau <source>-signed.docx, dan download mengirim Content-Type yang cocok.
Sumber yang diunggah dan hasil yang ditandatangani masing-masing disimpan selama 30 menit. Setelah itu, run dan download menjawab 404 dan file harus dibuka kembali. Semua token adalah GUID.
| Rute | Status | Kapan | Badan |
|---|---|---|---|
| any | 404 | Widget tidak diaktifkan | hanya status |
| any | 405 | Verba salah (open dan run membutuhkan POST, download membutuhkan GET) | hanya status |
open | 400 | Bukan unggahan multipart | Expected a multipart file upload. |
open | 400 | Tidak ada file, atau file kosong | No file uploaded. |
open | 400 | Apa pun selain .pdf atau .docx | Signing supports PDF and Word (.docx) files only. |
open | 413 | Unggahan melebihi MaxUploadMb | File is too large. |
run | 400 | Badan tidak valid JSON, atau kosong | Malformed request. / Empty request. |
run | 400 | Token hilang atau bukan GUID | Invalid token. |
run | 404 | Unggahan kedaluwarsa atau tidak pernah dibuka | Upload expired — please re-open the file. |
run | 400 | Tidak ada tanda tangan, atau tidak ada penempatan | No signature supplied. / No placement supplied. |
run | 400 | Muatan bukan base64, kosong, terlalu besar, atau bukan 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 | Penempatan berada di luar halaman | The signature or its placement is invalid. |
run | 400 | Mode bersertifikat, lisensi berbayar dan tidak ada sertifikat | No signing certificate configured. |
run | 400 | Mode bersertifikat dengan sertifikat di luar jendela validitasnya | The signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd. |
open, run | 500 | Pemrosesan gagal | Pesan yang disanitasi |
download | 400 | Token hilang atau bukan GUID | hanya status |
download | 404 | Token tidak dikenal atau kedaluwarsa | hanya status |
Siklus lengkap dengan fetch:
// file: File yang akan ditandatangani; pngBase64: tanda tangan sebagai PNG base64 mentah, tanpa awalan data:
// misalnya canvas.toDataURL('image/png').split(',')[1].
async function signFile(file, pngBase64) {
const base = '/doconut';
// 1. open: unggah file
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: tandatangani
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: ambil file yang telah ditandatangani
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);
}Endpoint bersifat same-origin: versi ini tidak mendukung CORS. Layani UI Anda dan skrip widget dari origin yang sama dengan Doconut, atau reverse-proxy kedua jalur /doconut (jalur middleware dan jalur sumber daya) di bawah origin UI Anda.
Dalam produksi
-
Pasang plugin di samping paket inti, dengan versi yang sama:
dotnet add package Doconut.NET8.Signer. -
Tambahkan file lisensi. Letakkan
Doconut.Viewer.Signer.licdi folder yang sama denganDoconut.Viewer.lic. -
Dapatkan sertifikat Anda sebagai PFX dengan kunci pribadi dan rantai penerbitnya, dari otoritas sertifikat atau PKI milik organisasi Anda. Untuk mencoba terlebih dahulu, gunakan lisensi demo (sertifikat demo bawaan, berwatermark) atau PFX yang ditandatangani sendiri.
-
Baca sertifikat dari konfigurasi, sehingga mengubahnya tidak pernah memerlukan perubahan kode:
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"] ?? "", }); });Simpan
.pfxdi luarwwwroot, dan simpan kata sandi di luarappsettings.json: rahasia pengguna dalam pengembangan (dotnet user-secrets set "DoconutSigner:Password" "<password>"), variabel lingkungan (DoconutSigner__Password) atau brankas dalam produksi. -
Periksa log startup. Seharusnya menampilkan
using certificate '{subject}' (valid until …). Signatures are digitally sealed.. Sebuah Peringatan berarti sertifikat telah kedaluwarsa, belum berlaku, atau tidak dikeluarkan untuk penandatanganan dokumen.
Percaya pada pembaca PDF. Sebuah pembaca menampilkan tanda tangan sebagai valid ketika ia mempercayai akar sertifikat. Dengan PKI organisasi Anda, hal ini berlaku pada setiap mesin yang mempercayai akar Anda, yang biasanya semua mesin di dalam organisasi. Sertifikat yang dipercaya Adobe pada mesin mana pun (Adobe Approved Trust List) adalah, sejauh yang kami tahu, dikeluarkan dengan kunci pribadi pada token perangkat keras atau HSM, yang tidak dapat digunakan oleh plugin ini: ia hanya menandatangani dari PFX. Konfirmasikan dengan penyedia sertifikat Anda sebelum mengandalkan jenis kepercayaan tersebut.
Ladang web
Widget menyimpan setiap unggahan dan hasilnya di memori pada node yang melayani open. Di belakang load balancer tanpa sesi lengket, permintaan run, download, atau pratinjau berikutnya dapat mencapai node lain dan tidak menemukan unggahan. Daftarkan penyimpanan widget terenkripsi bersama sekali, setelah AddDoconut():
byte[] farmKey = Convert.FromBase64String(builder.Configuration["Doconut:FarmKey"]);
builder.Services.AddDoconutDistributedWidgets(store =>
{
store.RootPath = @"\\fileshare\doconut"; // sebuah folder yang dapat dibaca dan ditulis oleh setiap node
store.FarmKey = farmKey; // setidaknya 32 byte, identik pada setiap node
// store.Ttl = TimeSpan.FromMinutes(30); // berapa lama unggahan disimpan (default)
});- Sebuah server tunggal tidak memerlukan apa pun: tanpa panggilan ini penyimpanan dalam memori digunakan.
- Unggahan dan hasil dienkripsi saat disimpan pada share (AES-256, encrypt-then-MAC), dan setiap file terikat pada tokennya, sehingga satu token tidak pernah dapat membaca file token lain.
FarmKeyharus setidaknya 32 byte dan sama pada setiap node. Muat dari penyimpanan rahasia; jangan pernah menuliskannya secara keras. Pendaftaran melemparArgumentExceptionketikaRootPathtidak ada atauFarmKeylebih pendek dari 32 byte.- Arahkan
RootPathke lokasi bersama yang sama yang digunakan oleh penampil terdistribusi, dan berikan setiap node sertifikat penandatangan yang sama.
Referensi API
Facade dan opsi widget berada di namespace Doconut; tipe permintaan dan hasil berada di Doconut.Core.Models.Signing. SignerPlugin berada di Doconut.Plugins.Signer.
DocumentSigner
public sealed class DocumentSigner
{
public Task<SignResult> SignAsync(
Stream source, string sourceExtension, SignRequest request,
SigningCertificate? cert = null, CancellationToken ct = default);
}Di-resolve melalui dependency injection; konstruktor bersifat internal. sourceExtension adalah ".pdf" atau ".docx". Dengan lisensi berbayar cert digunakan dan output bersih; dengan lisensi sementara sertifikat demo bawaan digunakan, cert diabaikan, dan output berwatermark.
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
}Satu tanda tangan terlihat ditempatkan sekali, plus metadata penandatangan opsional.
VisibleSignature and SignatureKind
public sealed record VisibleSignature(SignatureKind Kind, byte[] PngBytes)
{
public bool IsValid { get; } // PngBytes tidak kosong
}
public enum SignatureKind { Drawn, Typed, Image }PngBytes adalah PNG untuk setiap jenis. Tanda tangan yang digambar atau diketik bersifat transparan; gambar yang diunggah mempertahankan transparansi yang dimilikinya, sehingga JPG yang tidak transparan tetap tidak transparan. Kind hanya merupakan petunjuk.
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 berbasis 1; X, Y, W, dan H adalah 0..1 yang dinormalisasi dari sudut kiri atas.
SignatureMode and WordOutput
public enum SignatureMode { Certified, Visual } // Certified adalah default
public enum WordOutput { Pdf, Docx } // Pdf adalah default; diabaikan untuk sumber PDFSignResult
public sealed record SignResult(Stream Stream, string Extension);Dokumen yang ditandatangani sebagai aliran yang dapat di-seek, dan ekstensi-nya dengan titik (".pdf" atau ".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 tidak kosong, atau PfxPath tidak kosong
}Setel salah satu PfxBytes atau 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; }
}Setel melalui DoconutOptions.AddSignerWidget(Action<SignerWidgetOptions>? configure = null), yang mengembalikan DoconutOptions sehingga pemanggilan dapat dirantai. SigningCertificate null berarti sertifikat demo pada lisensi sementara, dan tanda tangan Visual hanya pada lisensi berbayar.
Pemecahan Masalah
| Gejala | Penyebab | Perbaikan |
|---|---|---|
AddDoconut() melempar The Signer plugin is registered via AddPlugin but no active license grants Signer. | Tidak ada lisensi, file TRIAL, lisensi tanpa Signer, atau lisensi berbayar di luar jendela versinya | Pasang lisensi yang memberikan Signer, atau hapus AddPlugin<SignerPlugin>() |
AddDoconut() melempar AddSignerWidget() was called but the Signer plugin is not registered. | Widget diaktifkan tanpa plugin-nya | Tambahkan options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>() |
AddDoconut() melempar Doconut Signer: the certificate file was not found at '{path}'. | PfxPath menunjuk ke file yang hilang | Perbaiki jalur; tempatkan file di lokasi yang dapat dibaca oleh akun aplikasi |
AddDoconut() melempar Doconut Signer: the signing certificate could not be opened — the password is incorrect or the file is not a valid .pfx. | Password salah, atau bukan file PKCS#12 | Periksa password; gunakan .pfx yang sebenarnya |
AddDoconut() melempar Doconut Signer: the signing certificate has no private key. Re-export the .pfx INCLUDING the private key. | PFX diekspor tanpa kunci privatnya | Ekspor kembali dengan kunci privat |
Menyelesaikan DocumentSigner melempar No IDocumentSigner is registered. | SignerPlugin tidak terdaftar | Tambahkan AddPlugin<SignerPlugin>() di dalam AddDoconut() |
| Output berwatermark | Lisensi bersifat sementara (Demo/NFR) | Gunakan lisensi berbayar yang memberikan Signer |
run menjawab 400 No signing certificate configured. | Lisensi berbayar, mode Certified, dan tidak ada sertifikat | Konfigurasikan SigningCertificate, atau tanda tangani dalam mode Visual |
run menjawab 400 The signing certificate expired on yyyy-MM-dd. | Sertifikat sudah kedaluwarsa | Ganti; tanda tangan Visual tetap berfungsi sementara |
| Log mengatakan output "menggunakan sertifikat demo bawaan", namun lisensi berbayar menolak tanda tangan Certified | Baris itu ditulis setiap kali tidak ada sertifikat yang dikonfigurasi, terlepas dari lisensi | Konfigurasikan SigningCertificate |
Widget dimuat tetapi mengatakan Signing is not enabled on this server. | AddSignerWidget() tidak dipanggil, atau basePath tidak cocok dengan tempat UseDoconut() dipasang | Panggil AddSignerWidget(); perbaiki basePath |
run menjawab 400 The signature image must be a PNG., Signature image is not valid base64. atau Signature image is too large. | UI khusus mengirim URL data:, JPG, atau lebih dari MaxSignatureImageKb | Kirim PNG base64 mentah dalam batas |
open menjawab 413 File is too large. | Unggahan melebihi MaxUploadMb | Tingkatkan MaxUploadMb di AddSignerWidget; maxUploadMb widget hanya pemeriksaan sisi klien |
run atau download menjawab 404 Upload expired — please re-open the file. | Jendela 30 menit telah berlalu, atau node web-farm tidak memiliki unggahan | Buka file lagi; di farm, daftarkan AddDoconutDistributedWidgets |
.docx yang ditandatangani tidak menampilkan tanda tangan di beberapa penampil | Output Word membawa tanda tangan paket OOXML, yang banyak penampil tidak menampilkan | Tandatangani ke PDF, defaultnya |
| Pembaca PDF mengatakan identitas penandatangan tidak dikenal | Pembaca tidak mempercayai root sertifikat (sertifikat demo tidak pernah dipercaya) | Gunakan sertifikat dari root yang dipercaya pembaca Anda |
| Widget gagal ketika UI berada pada origin lain | Endpoint tidak mendukung CORS | Layani UI dari origin yang sama, atau reverse-proxy jalur Doconut |
| Tema tidak diterapkan | Selector menargetkan elemen di dalam mount | Target mount itu sendiri: #host.dsw atau #host |
Apakah halaman ini membantu?