Plugin Penandatangan
Tandatangani dokumen PDF dan Word dengan tanda tangan terlihat dan 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.
| Permukaan | Gunakan ketika |
|---|---|
DocumentSigner (C#) | Anda menandatangani di server, tanpa melibatkan browser |
Drop-in widget (doconutSigner.js) | Anda menginginkan layar unggah, tanda tangan, dan unduh yang siap pakai di halaman Anda |
HTTP endpoints on DocImage.axd (?sign=open|run|download) | Anda membangun UI penandatanganan Anda sendiri terhadap kontrak server yang terdokumentasi |
Setiap tanda tangan ditempatkan sekali, pada satu halaman. Nama penandatangan, alasan, dan lokasi dapat menyertainya.
Pasang paket
Install-Package Doconut.NETFramework.SignerUntuk menambatkan plugin ke rilis yang dijelaskan dalam dokumentasi ini:
Install-Package Doconut.NETFramework.Signer -Version 26.10.0Pertahankan paket Signer pada versi yang sama dengan Doconut.NETFramework.
File lisensi plugin, Doconut.Viewer.Signer.lic, diletakkan di folder yang sama dengan Doconut.Viewer.lic; file ini dibaca bersama lisensi penampil.
Daftarkan plugin
Seperti setiap plugin Doconut, Signer mendaftar dengan AddPlugin<TPlugin>() di DoconutHost.Initialize, dipanggil dari Application_Start:
Doconut.DoconutHost.Initialize(options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
});Tambahkan Doconut.DoconutHost.Shutdown() ke Application_End agar pekerjaan latar belakang berhenti bersih saat kolam aplikasi didaur ulang.
Itu semua yang dibutuhkan oleh fasad C#. Widget dan endpoint HTTP-nya adalah opsi terpisah, AddSignerWidget() (lihat Widget Drop-in).
Plugin memerlukan lisensi yang memberikan kemampuan Signer. Tanpa itu, DoconutHost.Initialize melempar dari Application_Start:
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.Di System.Web itu berarti setiap permintaan menjawab 500 kosong, dan alasannya hanya ada di log peristiwa Windows (sumber ASP.NET). Ia melempar 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.
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 | 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) | Berwatermark |
Tidak ada lisensi, file legacy TRIAL, lisensi tanpa Signer, atau lisensi berbayar di luar jendela versinya | Application_Start melempar; setiap permintaan menjawab 500 kosong | — | — |
Aturannya sama untuk fasad C# dan widget: output 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 konfigurasikan tidak digunakan.
Sertifikat demo menghasilkan segel asli, tetapi pembaca PDF tidak mempercayainya. Integrasi dapat dibangun dan diuji secara menyeluruh dengan lisensi evaluasi; untuk mendapatkan output yang bersih dan terpercaya Anda memerlukan lisensi berbayar serta sertifikat penandatanganan Anda sendiri.
Gunakan dari C#
DocumentSigner terdaftar oleh DoconutHost.Initialize; selesaikan dari DoconutHost.Services. Konstruktornya internal, jadi jangan pernah new itu. Menyelesaikannya tanpa AddPlugin<SignerPlugin>() 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, 81920, ct);
return output.ToArray();
}
}
}SignAsync mengambil aliran sumber, ekstensi‑nya (".pdf" atau ".docx"), permintaan, dan sertifikat untuk panggilan ini. Fasad 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 tersebut: dispose itu ketika selesai.
Di dalam kontroler MVC 5
Buat aksi menjadi asinkron dan await tanda tangan. Yang ini menambahkan cap Visual, yang tidak memerlukan sertifikat:
[HttpPost]
public async Task<ActionResult> Sign(HttpPostedFileBase file)
{
var signer = Doconut.DoconutHost.Services.GetRequiredService<DocumentSigner>();
byte[] signaturePng = System.IO.File.ReadAllBytes(Server.MapPath("~/App_Data/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(
file.InputStream, Path.GetExtension(file.FileName), request, ct: Response.ClientDisconnectedToken);
string contentType = result.Extension == ".pdf"
? "application/pdf"
: "application/vnd.openxmlformats-officedocument.wordprocessingml.document";
return File(result.Stream, contentType, Path.GetFileNameWithoutExtension(file.FileName) + "-signed" + result.Extension);
}Sumber Word ditandatangani menjadi PDF kecuali Anda meminta output Word. Beri nama hasil dari result.Extension:
var signer = Doconut.DoconutHost.Services.GetRequiredService<DocumentSigner>();
byte[] signaturePng = File.ReadAllBytes(HostingEnvironment.MapPath("~/App_Data/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 bersertifikat, 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 bersertifikat dengan sertifikat di luar jendela masa berlakunya |
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 (default) | 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 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 ada di PFX Anda, sehingga pembaca yang mempercayai root Anda dapat membangun rantai. Segel asli Word adalah tanda tangan paket OOXML dan hanya membawa sertifikat penandatangan.
Dokumen Word
Untuk sumber .docx, SignRequest.WordOutput memilih output. Ini diabaikan untuk sumber PDF, yang selalu menghasilkan PDF.
| Output | Apa yang terjadi | Dukungan Verifier |
|---|---|---|
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 verifier yang terbatas.
Pengaturan Sertifikat
Untuk menyegel dengan identitas Anda sendiri, berikan plugin file PFX (PKCS#12) yang mencakup kunci pribadi. Untuk widget, atur SignerWidgetOptions.SigningCertificate; untuk facade C#, berikan sertifikat ke SignAsync. Sediakan berupa byte atau jalur, plus kata sandi. App_Data adalah tempat yang baik untuk file tersebut, karena IIS tidak pernah menyajikannya:
Doconut.DoconutHost.Initialize(options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
options.AddSignerWidget(widget =>
{
widget.SigningCertificate = new SigningCertificate
{
PfxBytes = File.ReadAllBytes(HostingEnvironment.MapPath("~/App_Data/signing.pfx")),
Password = System.Configuration.ConfigurationManager.AppSettings["DoconutSigner:Password"] ?? "",
};
});
});Doconut.DoconutHost.Initialize(options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
options.AddSignerWidget(widget =>
{
widget.SigningCertificate = new SigningCertificate
{
PfxPath = HostingEnvironment.MapPath("~/App_Data/signing.pfx"),
Password = System.Configuration.ConfigurationManager.AppSettings["DoconutSigner:Password"] ?? "",
};
});
});Properti SigningCertificate bersifat init-only, yang tidak dapat diatur oleh C# 7.3 (default untuk proyek .NET Framework). Atur <LangVersion> ke 9.0 atau yang lebih baru dalam file proyek.
Sertifikat hanya disimpan di memori. Tidak pernah dicatat, dikembalikan ke klien, atau disimpan secara permanen, dan kata sandi tidak pernah muncul dalam pesan error.
Persyaratan:
- Sebuah bundel PFX / PKCS#12 dengan kunci pribadi. File hanya kunci publik (
.cer,.crt) tidak dapat menandatangani. Ekspor rantai penerbit bersamanya, sehingga segel PDF dapat membawanya. - Kata sandi yang benar.
- Di dalam jangka waktu berlaku sertifikat. Sertifikat yang kedaluwarsa atau belum berlaku tidak menghentikan aplikasi, tetapi tanda tangan Certified ditolak sampai 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 pembaca PDF menandai tanda tangan tersebut.
- Token perangkat keras, smart card, HSM, dan penyimpanan sertifikat Windows tidak didukung. Ekspor sertifikat, beserta kunci pribadi dan rantainya, ke PFX.
Buat PFX dari sertifikat dan kunci pribadinya 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 pribadi ada). Klik kanan, pilih Semua Tugas → Ekspor…, pilih Ya, ekspor kunci pribadi, pilih Pertukaran Informasi Pribadi – PKCS #12 (.PFX), dan atur kata sandi.
Pemeriksaan Startup
Ketika widget diaktifkan, sertifikat di SignerWidgetOptions.SigningCertificate diperiksa sekali, di dalam DoconutHost.Initialize, sehingga PFX yang salah konfigurasi gagal pada saat startup bukan pada tanda tangan pertama. Tiga masalah melempar InvalidOperationException dari Application_Start, dan setiap permintaan kemudian menjawab 500 kosong; pesan berada di log peristiwa Windows:
| Pesan | Perbaikan |
|---|---|
Doconut Signer: the certificate file was not found at '{path}'. | Perbaiki PfxPath; pastikan file dideploy dan dapat dibaca oleh akun app pool |
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 pribadi |
Pada ASP.NET Core host juga mencatat satu baris saat startup yang menyebutkan sertifikat, atau memperingatkan bahwa sertifikat telah kedaluwarsa atau tidak dikeluarkan untuk penandatanganan. DoconutHost tidak menulis baris itu, jadi pada .NET Framework periksa sertifikat baru dengan menandatangani dokumen uji dalam mode Certified.
Facade C# tidak diperiksa saat startup. Sertifikat yang Anda berikan ke SignAsync dibaca saat Anda menandatangani, sehingga jalur atau kata sandi yang salah menyebabkan panggilan itu gagal.
Widget Drop-in
Aktifkan endpoint
Endpoint ?sign=open|run|download widget disajikan oleh DocImage.axd dan dinonaktifkan secara default. Aktifkan mereka di samping pendaftaran plugin:
Doconut.DoconutHost.Initialize(options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
options.AddSignerWidget(widget =>
{
widget.MaxUploadMb = 25; // bawaan
widget.MaxSignatureImageKb = 512; // bawaan
// widget.SigningCertificate: lihat pengaturan Sertifikat; biarkan null untuk penandatanganan demo (berwatermark)
});
});
// System.Web membaca seluruh unggahan sebelum Doconut melihatnya: pertahankan maxRequestLength (KB) dan
// maxAllowedContentLength (bytes) di Web.config di atas MaxUploadMb widget.AddSignerWidget() tanpa argumen mengaktifkan widget dengan nilai default. Itu tidak memberikan penandatanganan sendiri: ia membutuhkan AddPlugin<SignerPlugin>(), atau DoconutHost.Initialize 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.Endpoint dan skrip disajikan oleh handler dan modul yang terdaftar di Web.config:
<system.webServer>
<handlers>
<add name="DocImage" verb="GET,HEAD,POST" path="DocImage.axd" type="Doconut.DocImageHandler, Doconut" />
</handlers>
<modules>
<add name="DoconutResources" type="Doconut.DoconutResourceModule, Doconut" />
</modules>
</system.webServer>Modul menyajikan skrip terlepas dari apakah widget diaktifkan atau tidak. Tanpa AddSignerWidget(), widget memuat dan menggambar zona drop-nya, dan permintaan pertamanya menjawab 404: widget kemudian melaporkan Signing is not enabled on this server.
Batas Unggah
ASP.NET membaca seluruh badan permintaan sebelum DocImage.axd dijalankan. Unggahan di atas MaxUploadMb tetapi di bawah batas host menghasilkan JSON 413 milik widget (File is too large.). Unggahan di atas batas host ditolak oleh IIS terlebih dahulu, dengan halaman error yang tidak dapat dibaca widget. Pertahankan kedua batas host di atas batas maksimum widget:
<system.web>
<httpRuntime maxRequestLength="30720" /> <!-- KILOBYTES: 30 MB -->
</system.web>
<system.webServer>
<security>
<requestFiltering>
<requestLimits maxAllowedContentLength="31457280" /> <!-- BYTES: 30 MB -->
</requestFiltering>
</security>
</system.webServer>Unggahan yang dikirim tanpa Content-Length (chunked) yang melebihi batas host juga mendapatkan halaman error IIS; tidak ada solusi untuk kasus tersebut.
Sematkan
Skrip disajikan di /doconut-res/js/doconutSigner.js. Ini adalah file tunggal yang berdiri sendiri tanpa ketergantungan. Arahkan basePath ke penangan:
<div id="host"></div>
<script src="/doconut-res/js/doconutSigner.js"></script>
<script>
const handle = Doconut.signer('#host', { basePath: '/DocImage.axd' });
</script>Doconut.signer(selectorOrElement, options) mengambil selector CSS atau elemen, melempar jika mount tidak ditemukan, dan mengembalikan sebuah handle. basePath default widget, /doconut, adalah endpoint ASP.NET Core; pada paket ini harus '/DocImage.axd'.
Penandatangan mengunggah file PDF atau .docx, membuat tanda tangan (Draw pada kanvas, Type nama dengan font tanda tangan, atau Image dari PNG, JPG, atau GIF), menyeret dan mengubah ukurannya ke halaman, lalu menandatangani dan mengunduh hasilnya. Widget selalu mengirim tanda tangan sebagai PNG; gambar yang diunggah dikonversi di browser menjadi PNG dengan ukuran 520×160.
Opsi
| Opsi | Tipe | Default | Catatan |
|---|---|---|---|
basePath | string | '/doconut' | Di mana endpoint ?sign= dan gambar pratinjau disajikan. Atur '/DocImage.axd' pada paket ini |
resPath | string | '/doconut-res' | Cadangan; widget menyertakan CSS-nya sendiri |
maxUploadMb | number | 25 | Hanya pemeriksaan sisi klien, sehingga file yang terlalu besar gagal dengan cepat. Batas server adalah MaxUploadMb di 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 watermark demo 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 | {} | Mengesampingkan setiap subset dari string bahasa Inggris |
Menyembunyikan toggle tidak menonaktifkan fitur; itu mengunci nilai. Dua konfigurasi umum:
// Kedua toggle ditampilkan, tanda tangan digital secara default: penandatangan layanan mandiri penuh.
Doconut.signer('#host', { basePath: '/DocImage.axd', licenseUrl: '/pricing' });// Hanya visual, tanpa toggle: stempel sederhana tanpa tanda tangan digital yang ditawarkan.
Doconut.signer('#host', {
basePath: '/DocImage.axd',
signatureMode: 'visual',
showSignatureModeToggle: false
});Callback
| Callback | 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 tombol Download diklik | { downloadName, downloadToken } |
onError | Langkah membuka, menandatangani, atau mengunduh gagal, atau file mode Gambar terlalu besar | { message } |
Callback yang melempar akan ditangkap dan dicatat; itu tidak pernah memutus alur widget.
Handle Imperatif
| Metode | Perilaku |
|---|---|
reset() | Kembali ke layar drop dan menghapus alur saat ini. Tidak memicu onReady lagi. Tidak melakukan apa-apa setelah destroy() |
loadFile(file) | Memulai alur dengan 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: '/DocImage.axd',
onSigned: (result) => console.log('signed', result.downloadName, result.watermarked),
onError: (error) => console.warn(error.message)
});
document.getElementById('start-over').addEventListener('click', () => signerWidget.reset());Labels
Setiap string memiliki nilai default bahasa Inggris; labels menggantikan sebagian subset dan sisanya tetap bahasa Inggris. Fragmen yang berubah pada waktu berjalan 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 tambahan mencakup langkah penempatan, layar kesalahan, formulir tertaut dari pemberitahuan demo (demoNoticePrefix, demoNoticeLink, demoNoticeSuffix) dan pengumuman aria-live.
Ketika open atau run menjawab 404 tanpa kesalahan JSON, widget menampilkan signingNotEnabled. Kesalahan JSON dari server selalu diutamakan, sehingga pesan seperti unggahan yang kedaluwarsa tetap terlihat.
Pemberian Tema
Widget menambahkan kelas dsw ke elemen mount-nya dan membaca warna, radius, serta font-nya dari properti khusus CSS, sehingga Anda dapat memberi tema 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, sebuah font UI sistem, dan font tanda tangan bergaya kursif.
Bangun frontend Anda sendiri
Widget ini adalah klien untuk kontrak HTTP ini pada DocImage.axd. Rute-rute menjawab 404 sampai AddSignerWidget() dipanggil. Kesalahan menyertakan badan JSON, { "error": "..." }, kecuali pada tabel yang menyatakan "hanya status". Nilai ?sign= yang tidak dikenal menjawab 400.
| Rute | Tujuan | Respons sukses |
|---|---|---|
POST /DocImage.axd?sign=open (multipart, one file) | Unggah PDF atau .docx dan buka untuk pratinjau | 200 — { token, name, pages, ext } |
POST /DocImage.axd?sign=run (JSON body) | Tandatangani file yang diunggah | 200 — { downloadToken, downloadName, watermarked } |
GET /DocImage.axd?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, /DocImage.axd?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"
}| Kolom | Catatan |
|---|---|
token | Token dari open |
signature.kind | Drawn, Typed atau Image, tidak sensitif huruf; apa pun yang lain menjadi Drawn. Hanya petunjuk: muatan selalu berupa 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 nilai 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 (tetapi tidak melebihi batas IIS) | 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 disaring |
download | 400 | Token hilang atau bukan GUID | hanya status |
download | 404 | Token tidak dikenal atau kedaluwarsa | hanya status |
Siklus lengkap dengan fetch:
// file: File untuk ditandatangani; pngBase64: tanda tangan sebagai PNG base64 mentah, tanpa data: prefix,
// misalnya canvas.toDataURL('image/png').split(',',)[1].
async function signFile(file, pngBase64) {
const base = '/DocImage.axd';
// 1. buka: 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. jalankan: 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. unduh: ambil file yang 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);
}The endpoints are same-origin: versi ini tidak mendukung CORS. Sajikan UI Anda dan skrip widget dari origin yang sama dengan aplikasi, atau reverse-proxy DocImage.axd dan /doconut-res di bawah origin UI Anda.
Dalam produksi
-
Pasang plugin di samping paket inti, pada versi yang sama:
Install-Package Doconut.NETFramework.Signer. -
Tambahkan file lisensi. Letakkan
Doconut.Viewer.Signer.licdi folder yang sama denganDoconut.Viewer.lic. -
Dapatkan sertifikat Anda sebagai PFX dengan kunci privat 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:
xml<appSettings> <add key="DoconutSigner:PfxPath" value="~/App_Data/your-certificate.pfx" /> </appSettings>csharpvar settings = System.Configuration.ConfigurationManager.AppSettings; Doconut.DoconutHost.Initialize(options => { options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic"); options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>(); options.AddSignerWidget(widget => widget.SigningCertificate = new SigningCertificate { PfxPath = HostingEnvironment.MapPath(settings["DoconutSigner:PfxPath"]), Password = settings["DoconutSigner:Password"] ?? "", }); });Simpan
.pfxdiApp_Data, yang tidak pernah disajikan oleh IIS, dan simpan kata sandi di luarWeb.configyang biasa: gunakan bagian konfigurasi terenkripsi, atau penyimpanan rahasia yang dibaca oleh deployment Anda. -
Tandatangani dokumen uji dalam mode Certified. Sertifikat yang kedaluwarsa atau belum berlaku akan ditolak dengan
The signing certificate expired on yyyy-MM-dd.(atauis not valid before), dan pembaca PDF menunjukkan apakah ia mempercayai tanda tangan.
Kepercayaan pada pembaca PDF. 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, diterbitkan dengan kunci privat 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.
Farm web
Widget menyimpan setiap unggahan dan hasilnya di memori pada server yang menyajikan open. Di belakang load balancer tanpa sesi lengket, permintaan run, download, atau pratinjau berikutnya dapat mencapai server lain dan tidak menemukan unggahan. Daftarkan penyimpanan widget terenkripsi bersama melalui argumen kedua dari DoconutHost.Initialize:
byte[] farmKey = Convert.FromBase64String(System.Configuration.ConfigurationManager.AppSettings["Doconut:FarmKey"]);
Doconut.DoconutHost.Initialize(
options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
options.AddSignerWidget();
},
services => services.AddDoconutDistributedWidgets(store =>
{
store.RootPath = @"\\fileshare\doconut"; // sebuah folder yang dapat dibaca dan ditulis oleh setiap server
store.FarmKey = farmKey; // setidaknya 32 byte, identik pada setiap server
// store.Ttl = TimeSpan.FromMinutes(30); // berapa lama unggahan disimpan (default)
}));- Sebuah server tunggal tidak memerlukan apa pun: tanpa pemanggilan ini penyimpanan dalam memori akan 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 server. 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 server 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);
}Dipecahkan dari DoconutHost.Services; konstruktor bersifat internal. sourceExtension adalah ".pdf" atau ".docx". Dengan lisensi berbayar cert digunakan dan outputnya bersih; dengan lisensi sementara sertifikat demo bawaan digunakan, cert diabaikan, dan outputnya diberi watermark.
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 dan 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 tembus pandang tetap tidak tembus pandang. 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 dinormalisasi 0..1 dari sudut kiri atas.
SignatureMode dan WordOutput
public enum SignatureMode { Certified, Visual } // Certified adalah bawaan
public enum WordOutput { Pdf, Docx } // Pdf adalah bawaan; diabaikan untuk sumber PDFSignResult
public sealed record SignResult(Stream Stream, string Extension);Dokumen yang ditandatangani sebagai aliran yang dapat dicari, 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. Setter hanya init: proyek memerlukan C# 9.0 atau lebih baru.
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 di bawah lisensi sementara, dan tanda tangan Visual hanya pada lisensi berbayar.
Pemecahan Masalah
| Gejala | Penyebab | Solusi |
|---|---|---|
Setiap permintaan menjawab 500 kosong setelah menambahkan plugin; log peristiwa menunjukkan 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>() |
Log peristiwa menunjukkan AddSignerWidget() was called but the Signer plugin is not registered. | Widget diaktifkan tanpa plugin-nya | Tambahkan options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>() |
Log peristiwa menunjukkan Doconut Signer: the certificate file was not found at '{path}'. | PfxPath mengarah ke file yang hilang | Perbaiki jalur; tempatkan file di lokasi yang dapat dibaca oleh akun app pool |
Log peristiwa menunjukkan Doconut Signer: the signing certificate could not be opened — the password is incorrect or the file is not a valid .pfx. | Kata sandi salah, atau bukan file PKCS#12 | Periksa kata sandi; gunakan .pfx yang sebenarnya |
Log peristiwa menunjukkan 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 |
new SigningCertificate { … } tidak dapat dikompilasi | Proyek menggunakan C# 7.3, yang tidak dapat mengatur properti init-only | Setel <LangVersion> ke 9.0 atau lebih baru |
Menyelesaikan DocumentSigner melempar No IDocumentSigner is registered. | SignerPlugin tidak terdaftar | Tambahkan AddPlugin<SignerPlugin>() di DoconutHost.Initialize |
| 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 |
Widget dimuat tetapi mengatakan Signing is not enabled on this server. | AddSignerWidget() tidak dipanggil, atau basePath tidak '/DocImage.axd' | Panggil AddSignerWidget(); setel basePath: '/DocImage.axd' |
| Unggahan besar menampilkan halaman error IIS alih-alih pesan widget | maxRequestLength / maxAllowedContentLength berada di bawah MaxUploadMb | Tingkatkan kedua batas host di atas MaxUploadMb |
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 server lain dalam farm tidak memiliki unggahan | Buka file lagi; dalam 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 akar sertifikat (sertifikat demo tidak pernah dipercaya) | Gunakan sertifikat dari akar yang dipercaya pembaca Anda |
| Widget gagal ketika UI berada pada origin lain | Endpoint tidak memiliki dukungan CORS | Layani UI dari origin yang sama, atau reverse-proxy DocImage.axd dan /doconut-res |
| Tema tidak diterapkan | Selector menargetkan elemen di dalam mount | Targetkan mount itu sendiri: #host.dsw atau #host |
Catatan Kerangka
Dibandingkan dengan paket ASP.NET Core, paket ini hanya berbeda dalam hal hosting; API, kontrak endpoint, skrip widget, dan aturan lisensi tetap sama.
- Registrasi ada di
Application_Start, melaluiDoconutHost.Initialize, bukanbuilder.Services.AddDoconut. Layanan sepertiAddDoconutDistributedWidgetsdiletakkan pada argumen keduanya. - Endpoint disajikan oleh
DocImage.axddan skrip olehDoconutResourceModule, keduanya terdaftar diWeb.config, bukanUseDoconut()danUseDoconutResources(). Widget membutuhkanbasePath: '/DocImage.axd'. - Kegagalan startup muncul sebagai
500kosong pada setiap permintaan, dengan alasannya di log peristiwa Windows. - Unggahan dibaca secara lengkap oleh ASP.NET sebelum Doconut melihatnya, sehingga batas IIS harus di atas
MaxUploadMb. - Tidak ada baris log startup tentang sertifikat: tiga kesalahan sertifikat masih dilempar, tetapi baris yang menyebutkan sertifikat tidak ditulis.
- C# 9.0 atau lebih baru diperlukan untuk mengatur properti init‑only
SigningCertificate. - Hanya Windows, seperti sisanya dari paket .NET Framework.
Apakah halaman ini membantu?