İmzalayıcı Eklentisi
PDF ve Word belgelerini görünür bir imza ve dijital mühürle imzalayın
Signer eklentisi bir belgeye görünür bir imza ekler ve varsayılan olarak, bir PDF okuyucusunun doğrulayabileceği dijital bir imza ile mühürler. PDF ve Word (.docx) dosyalarını imzalar. Görünür imza her zaman bir PNG görüntüsüdür: imzalayan tarafından çizilmiş, yazılmış veya yüklenmiş.
| Yöntem | Ne zaman kullanılır |
|---|---|
DocumentSigner (C#) | Sunucuda imzalarsınız, tarayıcı kullanılmaz |
Drop-in widget (doconutSigner.js) | Sayfanızda hazır bir yükleme, imzalama ve indirme ekranı istiyorsunuz |
HTTP endpoints (?sign=open|run|download) | Belgelendirilmiş bir sunucu sözleşmesine karşı kendi imzalama UI'nizi oluşturursunuz |
Her imza bir kez, tek bir sayfaya yerleştirilir. İmzalayanın adı, nedeni ve konumu onunla birlikte taşınabilir.
Paketi kurun
En son kararlı Signer eklentisini kurun:
dotnet add package Doconut.NET6.SignerBu belgenin açıkladığı sürüme eklentiyi sabitlemek için, sürümü ayrı olarak geçirin:
dotnet add package Doconut.NET6.Signer --version 26.10.0Signer paketini Doconut.NET6 ile aynı sürümde tutun. Paket kimliği Doconut.NET6.Signer; .<version> yalnızca indirilen .nupkg dosya adında görünür.
Eklentinin lisans dosyası Doconut.Viewer.Signer.lic, Doconut.Viewer.lic ile aynı klasöre konur; görüntüleyici lisansı ile birlikte okunur.
Platformlar. Eklenti, Doconut.NET6 çalıştığı her yerde çalışır: Windows ve x64 üzerindeki glibc tabanlı Linux (Alpine veya diğer musl tabanlı dağıtımlar değil). Linux'ta, ilk belge açılmadan önce font yapılandırma kütüphanesini kurun:
apt-get update && apt-get install -y libfontconfig1RHEL, Fedora ve benzeri dağıtımlarda paket fontconfig'dır. Olmadan, bir belge açma The system library libfontconfig1 is missing. Install it (Debian/Ubuntu: apt-get install -y libfontconfig1) and see the Linux section of the Doconut documentation. hatasıyla başarısız olur.
Eklentiyi kaydedin
Her Doconut eklentisi gibi, Signer AddDoconut() içinde AddPlugin<TPlugin>() ile kaydolur:
builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
});Bu, C# arayüzünün ihtiyaç duyduğu her şeydir. Widget ve HTTP uç noktaları ayrı bir opt‑in'dir, AddSignerWidget() (bkz. Yerleşik widget).
Eklenti, Signer yeteneğini veren bir lisansa ihtiyaç duyar. Lisans olmadan, AddDoconut() uygulama başlatılırken, isteği hizmet vermeden önce bir hata fırlatır:
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.Lisans olmaması, eski bir TRIAL dosyası, Signer içermeyen bir lisans ve sürüm penceresinin dışındaki bir ücretli lisans için hata fırlatır. Geçici Demo/NFR lisansları kabul edilir. Lisansların nasıl yükleneceği için Lisans Kurulumu bölümüne bakın.
Lisanslama ve filigran
| Lisans durumu | Başlangıç | Sertifikalı imza | Görsel imza |
|---|---|---|---|
Ücretli lisans, Signer verir, sertifika yapılandırıldı | Başlar | Sertifikanızla mühürlenir, temiz (watermarked: false) | Temiz |
Ücretli lisans, Signer verir, sertifika yok | Başlar | Reddedildi: No signing certificate configured. | Temiz |
| Ücretli lisans, sertifika süresi dolmuş veya henüz geçerli değil | Başlar (widget etkinleştirildiğinde, bir Uyarı kaydedilir) | Reddedildi: The signing certificate expired on yyyy-MM-dd. | Temiz |
| Geçici Demo/NFR lisansı, aktif veya süresi dolmuş | Başlar | Dahili demo sertifikasıyla mühürlenir, filigranlı (watermarked: true) | Filigranlı |
Lisans yok, eski bir TRIAL dosyası, Signer içermeyen bir lisans veya sürüm penceresinin dışındaki bir ücretli lisans | AddDoconut() hata verir | — | — |
Kural, C# arayüzü ve widget için aynıdır: lisans ücretli bir görüntüleyici lisansı değilse veya geçiciyse çıktı filigranlı olur. Geçici bir lisans altında eklenti her zaman dahili demo sertifikasıyla imzalar ve yapılandırdığınız herhangi bir sertifika kullanılmaz.
Demo sertifikası gerçek bir mühür üretir, ancak PDF okuyucuları ona güvenmez. Bir entegrasyon, değerlendirme lisansı üzerinde uçtan uca inşa edilebilir ve test edilebilir; temiz, güvenilir bir çıktı elde etmek için hem ücretli bir lisansa hem de kendi imzalama sertifikası ihtiyacınız vardır.
C#'dan Kullanım
DocumentSigner, AddDoconut() tarafından kaydedilir ve bağımlılık enjeksiyonundan çözülür. Yapıcı içtir, bu yüzden asla new etmeyin. AddPlugin<SignerPlugin>() olmadan çözmek No IDocumentSigner is registered. Add the signing plugin: options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>(). fırlatır.
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 defaults to Certified (görünür imza + dijital mühür); WordOutput defaults to 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, kaynak akışı, uzantısını (".pdf" veya ".docx"), isteği ve sertifikayı bu çağrı için alır. Facade, SignerWidgetOptions.SigningCertificate'ı okumaz; bu ayar widget için geçerlidir. Demo lisansı altında veya Görsel modda null gönderin.
SignResult, imzalı belgeyi aranabilir bir akış olarak tutar, ayrıca dosyayı adlandırabilmeniz için Extension (".pdf" veya ".docx") içerir. Akış sizin: işiniz bittiğinde onu serbest bırakın.
Görsel bir imza yalnızca görüntüyü damgalamaktadır ve sertifika gerektirmez:
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);Bir Word kaynağı, Word çıktısı istemediğiniz sürece PDF'ye imzalanır. Sonucu result.Extension'dan adlandırın:
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, çağrı başarılı olamadığında döndürmek yerine fırlatır:
| İstisna | Mesaj | Ne Zaman |
|---|---|---|
InvalidOperationException | No signing certificate configured. | Sertifikalı mod, ücretli lisans ve sertifika gönderilmemiş |
InvalidOperationException | The signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd. | Sertifikalı mod, geçerlilik süresi dışındaki bir sertifika |
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. | Boş PNG baytları veya geçersiz bir yerleştirme |
NotSupportedException | The signer supports PDF and Word (.docx) documents; got '{extension}'. | Diğer tüm kaynak türleri |
İmza modları, Word çıktısı ve sertifikalar
İmza modları
SignRequest.Mode, imzanın mühürlenip mühürlenmeyeceğini seçer.
| Mod | Ne üretir | Sertifika | Doğrulanabilir |
|---|---|---|---|
SignatureMode.Certified (default) | Görünür imza ve dijital mühür | Ücretli lisans altında gereklidir | Evet |
SignatureMode.Visual | Yalnızca görünür imza | Hiç gerekmez | Hayır: bir resimdir |
Certified'i, imzanın kanıtlanabilir olması gerektiğinde kullanın: onaylar, sözleşmeler, doğrulayıcının kimlik ve bütünlüğü kontrol etmesi gereken her şey. Visual'ı, yalnızca imzanın görünümüne ihtiyacınız olduğunda veya sertifikanız olmadığında kullanın. Geçici bir lisans her ikisine de filigran ekler.
PDF mühürleri, SHA-256 ile PKCS#7 ayrık imzalar (adbe.pkcs7.detached) olup RSA veya ECDSA anahtarları için kullanılır. PFX dosyanızda bulunan yayıncı sertifikalarını taşırlar, böylece kökünüzü güvenen bir okuyucu zinciri oluşturabilir. Word‑yerel mühürler OOXML paket imzalarıdır ve yalnızca imzalayanın sertifikasını taşırlar.
Word belgeleri
Bir .docx kaynağı için, SignRequest.WordOutput çıktıyı seçer. PDF kaynakları için yok sayılır; PDF kaynakları her zaman bir PDF üretir.
| Çıktı | Ne olur | Doğrulayıcı desteği |
|---|---|---|
WordOutput.Pdf (varsayılan) | Belge PDF'ye dönüştürülür, ardından imzalanır ve mühürlenir | Geniş: imzalı bir PDF her yerde doğrulanır |
WordOutput.Docx | Belge Word olarak kalır: imza görüntüsü içine yerleştirilir, ayrıca bir OOXML paket imzası eklenir | Sınırlı: her görüntüleyici OOXML paket imzalarını göstermez |
Alıcı düzenlenebilir bir Word dosyasına ihtiyaç duymuyorsa ve sınırlı doğrulayıcı desteğini kabul ediyorsa PDF tutun.
Sertifika kurulumu
Kendi kimliğinizle mühürlemek için, eklentiye özel anahtarı içeren bir PFX (PKCS#12) dosyası verin. Widget için SignerWidgetOptions.SigningCertificate ayarlayın; C# arayüzü için sertifikayı SignAsync'a geçirin. Ya baytları ya da bir yolu, ayrıca şifreyi sağlayın:
builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
options.AddSignerWidget(widget =>
{
widget.SigningCertificate = new SigningCertificate
{
PfxBytes = File.ReadAllBytes("/secure/signing.pfx"),
Password = builder.Configuration["Signing:PfxPassword"],
};
});
});builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
options.AddSignerWidget(widget =>
{
widget.SigningCertificate = new SigningCertificate
{
PfxPath = "/secure/signing.pfx",
Password = builder.Configuration["Signing:PfxPassword"],
};
});
});Sertifika yalnızca bellek içinde tutulur. Asla günlüğe kaydedilmez, bir istemciye geri gönderilmez veya kalıcı olarak saklanmaz ve şifre hiçbir zaman bir günlük satırında ya da hata mesajında görünmez.
Gereksinimler:
- PFX / PKCS#12 paketinin özel anahtarı ile birlikte olması gerekir. Sadece genel anahtar içeren bir dosya (
.cer,.crt) imza atamaz. İhraç zincirini de dışa aktarın, böylece PDF mühürleri onu taşıyabilir. - Doğru şifre.
- Geçerlilik süresi içinde. Süresi dolmuş ya da henüz geçerli olmayan bir sertifika uygulamayı durdurmaz: başlangıçta Uyarı olarak günlüğe kaydedilir ve Sertifikalı imzalar, yerine konulana kadar reddedilir. Görsel imzalar etkilenmez.
- Belge imzalama için verilmiş: digital signature (dijital imza) veya non-repudiation (inkâr edilemezlik) anahtar kullanımı ve varsa, belge imzalama, e-posta koruması veya istemci kimlik doğrulaması sağlayan genişletilmiş anahtar kullanımı. TLS sunucu sertifikası gibi başka bir amaç için verilen bir sertifika yine imza atar, ancak Uyarı olarak günlüğe kaydedilir ve PDF okuyucular imzayı işaretler.
- Donanım tokenları, akıllı kartlar, HSM'ler ve Windows sertifika deposu desteklenmez. Sertifikayı, özel anahtarı ve zinciriyle birlikte bir PFX dosyasına dışa aktarın.
OpenSSL ile bir sertifikadan ve onun özel anahtarından PFX oluşturun:
openssl pkcs12 -export -out signing.pfx -inkey private.key -in certificate.crt
# İstenen dışa aktarma şifresi SigningCertificate.Password'dir.Windows sertifika deposundan bir tane dışa aktarın: certmgr.msc'ı açın ve sertifikayı bulun (özel anahtar mevcut olduğunda simgesi bir anahtar gösterir). Sağ tıklayın, All Tasks → Export… seçeneğini seçin, Yes, export the private key seçeneğini işaretleyin, Personal Information Exchange – PKCS #12 (.PFX) seçin ve bir şifre belirleyin.
Başlangıç kontrolleri
Widget etkinleştirildiğinde, SignerWidgetOptions.SigningCertificate içindeki sertifika bir kez, AddDoconut() içinde kontrol edilir, böylece hatalı yapılandırılmış bir PFX ilk imzadan ziyade başlangıçta başarısız olur. Üç sorun bir InvalidOperationException fırlatır:
| Mesaj | Düzeltme |
|---|---|
Doconut Signer: the certificate file was not found at '{path}'. | Doğru PfxPath; dosyanın uygulamanın hesabı tarafından dağıtıldığından ve okunabildiğinden emin olun |
Doconut Signer: the signing certificate could not be opened — the password is incorrect or the file is not a valid .pfx. | Şifreyi kontrol edin; dosyanın gerçek bir .pfx olduğundan, bir .cer veya .pem olmadığından emin olun |
Doconut Signer: the signing certificate has no private key. Re-export the .pfx INCLUDING the private key. | PFX'i tekrar özel anahtarla dışa aktarın |
Aksi takdirde, ana bilgisayar başlarken günlüğe bir satır yazar. Sertifika hazır olduğunda bilgi:
Doconut Signer: using certificate '{subject}' (valid until yyyy-MM-dd). Signatures are digitally sealed.Süresi dolmuş, henüz geçerli olmayan veya belge imzalama için verilmemiş olduğunda bir Uyarı:
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.Ve hiçbir sertifika yapılandırılmadığında Bilgi:
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.Son satır her lisans altında aynıdır. Ücretli bir lisans altında demo sertifikası hiç kullanılmaz: sertifika yoksa, yalnızca Görsel imzalar çalışır.
C# arayüzü başlangıçta kontrol edilmez. SignAsync'a geçirdiğiniz sertifika imzaladığınızda okunur, bu yüzden yanlış bir yol veya şifre o çağrıyı başarısız kılar.
Drop-in widget
Enable the endpoints
The widget's ?sign=open|run|download endpoints are varsayılan olarak kapalıdır. Enable them next to the plugin registration:
builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
options.AddSignerWidget(widget =>
{
widget.MaxUploadMb = 25; // varsayılan
widget.MaxSignatureImageKb = 512; // varsayılan
// widget.SigningCertificate: Sertifika kurulumuna bakın; demo (su işaretli) imzalama için null bırakın
});
});AddSignerWidget() argümansız olarak widget'ı varsayılanlarla etkinleştirir. Tek başına imzalama yetkisi vermez: AddPlugin<SignerPlugin>() gerekir, ya da AddDoconut() hata verir:
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.AddSignerWidget() olmadan, her ?sign= isteği 404 yanıtını verir. Betik hâlâ sunulur, bu yüzden widget yüklenir ve bırakma bölgesini çizer, ardından ilk isteğinde Signing is not enabled on this server. rapor eder.
Embed it
UseDoconutResources() betiği {ResourcesPath}/js/doconutSigner.js adresinde (varsayılan /doconut-res/js/doconutSigner.js) sunar. Bağımlılığı olmayan tek bir, bağımsız dosyadır:
<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) bir CSS seçicisi ya da bir öğe alır, bağlama bulunamazsa hata verir ve bir tutamaç döndürür.
İmzalayan bir PDF ya da .docx dosyası yükler, bir imza oluşturur (Draw bir kanvasta, Type bir imza fontunda isim, ya da Image bir PNG, JPG ya da GIF'den), sayfaya sürükler ve yeniden boyutlandırır, ardından imzalar ve sonucu indirir. Widget her zaman imzayı PNG olarak gönderir; yüklenen görsel tarayıcıda 520×160 boyutuna uyan bir PNG'ye dönüştürülür.
Options
| Option | Type | Default | Notes |
|---|---|---|---|
basePath | string | '/doconut' | ?sign= uç noktalarının ve ön izleme görsellerinin sunulduğu yer |
resPath | string | '/doconut-res' | Ayrılmış; widget kendi CSS'ini paketler |
maxUploadMb | number | 25 | Yalnızca istemci tarafı kontrolü, bu yüzden aşırı büyük bir dosya hızlıca başarısız olur. Sunucu sınırı MaxUploadMb, AddSignerWidget içinde |
maxSignatureKb | number | 512 | Görsel mod için istemci tarafı sınırı. Sunucunun MaxSignatureImageKb değerine eşit tutun |
previewWidth | number | 560 | Sayfa ön izlemesinin piksel genişliği |
licenseUrl | string | null | null | demo-watermark uyarısını bu URL'ye bir bağlantı haline getirir |
signatureMode | string | 'certified' | İlk imza türü: 'certified' veya 'visual'. Başka herhangi bir değer 'certified' olur |
showSignatureModeToggle | boolean | true | Digital signature / Visual only seçeneğini gösterir. false ile widget, signatureMode ile imzalar |
wordOutput | string | 'pdf' | .docx kaynakları için ilk çıktı: 'pdf' veya 'docx'. Başka herhangi bir değer 'pdf' olur |
showOutputFormatToggle | boolean | true | PDF / Word seçeneğini gösterir, yalnızca .docx kaynakları için. false ile widget, wordOutput kullanır |
labels | object | {} | İngilizce dizelerin herhangi bir alt kümesini geçersiz kılar |
Bir geçişi gizlemek özelliği devre dışı bırakmaz; değeri sabitler. İki yaygın yapılandırma:
// Her iki geçiş gösterilir, dijital imza varsayılan olarak: tam öz hizmet imzalayan.
Doconut.signer('#host', { basePath: '/doconut', licenseUrl: '/pricing' });// Yalnızca görsel, geçiş yok: dijital imza sunulmayan basit bir damga.
Doconut.signer('#host', {
basePath: '/doconut',
signatureMode: 'visual',
showSignatureModeToggle: false
});Callbacks
| Callback | Fires when | Payload |
|---|---|---|
onReady | Bir kez, bağlama sırasında (reset()'da tekrar tetiklenmez) | — |
onSourceLoaded | Dosya açılır ve ön izlemesi gösterilir | { file: { token, name, pages, ext } } |
onSigned | İmzalama başarılı olur | { downloadToken, downloadName, watermarked } |
onDownload | Her İndir tıklamasında | { downloadName, downloadToken } |
onError | Açma, imzalama veya indirme adımı başarısız olur, ya da Görsel-mod dosyası çok büyük | { message } |
Hata veren bir geri çağrı yakalanır ve kaydedilir; widget akışını asla bozmaz.
Zorunlu işleyici
| Yöntem | Davranış |
|---|---|
reset() | Bırakma ekranına geri döner ve mevcut akışı temizler. onReady tekrar tetiklenmez. destroy() sonrası hiçbir işlem yapılmaz. |
loadFile(file) | File ile akışı başlatır. Widget bırakma ekranında değilse hiçbir işlem yapılmaz; gerekirse önce reset() çağırın. |
destroy() | Dinleyicileri kaldırır, bağlamayı boşaltır ve örneği dondurur. |
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());Etiketler
Her dize İngilizce varsayılan bir değere sahiptir; labels herhangi bir alt kümesini geçersiz kılar ve geri kalanlar İngilizce kalır. Çalışma zamanında değişen parçalar {placeholders} kullanır, örneğin uploading: 'Uploading {name}…' ve pages: '{n} pages'.
| Anahtar | İngilizce varsayılan |
|---|---|
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 |
Diğer anahtarlar yerleştirme adımını, hata ekranını, demo bildirisinin bağlanmış formunu (demoNoticePrefix, demoNoticeLink, demoNoticeSuffix) ve aria-live duyurularını kapsar.
open veya run, 404 sorusuna JSON hatası olmadan yanıt verdiğinde, widget signingNotEnabled gösterir. Sunucudan gelen bir JSON hatası her zaman önceliklidir, bu yüzden süresi dolmuş bir yükleme gibi mesajlar görünür kalır.
Tema
Widget, bağlama öğesine dsw sınıfını ekler ve renklerini, yarıçapını ve yazı tiplerini CSS özel özelliklerinden okur, böylece iç yapılarına dokunmadan temalandırabilirsiniz:
#host.dsw {
--dsw-accent: #b0522b; /* bağlantılar, odak, aktif mod */
--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; /* Type modu */
}Varsayılanlar: --dsw-accent: #2b6cb0, --dsw-bg: #ffffff, --dsw-fg: #1a202c, --dsw-muted: #718096, --dsw-border: #cbd5e0, --dsw-radius: 8px, bir sistem UI yazı tipi ve el yazısı imza fontu.
Kendi ön ucunuzu oluşturun
Widget, bu HTTP sözleşmesi için bir istemcidir. Üç rota da UseDoconut()'in bağlandığı yolun altında bulunur (genellikle /doconut), ve AddSignerWidget() çağrılana kadar 404 yanıt verir. Hatalar bir JSON gövdesi taşır, { "error": "..." }, tablo "yalnızca durum" dediği yerler hariç. Bilinmeyen bir ?sign= değeri 400 yanıt verir.
| Rota | Amaç | Başarı yanıtı |
|---|---|---|
POST ?sign=open (multipart, one file) | Bir PDF veya .docx yükleyin ve ön izleme için açın | 200 — { token, name, pages, ext } |
POST ?sign=run (JSON body) | Yüklenen dosyayı imzalayın | 200 — { downloadToken, downloadName, watermarked } |
GET ?sign=download&token=<downloadToken> | İmzalı dosyayı akış olarak gönderin | 200 — dosya, Content-Disposition: attachment, Cache-Control: no-store |
ext, open yanıtında önde gelen noktayı (".docx") içerir. Sayfa ön izlemesi standart görüntüleyici resim rotasını, {basePath}?token={token}&page={n}&thumb=1&width={px}, kullanır; gösterilen sayfa placement.page olur.
run gövdesi:
{
"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"
}| Alan | Notlar |
|---|---|
token | open'dan gelen token |
signature.kind | Drawn, Typed veya Image, büyük/küçük harfe duyarsız; başka herhangi bir şey Drawn olur. Sadece bir ipucu: yük her zaman PNG'dir |
signature.payload | Bir çıplak base64 PNG, data: öneki olmadan. Gerçek bir PNG olmalı ve çözüldükten sonra MaxSignatureImageKb'dan büyük olmamalıdır |
placement.page | 1 tabanlı |
placement.x / y / w / h | Üst‑sol köşeden normalize edilmiş 0..1, x + w ≤ 1 ve y + h ≤ 1 ile |
meta.signerName / reason / location | İsteğe bağlı. Her biri kırpılır, boş değer atılır ve her biri 256 karakterde kesilir |
wordOutput | pdf (varsayılan) veya docx; PDF kaynakları için yok sayılır. Başka herhangi bir şey pdf olur |
mode | certified (varsayılan) veya visual. Başka herhangi bir şey certified olur |
downloadName çıktıyı izler: <source>-signed.pdf veya <source>-signed.docx, ve download eşleşen Content-Type gönderir.
Yüklenen kaynak ve imzalı sonuç her biri 30 dakika saklanır. Bundan sonra, run ve download 404 yanıt verir ve dosya tekrar açılmalıdır. Tüm token'lar GUID'dir.
| Rota | Durum | Ne zaman | Gövde |
|---|---|---|---|
| any | 404 | Widget etkin değil | yalnızca durum |
| any | 405 | Yanlış fiil (open ve run POST gerekir, download GET gerekir) | yalnızca durum |
open | 400 | Multipart yükleme değil | Expected a multipart file upload. |
open | 400 | Dosya yok veya boş | No file uploaded. |
open | 400 | .pdf veya .docx dışındaki herhangi bir şey | Signing supports PDF and Word (.docx) files only. |
open | 413 | Yükleme MaxUploadMb'ı aşıyor | File is too large. |
run | 400 | Gövde geçerli JSON değil veya boş | Malformed request. / Empty request. |
run | 400 | Token eksik veya GUID değil | Invalid token. |
run | 404 | Yüklemenin süresi doldu veya hiç açılmadı | Upload expired — please re-open the file. |
run | 400 | İmza yok veya yerleştirme yok | No signature supplied. / No placement supplied. |
run | 400 | Yük base64 değil, boş, çok büyük veya PNG değil | Signature image is not valid base64. / Signature image is empty. / Signature image is too large. / The signature image must be a PNG. |
run | 400 | Yerleştirme sayfanın dışındadır | The signature or its placement is invalid. |
run | 400 | Sertifikalı mod, ücretli lisans ve sertifika yok | No signing certificate configured. |
run | 400 | Geçerlilik süresi dışında bir sertifikaya sahip sertifikalı mod | The signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd. |
open, run | 500 | İşleme başarısız | Temizlenmiş bir mesaj |
download | 400 | Token eksik veya GUID değil | yalnızca durum |
download | 404 | Bilinmeyen veya süresi dolmuş token | yalnızca durum |
Tam bir tur dönüşü fetch ile:
// file: imzalanacak Dosya; pngBase64: veri: öneki olmayan çıplak base64 PNG imzası,
// örneğin canvas.toDataURL('image/png').split(',')[1].
async function signFile(file, pngBase64) {
const base = '/doconut';
// 1. open: dosyayı yükle
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: imzala
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: imzalı dosyayı al
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);
}Uç noktalar same-origin'dır: bu sürüm CORS desteği sağlamaz. UI'nizi ve widget betiğini Doconut ile aynı origin'den sunun veya UI'nizin origin'i altında her iki /doconut yolunu da (middleware yolu ve kaynak yolu) ters proxy yapın.
Üretimde
-
Eklentiyi kurun çekirdek paketinin yanına, aynı sürümde:
dotnet add package Doconut.NET6.Signer. -
Lisans dosyasını ekleyin.
Doconut.Viewer.Signer.licdosyasınıDoconut.Viewer.licile aynı klasöre koyun. -
Sertifikanızı bir PFX olarak alın özel anahtarı ve veren zinciriyle birlikte, bir sertifika otoritesinden veya kuruluşunuzun kendi PKI'sından. İlk olarak denemek için, bir demo lisansı (yerleşik demo sertifikası, filigranlı) veya kendinden imzalı bir PFX kullanın.
-
Sertifikayı yapılandırmadan okuyun, böylece değiştirildiğinde kod değişikliği gerekmez:
json"DoconutSigner": { "PfxPath": "certs/your-certificate.pfx" }csharpvar signerSettings = builder.Configuration.GetSection("DoconutSigner"); builder.Services.AddDoconut(options => { options.LicensePath = "Doconut.Viewer.lic"; options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>(); options.AddSignerWidget(widget => widget.SigningCertificate = new SigningCertificate { PfxPath = Path.Combine(builder.Environment.ContentRootPath, signerSettings["PfxPath"]), Password = signerSettings["Password"] ?? "", }); });.pfx'yiwwwrootdışında tutun ve şifreyiappsettings.jsoniçinde tutmayın: geliştirme ortamında kullanıcı gizli bilgileri (dotnet user-secrets set "DoconutSigner:Password" "<password>"), bir ortam değişkeni (DoconutSigner__Password) veya üretimde bir kasada. -
Başlangıç günlüğünü kontrol edin.
using certificate '{subject}' (valid until …). Signatures are digitally sealed.okuması gerekir; bir Uyarı, sertifikanın süresi dolmuş, henüz geçerli değil veya belge imzalama için verilmemiş olduğu anlamına gelir.
PDF okuyucularına güvenin. Bir okuyucu, kök sertifikaya güvendiğinde imzayı geçerli gösterir. Kuruluşunuzun PKI'sı ile bu, kökünüzü güvenen her makinede geçerlidir; genellikle kuruluş içindeki her makinede olur. Adobe'nun herhangi bir makinede güvendiği sertifikalar (Adobe Approved Trust List) bizim bildiğimize göre özel anahtarın bir donanım token'ı veya HSM'de bulunmasıyla verilir; bu eklenti bunu kullanamaz: yalnızca bir PFX'ten imzalar. Bu tür bir güvene dayanmazdan önce sertifika sağlayıcınızla teyit edin.
Web çiftlikleri
Widget, open hizmet veren düğümde her yüklemeyi ve sonucunu bellekte tutar. Yapışkan oturumlar olmadan bir yük dengeleyicinin arkasında, daha sonraki bir run, download veya ön izleme isteği başka bir düğüme ulaşabilir ve yüklemeyi bulamaz. Paylaşılan, şifreli widget deposunu bir kez, AddDoconut() sonrasında kaydedin:
byte[] farmKey = Convert.FromBase64String(builder.Configuration["Doconut:FarmKey"]);
builder.Services.AddDoconutDistributedWidgets(store =>
{
store.RootPath = @"\\fileshare\doconut"; // her düğümün okuyup yazabileceği bir klasör
store.FarmKey = farmKey; // her düğümde aynı, en az 32 bayt
// store.Ttl = TimeSpan.FromMinutes(30); // bir yüklemenin ne kadar süre saklanacağı (varsayılan)
});- Tek bir sunucu hiçbir şeye ihtiyaç duymaz: bu çağrı olmadan bellek içi depolama kullanılır.
- Yüklemeler ve sonuçlar paylaşılda (AES-256, encrypt-then-MAC) dinlenirken şifrelenir ve her dosya token'ına bağlanır, böylece bir token başka birinin dosyasını asla okuyamaz.
FarmKeyen az 32 bayt olmalı ve her düğümde aynı olmalıdır. Bir gizli depodan yükleyin; asla sabit kodlamayın. Kayıt,RootPatheksik olduğunda veyaFarmKey32 bayttan kısa olduğunda birArgumentExceptionfırlatır.RootPath'yi dağıtılmış görüntüleyicinin kullandığı aynı paylaşılan konuma yönlendirin ve her düğüme aynı imzalama sertifikasını verin.
API referansı
Facade ve widget seçenekleri Doconut ad alanında bulunur; istek ve sonuç tipleri Doconut.Core.Models.Signing içinde yer alır. SignerPlugin Doconut.Plugins.Signer içinde bulunur.
DocumentSigner
public sealed class DocumentSigner
{
public Task<SignResult> SignAsync(
Stream source, string sourceExtension, SignRequest request,
SigningCertificate? cert = null, CancellationToken ct = default);
}Bağımlılık enjeksiyonundan çözülür; yapıcı dahili (internal)dir. sourceExtension ".pdf" veya ".docx"'dır. Ücretli bir lisans altında cert kullanılır ve çıktı temiz olur; geçici bir lisans altında yerleşik demo sertifikası kullanılır, cert yok sayılır ve çıktı filigranlı olur.
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
}Bir kez yerleştirilen tek bir görünür imza, artı isteğe bağlı imzalayan meta verileri.
VisibleSignature and SignatureKind
public sealed record VisibleSignature(SignatureKind Kind, byte[] PngBytes)
{
public bool IsValid { get; } // PngBytes boş değil
}
public enum SignatureKind { Drawn, Typed, Image }PngBytes her tür için bir PNG'dir. Çizilmiş veya yazılmış bir imza transparan (şeffaftır); yüklenen bir görüntü sahip olduğu şeffaflığı korur, bu yüzden opak bir JPG opak kalır. Kind sadece bir ipucudur.
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 1 tabanlıdır; X, Y, W ve H üst‑sol köşeden normalize edilmiş 0..1'dır.
SignatureMode and WordOutput
public enum SignatureMode { Certified, Visual } // Certified varsayılan
public enum WordOutput { Pdf, Docx } // Pdf varsayılandır; PDF kaynakları için yok sayılırSignResult
public sealed record SignResult(Stream Stream, string Extension);İmzalı belge, aranabilir bir akış (stream) olarak ve uzantısı nokta ile birlikte (".pdf" veya ".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 boş değil, veya PfxPath boş değil
}PfxBytes veya PfxPath ve ayrıca Password ayarlayın.
SignerWidgetOptions
public sealed class SignerWidgetOptions
{
public int MaxUploadMb { get; set; } = 25;
public int MaxSignatureImageKb { get; set; } = 512;
public SigningCertificate? SigningCertificate { get; set; }
}DoconutOptions.AddSignerWidget(Action<SignerWidgetOptions>? configure = null) aracılığıyla ayarlayın, bu DoconutOptions döndürür, böylece çağrılar zincirlenebilir. Null bir SigningCertificate geçici lisans altında demo sertifikasını, sadece ücretli lisans altında Görsel imzaları ifade eder.
Sorun Giderme
| Belirti | Neden | Çözüm |
|---|---|---|
AddDoconut(), The Signer plugin is registered via AddPlugin but no active license grants Signer. hatası verir | Lisans yok, bir TRIAL dosyası, Signer içermeyen bir lisans veya sürüm penceresinin dışındaki bir ücretli lisans | Signer sağlayan bir lisans kurun veya AddPlugin<SignerPlugin>() kaldırın |
AddDoconut(), AddSignerWidget() was called but the Signer plugin is not registered. hatası verir | Widget, eklentisi olmadan etkinleştirildi | options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>() ekleyin |
AddDoconut(), Doconut Signer: the certificate file was not found at '{path}'. hatası verir | PfxPath eksik bir dosyaya işaret ediyor | Yolu düzeltin; dosyayı uygulamanın hesabının okuyabileceği bir yere dağıtın |
AddDoconut(), Doconut Signer: the signing certificate could not be opened — the password is incorrect or the file is not a valid .pfx. hatası verir | Yanlış şifre veya PKCS#12 dosyası değil | Şifreyi kontrol edin; gerçek bir .pfx kullanın |
AddDoconut(), Doconut Signer: the signing certificate has no private key. Re-export the .pfx INCLUDING the private key. hatası verir | PFX, özel anahtarı olmadan dışa aktarıldı | Özel anahtarıyla tekrar dışa aktarın |
DocumentSigner çözülürken No IDocumentSigner is registered. hatası verir | SignerPlugin kayıtlı değil | AddDoconut() içinde AddPlugin<SignerPlugin>() ekleyin |
| Çıktı filigranlıdır | Lisans geçicidir (Demo/NFR) | Signer sağlayan bir ücretli lisans kullanın |
run, 400 No signing certificate configured. yanıt verir | Ücretli bir lisans, Sertifikalı mod ve sertifika yok | SigningCertificate yapılandırın veya Görsel modda imzalayın |
run, 400 The signing certificate expired on yyyy-MM-dd. yanıt verir | Sertifika süresi dolmuş | Değiştirin; bu arada Görsel imzalar çalışmaya devam eder |
| Günlük, çıktının "yerleşik demo sertifikasını kullandığını" söylüyor, ancak bir ücretli lisans Sertifikalı imzaları reddediyor | Bu satır, lisans ne olursa olsun, hiçbir sertifika yapılandırılmadığında yazılır | SigningCertificate yapılandırın |
Widget yüklenir ancak Signing is not enabled on this server. diyor | AddSignerWidget() çağrılmadı veya UseDoconut()'nin monte edildiği yerde basePath eşleşmiyor | AddSignerWidget() çağırın; basePath düzeltin |
run, 400 The signature image must be a PNG., Signature image is not valid base64. veya Signature image is too large. yanıt verir | Özel bir UI, bir data: URL'si, bir JPG veya MaxSignatureImageKb'dan fazla gönderdi | Kapasite içinde çıplak bir base64 PNG gönderin |
open, 413 File is too large. yanıt verir | Yükleme, MaxUploadMb sınırını aşıyor | AddSignerWidget içinde MaxUploadMb yükseltin; widget'ın maxUploadMb sadece istemci tarafı bir kontrol |
run veya download, 404 Upload expired — please re-open the file. yanıt verir | 30 dakikalık pencere geçti veya bir web-farm düğümü yüklemeye sahip değil | Dosyayı tekrar açın; bir farm içinde, AddDoconutDistributedWidgets kaydedin |
İmzalı bir .docx bazı görüntüleyicilerde imza göstermez | Word çıktısı bir OOXML paket imzası taşır, bu da birçok görüntüleyicide gösterilmez | Varsayılan olarak PDF'ye imzalayın |
| PDF okuyucular, imzalayanın kimliğinin bilinmediğini söylüyor | Okuyucu, sertifikanın köküne (demo sertifikası asla güvenilir değildir) güvenmiyor | Okuyucularınızın güvendiği bir kökten sertifika kullanın |
| Widget, UI başka bir kökende olduğunda başarısız olur | Uç noktalar CORS desteğine sahip değil | UI'yi aynı kökenden sunun veya Doconut yollarını ters proxy yapın |
| Tema uygulanmıyor | Seçici, mount içinde bir öğeyi hedefliyor | Mount'un kendisini hedefleyin: #host.dsw veya #host |
Bu sayfa yardımcı oldu mu?