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.

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

bash
dotnet add package Doconut.NET8.Signer

Untuk mengunci plugin ke rilis yang dijelaskan dalam dokumentasi ini, berikan versi secara terpisah:

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

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

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

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

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

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.

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 lisensiMulaiTanda tangan bersertifikatTanda tangan visual
Lisensi berbayar yang memberikan Signer, sertifikat dikonfigurasiMulaiDitutup dengan sertifikat Anda, bersih (watermarked: false)Bersih
Lisensi berbayar yang memberikan Signer, tanpa sertifikatMulaiRefused: No signing certificate configured.Bersih
Lisensi berbayar, sertifikat kedaluwarsa atau belum validMulai (dengan widget diaktifkan, peringatan dicatat)Refused: The signing certificate expired on yyyy-MM-dd.Bersih
Lisensi Demo/NFR sementara, aktif atau kedaluwarsaMulaiDitutup 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 versinyaAddDoconut() 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>().

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

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

Sumber Word ditandatangani menjadi PDF kecuali Anda meminta output Word. Beri nama hasil dari 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 melempar alih‑alih mengembalikan ketika panggilan tidak dapat berhasil:

PengecualianPesanKapan
InvalidOperationExceptionNo signing certificate configured.Mode Certified, lisensi berbayar, dan tidak ada sertifikat yang diberikan
InvalidOperationExceptionThe 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
ArgumentExceptionThe 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
NotSupportedExceptionThe 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.

ModeApa yang dihasilkanSertifikatDapat diverifikasi
SignatureMode.Certified (bawaan)Tanda tangan yang terlihat plus segel digitalDiperlukan dengan lisensi berbayarYa
SignatureMode.VisualHanya tanda tangan yang terlihatTidak pernah diperlukanTidak: 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.

OutputApa yang terjadiDukungan verifikator
WordOutput.Pdf (default)Dokumen dikonversi ke PDF, lalu ditandatangani dan disegelLuas: PDF yang ditandatangani dapat diverifikasi di mana saja
WordOutput.DocxDokumen tetap dalam format Word: gambar tanda tangan ditempatkan di dalamnya, plus tanda tangan paket OOXMLTerbatas: 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:

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

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:

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

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

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

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.

Dan Informasi ketika tidak ada sertifikat yang dikonfigurasi:

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.

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:

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

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.

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:

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

OpsiTipeBawaanCatatan
basePathstring'/doconut'Di mana endpoint ?sign= dan gambar pratinjau disajikan
resPathstring'/doconut-res'Cadangan; widget menyertakan CSS‑nya sendiri
maxUploadMbnumber25Hanya pemeriksaan sisi klien, sehingga file yang terlalu besar gagal cepat. Batas server adalah MaxUploadMb dalam AddSignerWidget
maxSignatureKbnumber512Batas sisi klien untuk mode Gambar. Jaga agar sama dengan MaxSignatureImageKb server
previewWidthnumber560Lebar piksel pratinjau halaman
licenseUrlstring | nullnullMengubah pemberitahuan demo-watermark menjadi tautan ke URL ini
signatureModestring'certified'Tipe tanda tangan awal: 'certified' atau 'visual'. Nilai lain menjadi 'certified'
showSignatureModeTogglebooleantrueMenampilkan pilihan Digital signature / Visual only. Dengan false, widget menandatangani dengan signatureMode
wordOutputstring'pdf'Output awal untuk sumber .docx: 'pdf' atau 'docx'. Nilai lain menjadi 'pdf'
showOutputFormatTogglebooleantrueMenampilkan pilihan PDF / Word, hanya untuk sumber .docx. Dengan false, widget menggunakan wordOutput
labelsobject{}Menimpa subset apa pun dari string bahasa Inggris

Menyembunyikan toggle tidak menonaktifkan fitur; itu menetapkan nilai. Dua konfigurasi umum:

javascript
// Kedua saklar ditampilkan, tanda tangan digital secara default: penandatangan layanan mandiri penuh.
Doconut.signer('#host', { basePath: '/doconut', licenseUrl: '/pricing' });
javascript
// Hanya visual, tanpa saklar: stempel sederhana tanpa tanda tangan digital yang ditawarkan.
Doconut.signer('#host', {
  basePath: '/doconut',
  signatureMode: 'visual',
  showSignatureModeToggle: false
});

Panggilan balik

Panggilan balikTerpicu ketikaMuatan
onReadySekali, saat mount (tidak lagi pada reset())—
onSourceLoadedFile dibuka dan pratinjau ditampilkan{ file: { token, name, pages, ext } }
onSignedPenandatanganan berhasil{ downloadToken, downloadName, watermarked }
onDownloadSetiap kali klik Download{ downloadName, downloadToken }
onErrorLangkah 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

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

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'.

KunciDefault bahasa Inggris
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

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:

css
#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.

RuteTujuanRespons sukses
POST ?sign=open (multipart, satu file)Unggah PDF atau .docx dan buka untuk pratinjau200 — { token, name, pages, ext }
POST ?sign=run (badan JSON)Tandatangani file yang diunggah200 — { downloadToken, downloadName, watermarked }
GET ?sign=download&token=<downloadToken>Alirkan file yang ditandatangani200 — 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:

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"
}
BidangCatatan
tokenToken dari open
signature.kindDrawn, Typed atau Image, tidak sensitif huruf; apa pun yang lain menjadi Drawn. Hanya petunjuk: muatan selalu PNG
signature.payloadPNG base64 mentah, tanpa awalan data:. Harus berupa PNG asli dan tidak lebih besar dari MaxSignatureImageKb setelah didekode
placement.pageBerbasis 1
placement.x / y / w / h0..1 yang dinormalisasi dari sudut kiri atas, dengan x + w ≤ 1 dan y + h ≤ 1
meta.signerName / reason / locationOpsional. Setiap nilai dipangkas, nilai kosong diabaikan, dan setiap dipotong pada 256 karakter
wordOutputpdf (default) atau docx; diabaikan untuk sumber PDF. Apa pun yang lain menjadi pdf
modecertified (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.

RuteStatusKapanBadan
any404Widget tidak diaktifkanhanya status
any405Verba salah (open dan run membutuhkan POST, download membutuhkan GET)hanya status
open400Bukan unggahan multipartExpected a multipart file upload.
open400Tidak ada file, atau file kosongNo file uploaded.
open400Apa pun selain .pdf atau .docxSigning supports PDF and Word (.docx) files only.
open413Unggahan melebihi MaxUploadMbFile is too large.
run400Badan tidak valid JSON, atau kosongMalformed request. / Empty request.
run400Token hilang atau bukan GUIDInvalid token.
run404Unggahan kedaluwarsa atau tidak pernah dibukaUpload expired — please re-open the file.
run400Tidak ada tanda tangan, atau tidak ada penempatanNo signature supplied. / No placement supplied.
run400Muatan bukan base64, kosong, terlalu besar, atau bukan PNGSignature image is not valid base64. / Signature image is empty. / Signature image is too large. / The signature image must be a PNG.
run400Penempatan berada di luar halamanThe signature or its placement is invalid.
run400Mode bersertifikat, lisensi berbayar dan tidak ada sertifikatNo signing certificate configured.
run400Mode bersertifikat dengan sertifikat di luar jendela validitasnyaThe signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd.
open, run500Pemrosesan gagalPesan yang disanitasi
download400Token hilang atau bukan GUIDhanya status
download404Token tidak dikenal atau kedaluwarsahanya status

Siklus lengkap dengan fetch:

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

  1. Pasang plugin di samping paket inti, dengan versi yang sama: dotnet add package Doconut.NET8.Signer.

  2. Tambahkan file lisensi. Letakkan Doconut.Viewer.Signer.lic di folder yang sama dengan Doconut.Viewer.lic.

  3. 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.

  4. Baca sertifikat dari konfigurasi, sehingga mengubahnya tidak pernah memerlukan perubahan kode:

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

    Simpan .pfx di luar wwwroot, dan simpan kata sandi di luar appsettings.json: rahasia pengguna dalam pengembangan (dotnet user-secrets set "DoconutSigner:Password" "<password>"), variabel lingkungan (DoconutSigner__Password) atau brankas dalam produksi.

  5. 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():

csharp
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.
  • FarmKey harus setidaknya 32 byte dan sama pada setiap node. Muat dari penyimpanan rahasia; jangan pernah menuliskannya secara keras. Pendaftaran melempar ArgumentException ketika RootPath tidak ada atau FarmKey lebih pendek dari 32 byte.
  • Arahkan RootPath ke 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

csharp
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

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
}

Satu tanda tangan terlihat ditempatkan sekali, plus metadata penandatangan opsional.

VisibleSignature and SignatureKind

csharp
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

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 berbasis 1; X, Y, W, dan H adalah 0..1 yang dinormalisasi dari sudut kiri atas.

SignatureMode and WordOutput

csharp
public enum SignatureMode { Certified, Visual }   // Certified adalah default
public enum WordOutput { Pdf, Docx }              // Pdf adalah default; diabaikan untuk sumber PDF

SignResult

csharp
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

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 tidak kosong, atau PfxPath tidak kosong
}

Setel salah satu PfxBytes atau 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; }
}

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

GejalaPenyebabPerbaikan
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 versinyaPasang lisensi yang memberikan Signer, atau hapus AddPlugin<SignerPlugin>()
AddDoconut() melempar AddSignerWidget() was called but the Signer plugin is not registered.Widget diaktifkan tanpa plugin-nyaTambahkan options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>()
AddDoconut() melempar Doconut Signer: the certificate file was not found at '{path}'.PfxPath menunjuk ke file yang hilangPerbaiki 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#12Periksa 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 privatnyaEkspor kembali dengan kunci privat
Menyelesaikan DocumentSigner melempar No IDocumentSigner is registered.SignerPlugin tidak terdaftarTambahkan AddPlugin<SignerPlugin>() di dalam AddDoconut()
Output berwatermarkLisensi bersifat sementara (Demo/NFR)Gunakan lisensi berbayar yang memberikan Signer
run menjawab 400 No signing certificate configured.Lisensi berbayar, mode Certified, dan tidak ada sertifikatKonfigurasikan SigningCertificate, atau tanda tangani dalam mode Visual
run menjawab 400 The signing certificate expired on yyyy-MM-dd.Sertifikat sudah kedaluwarsaGanti; tanda tangan Visual tetap berfungsi sementara
Log mengatakan output "menggunakan sertifikat demo bawaan", namun lisensi berbayar menolak tanda tangan CertifiedBaris itu ditulis setiap kali tidak ada sertifikat yang dikonfigurasi, terlepas dari lisensiKonfigurasikan SigningCertificate
Widget dimuat tetapi mengatakan Signing is not enabled on this server.AddSignerWidget() tidak dipanggil, atau basePath tidak cocok dengan tempat UseDoconut() dipasangPanggil 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 MaxSignatureImageKbKirim PNG base64 mentah dalam batas
open menjawab 413 File is too large.Unggahan melebihi MaxUploadMbTingkatkan 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 unggahanBuka file lagi; di farm, daftarkan AddDoconutDistributedWidgets
.docx yang ditandatangani tidak menampilkan tanda tangan di beberapa penampilOutput Word membawa tanda tangan paket OOXML, yang banyak penampil tidak menampilkanTandatangani ke PDF, defaultnya
Pembaca PDF mengatakan identitas penandatangan tidak dikenalPembaca tidak mempercayai root sertifikat (sertifikat demo tidak pernah dipercaya)Gunakan sertifikat dari root yang dipercaya pembaca Anda
Widget gagal ketika UI berada pada origin lainEndpoint tidak mendukung CORSLayani UI dari origin yang sama, atau reverse-proxy jalur Doconut
Tema tidak diterapkanSelector menargetkan elemen di dalam mountTarget mount itu sendiri: #host.dsw atau #host

Apakah halaman ini membantu?