Plugin Penandatangan

Tandatangani dokumen PDF dan Word dengan tanda tangan terlihat dan segel digital

Plugin Signer 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
Widget Drop-in (doconutSigner.js)Anda menginginkan layar unggah, tanda tangan, dan unduh yang siap pakai di halaman Anda
Endpoint HTTP (?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.

Instal paket

Instal plugin Signer terbaru yang stabil:

bash
dotnet add package Doconut.NET6.Signer

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

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

Pertahankan paket Signer pada versi yang sama dengan Doconut.NET6. ID paketnya adalah Doconut.NET6.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; ia dibaca bersama dengan lisensi penampil.

Platform. Plugin berjalan di mana pun Doconut.NET6 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, Signer 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 opsi terpisah, AddSignerWidget() (lihat Widget Drop-in).

Plugin memerlukan lisensi yang memberikan kemampuan Signer. Tanpa lisensi, AddDoconut() 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.

Ia melempar kesalahan 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 Penyiapan Lisensi untuk cara memuat lisensi.

Lisensi & watermark

Status lisensiSaat memulaiTanda tangan bersertifikatTanda tangan visual
Lisensi berbayar yang memberikan Signer, sertifikat dikonfigurasiMulaiDitutup dengan sertifikat Anda, bersih (watermarked: false)Bersih
Lisensi berbayar yang memberikan Signer, tanpa sertifikatMulaiDitolak: No signing certificate configured.Bersih
Lisensi berbayar, sertifikat kedaluwarsa atau belum validMulai (dengan widget diaktifkan, Peringatan dicatat)Ditolak: The signing certificate expired on yyyy-MM-dd.Bersih
Lisensi Demo/NFR sementara, aktif atau kedaluwarsaMulaiDitutup dengan sertifikat demo bawaan, diberi watermark (watermarked: true)Berwatermark
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 konfigurasikan 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 terpercaya Anda memerlukan lisensi berbayar serta sertifikat penandatanganan Anda sendiri.

Penggunaan dari C#

DocumentSigner terdaftar oleh AddDoconut() dan di‑resolve dari dependency injection. 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>().

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 + stempel 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. 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: buang it ketika selesai.

Tanda tangan Visual hanya menempelkan 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 bersertifikat, 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 bersertifikat 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 (default)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 diperiksa verifier 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 menyertakan sertifikat penerbit yang ditemukan di PFX Anda, sehingga pembaca yang mempercayai root Anda dapat membangun rantai. Segel native Word adalah tanda tangan paket OOXML dan hanya menyertakan sertifikat penandatangan.

Dokumen Word

Untuk sumber .docx, SignRequest.WordOutput memilih output. Itu diabaikan untuk sumber PDF, yang selalu menghasilkan PDF.

OutputApa yang terjadiDukungan verifikator
WordOutput.Pdf (default)Dokumen dikonversi ke PDF, kemudian 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.

Pengaturan Sertifikat

Untuk menutup 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 di 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 pribadi. 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 autentikasi 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 pribadi dan rantainya, ke dalam PFX.

Buat PFX dari sertifikat dan kunci pribadinya dengan OpenSSL:

bash
openssl pkcs12 -export -out signing.pfx -inkey private.key -in certificate.crt
# Password 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 All Tasks → Export…, pilih Yes, export the private key, pilih Personal Information Exchange – PKCS #12 (.PFX), dan atur kata sandi.

Pemeriksaan Startup

Ketika widget diaktifkan, sertifikat di SignerWidgetOptions.SigningCertificate diperiksa sekali, di dalam AddDoconut(), sehingga PFX yang salah konfigurasi gagal pada saat startup bukan pada tanda tangan pertama. Tiga masalah melempar InvalidOperationException:

PesanPerbaikan
Doconut Signer: the certificate file was not found at '{path}'.Perbaiki 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 pribadi

Jika tidak, host menulis satu baris ke log saat mulai. 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 Anda menandatangani, sehingga jalur atau kata sandi yang salah menyebabkan panggilan tersebut gagal.

Widget Sisip

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;           // nilai default
        widget.MaxSignatureImageKb = 512;  // nilai default
        // widget.SigningCertificate: lihat pengaturan Sertifikat; biarkan null untuk penandatanganan demo (berwatermark)
    });
});

AddSignerWidget() tanpa argumen mengaktifkan widget dengan nilai bawaan. Itu tidak memberikan penandatanganan 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 masih disajikan, sehingga widget memuat dan menggambar zona drop‑nya, lalu melaporkan Signing is not enabled on this server. pada permintaan pertamanya.

Sematkan

UseDoconutResources() menyajikan skrip di {ResourcesPath}/js/doconutSigner.js (bawaan /doconut-res/js/doconutSigner.js). Ini adalah satu file tunggal yang berdiri sendiri 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) menerima selector CSS atau elemen, melempar jika mount tidak ditemukan, dan mengembalikan sebuah handle.

Penandatangan mengunggah file PDF atau file .docx, membuat tanda tangan (Gambar pada kanvas, Ketik nama dengan font tanda tangan, atau Gambar dari PNG, JPG, atau GIF), menyeret dan mengubah ukurannya pada halaman, lalu menandatangani dan mengunduh hasilnya. Widget selalu mengirim tanda tangan sebagai PNG; gambar yang diunggah dikonversi di browser menjadi PNG yang berukuran 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 Tanda tangan digital / Hanya visual. 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 setiap subset 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 lengkap.
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 BalikDipicu 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 }

Panggilan balik yang melempar akan ditangkap dan dicatat; itu tidak pernah menghentikan alur widget.

Penanganan Imperatif

MetodePerilaku
reset()Kembali ke layar drop dan membersihkan 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
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 waktu berjalan 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 tambahan 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. Ketiga rute berada di bawah jalur tempat UseDoconut() dipasang (biasanya /doconut), dan mereka menjawab 404 sampai AddSignerWidget() dipanggil. Kesalahan menyertakan badan JSON, { "error": "..." }, kecuali pada baris tabel yang mengatakan "status only". Nilai ?sign= yang tidak dikenal menjawab 400.

RuteTujuanRespons sukses
POST ?sign=open (multipart, one file)Unggah PDF atau .docx dan buka untuk pratinjau200 — { token, name, pages, ext }
POST ?sign=run (JSON body)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: payload selalu berupa PNG
signature.payloadPNG base64 polos, 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 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 diaktifkanstatus only
any405Verba salah (open dan run membutuhkan POST, download membutuhkan GET)status only
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.
run400Payload 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 masa berlakuThe 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 GUIDstatus only
download404Token tidak dikenal atau kedaluwarsastatus only

Siklus lengkap dengan fetch:

javascript
// file: File yang akan 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 = '/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 sudah 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);
}

Endpointnya 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.NET6.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 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.

  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 vault dalam produksi.

  5. Periksa log startup. Seharusnya menampilkan using certificate '{subject}' (valid until …). Signatures are digitally sealed.. Sebuah Peringatan berarti sertifikat telah kedaluwarsa, belum valid, atau tidak dikeluarkan untuk penandatanganan dokumen.

Percaya pada pembaca PDF. Sebuah pembaca menampilkan tanda tangan sebagai valid ketika 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 dipercayai Adobe pada mesin mana pun (Adobe Approved Trust List) adalah, sejauh yang kami tahu, dikeluarkan dengan kunci privat pada token perangkat keras atau HSM, yang tidak dapat digunakan plugin ini: ia menandatangani hanya dari PFX. Konfirmasikan dengan penyedia sertifikat Anda sebelum mengandalkan jenis kepercayaan tersebut.

Farm web

Widget menyimpan setiap unggahan dan hasilnya di memori pada node yang melayani open. Di belakang load balancer tanpa sesi sticky, 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. Registrasi 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);
}

Diresolusikan 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 opak tetap opak. 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 di bawah 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 versi-nyaPasang 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 mengarah 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, apa pun lisensinyaKonfigurasikan 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 MaxUploadMbNaikkan 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 berakhir, atau node web-farm tidak memiliki unggahanBuka file lagi; di farm, daftarkan AddDoconutDistributedWidgets
Sebuah .docx yang ditandatangani tidak menampilkan tanda tangan di beberapa penampilOutput Word membawa tanda tangan paket OOXML, yang tidak ditampilkan oleh banyak penampilTandatangani ke PDF, default
Pembaca PDF mengatakan identitas penandatangan tidak dikenalPembaca tidak mempercayai akar sertifikat (sertifikat demo tidak pernah dipercaya)Gunakan sertifikat dari akar 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?