İ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, PDF okuyucusunun doğrulayabileceği bir dijital 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üzeyNe zaman kullanılır
DocumentSigner (C#)Sunucuda imzalıyorsunuz, tarayıcı kullanılmaz
Hazır widget (doconutSigner.js)Sayfanızda hazır bir yükleme, imzalama ve indirme ekranı istiyorsunuz
HTTP uç noktaları (?sign=open|run|download)Belgelendirilmiş bir sunucu sözleşmesine karşı kendi imzalama UI'nizi oluşturuyorsunuz

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:

bash
dotnet add package Doconut.NET8.Signer

Bu belgenin açıkladığı sürüme eklentiyi sabitlemek için, sürümü ayrı olarak geçirin:

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

Signer paketini Doconut.NET8 ile aynı sürümde tutun. Paket kimliği Doconut.NET8.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.NET8 çalıştığı her yerde çalışır: Windows ve x64 üzerinde glibc tabanlı Linux (Alpine veya diğer musl tabanlı dağıtımlar hariç). Linux'ta, ilk belge açılmadan önce font yapılandırma kütüphanesini kurun:

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

Sistemde libfontconfig1 kütüphanesi eksik; PDF işleme için bu kütüphaneyi kurmanız gerekir.

RHEL, 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ı verir.

Eklentiyi kaydedin

Her Doconut eklentisi gibi, Signer AddDoconut() içinde AddPlugin<TPlugin>() ile kaydolur:

csharp
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 isteğe bağlı özelliktir, AddSignerWidget() (bkz. Hazır widget).

Eklenti, Signer yeteneğini veren bir lisansa ihtiyaç duyar. Lisans olmadan, AddDoconut() başlatma sırasında, uygulama bir istek hizmet etmeden önce hata verir:

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.

Lisans yoksa, eski bir TRIAL dosyası, Signer içermeyen bir lisans ve sürüm penceresinin dışında kullanılan ücretli bir lisans için hata verir. Geçici Demo/NFR lisansları kabul edilir. Lisansların nasıl yüklendiğini görmek için License Setup bölümüne bakın.

Lisanslama ve filigran

Lisans durumuBaşlatmaSertifikalı imzaGörsel imza
Ücretli lisans, Signer sağlar, sertifika yapılandırılmışBaşlarSertifikanızla mühürlenir, temiz (watermarked: false)Temiz
Ücretli lisans, Signer sağlar, sertifika yokBaşlarReddedildi: No signing certificate configured.Temiz
Ücretli lisans, sertifika süresi dolmuş veya henüz geçerli değilBaş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şlarYerleşik 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 ücretli bir lisansAddDoconut() 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çici ise çıktı filigranlı olur. Geçici bir lisans altında eklenti her zaman yerleşik 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ı ile uçtan uca oluşturulup test edilebilir; temiz ve güvenilir bir çıktı elde etmek için hem ücretli bir lisansa hem de kendi imzalama sertifikasıınıza 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çsel olduğundan, asla new etmeyin. AddPlugin<SignerPlugin>() olmadan çözümlemek No IDocumentSigner is registered. Add the signing plugin: options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>(). fırlatır.

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 varsayılan olarak Certified (görünür imza + dijital mühür) ayarlanır; WordOutput varsayılan olarak 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çindir. null'ı demo lisansı altında ya da Görsel modda geçirin.

SignResult, imzalı belgeyi aranabilir bir akış olarak tutar, ayrıca dosyayı adlandırabilmeniz için onun Extension (".pdf" veya ".docx") içerir. Akış sizin: işiniz bittiğinde onu dispose edin.

Bir Görsel imza yalnızca görüntüyü damgalamaktadır ve sertifika gerektirmez:

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

Bir Word kaynağı, Word çıktısı istemediğiniz sürece PDF'ye imzalanır. Sonucu result.Extension'dan adlandırın:

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, çağrı başarılı olamadığında döndürmek yerine fırlatır:

İstisnaMesajNe Zaman
InvalidOperationExceptionNo signing certificate configured.Sertifikalı mod, ücretli lisans ve sertifika gönderilmemiş
InvalidOperationExceptionThe 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
ArgumentExceptionThe 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
NotSupportedExceptionThe 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.

ModNe üretirSertifikaDoğrulanabilir
SignatureMode.Certified (varsayılan)Görünür imza ve dijital mühürÜcretli lisans altında gereklidirEvet
SignatureMode.VisualYalnızca görünür imzaAsla gerekmezHayır: bir resimdir

Certified'ı, 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. Bunlar, PFX dosyanızda bulunan yayıncı sertifikalarını taşır, 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şır.

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 olurDoğrulayıcı desteği
WordOutput.Pdf (varsayılan)Belge PDF'ye dönüştürülür, ardından imzalanır ve mühürlenirGeniş: imzalı bir PDF her yerde doğrulanır
WordOutput.DocxBelge Word olarak kalır: imza görüntüsü içine yerleştirilir, ayrıca bir OOXML paket imzası eklenirSı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 ederse PDF'i 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# katmanı için sertifikayı SignAsync'a geçirin. Baytları ya da bir yolu, ayrıca şifreyi sağlayın:

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

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ı içermesi gerekir. Sadece genel anahtar içeren bir dosya (.cer, .crt) imza atamaz. Yayımcı zincirini onunla dışa aktarın, böylece PDF mühürleri bunu taşıyabilir.
  • Doğru şifre.
  • Geçerlilik süresi içinde. Süresi dolmuş veya 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ına sahip ve varsa belge imzalamaya, e-posta korumasına veya istemci kimlik doğrulamasına izin veren genişletilmiş anahtar kullanımına sahip olmalıdır. 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:

bash
openssl pkcs12 -export -out signing.pfx -inkey private.key -in certificate.crt
# İstediğiniz 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 mevcutsa simgesi bir anahtar gösterir). Sağ tıklayın, All Tasks → Export… seçeneğini seçin, Yes, export the private key kutusunu 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:

MesajDüzeltme
Doconut Signer: the certificate file was not found at '{path}'.Correct 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, host başlarken günlüğe bir satır yazar. Sertifika hazır olduğunda bilgi:

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

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.

Ve hiçbir sertifika yapılandırılmadığında Bilgi:

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.

Son satır her lisans altında aynı olur. Ücretli bir lisans altında demo sertifikası hiç kullanılmaz: sertifika yoksa yalnızca Görsel imzalar çalışır.

C# katmanı 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.

Yerleştirilebilir widget

Uç noktaları etkinleştir

Widget'ın ?sign=open|run|download uç noktaları varsayılan olarak kapalıdır. Eklenti kaydı yanında bunları etkinleştirin:

csharp
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: Certificate kurulumuna bakın; demo (watermarked) 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:

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.

İmzalama bu sunucuda etkinleştirilmemiştir.

AddSignerWidget() olmadan, her ?sign= isteği 404 yanıt 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.

Göm

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:

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) bir CSS seçicisi ya da bir element alır, bağlama bulunamazsa hata verir ve bir tutamaç döndürür.

İmzalayan bir PDF veya .docx dosyası yükler, bir imza oluşturur (Çiz bir kanvasta, Yaz bir adı imza yazı tipinde, ya da Görsel bir PNG, JPG veya 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 boyutlarına uyan bir PNG'ye dönüştürülür.

Seçenekler

SeçenekTürVarsayılanNotlar
basePathstring'/doconut'?sign= uç noktalarının ve ön izleme görsellerinin sunulduğu yer
resPathstring'/doconut-res'Ayrılmış; widget kendi CSS'sini paketler
maxUploadMbnumber25Yalnı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
maxSignatureKbnumber512Görsel mod için istemci tarafı sınırı. Sunucunun MaxSignatureImageKb'ına eşit tutun
previewWidthnumber560Sayfa ön izlemesinin piksel genişliği
licenseUrlstring | nullnullDemo-su işareti uyarısını bu URL'ye bir bağlantıya dönüştürür
signatureModestring'certified'İlk imza türü: 'certified' veya 'visual'. Başka herhangi bir değer 'certified' olur
showSignatureModeTogglebooleantrueDijital imza / Yalnızca Görsel seçeneğini gösterir. false ile widget, signatureMode ile imzalar
wordOutputstring'pdf'.docx kaynakları için ilk çıktı: 'pdf' veya 'docx'. Başka herhangi bir değer 'pdf' olur
showOutputFormatTogglebooleantruePDF / Word seçeneğini gösterir, yalnızca .docx kaynakları için. false ile widget, wordOutput kullanır
labelsobject{}İ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:

javascript
// Her iki geçiş de gösterilir, varsayılan olarak dijital imza: tam öz hizmet imzalayan.
Doconut.signer('#host', { basePath: '/doconut', licenseUrl: '/pricing' });
javascript
// Yalnızca görsel, geçiş yok: dijital imza olmadan sunulan basit bir damga.
Doconut.signer('#host', {
  basePath: '/doconut',
  signatureMode: 'visual',
  showSignatureModeToggle: false
});

Geri çağrılar

Geri çağrıNe zaman tetiklenirYük
onReadyMount sırasında bir kez (reset()'da tekrar tetiklenmez)—
onSourceLoadedDosya açılır ve ön izlemesi gösterilir{ file: { token, name, pages, ext } }
onSignedİmzalama başarılı olur{ downloadToken, downloadName, watermarked }
onDownloadHer İndir tıklamasında{ downloadName, downloadToken }
onErrorAçma, imzalama veya indirme adımı başarısız olursa, ya da Görsel-mod dosyası çok büyükse{ message }

Hata atan bir geri çağrı yakalanır ve kaydedilir; widget akışını asla bozmaz.

Emirsel tutamak

YöntemDavranış
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.
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());

Etiketler

Her dize bir İngilizce varsayılanına 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
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

Diğer anahtarlar yerleştirme adımını, hata ekranını, demo bildirimindeki bağlantılı formu (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.

Temalandırma

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ısına dokunmadan temalandırabilirsiniz:

css
#host.dsw {
  --dsw-accent: #b0522b;       /* bağlantılar, odak, etkin 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 yazı tipi.

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, { "error": "..." } taşır, tablo "yalnızca durum" dediği yerler hariç. Bilinmeyen bir ?sign= değeri 400 yanıt verir.

RotaAmaçBaşarı yanıtı
POST ?sign=open (multipart, one file)Bir PDF veya .docx yükleyin ve ön izleme için açın200 — { token, name, pages, ext }
POST ?sign=run (JSON body)Yüklenen dosyayı imzalayın200 — { downloadToken, downloadName, watermarked }
GET ?sign=download&token=<downloadToken>İmzalanmış dosyayı akış olarak gönder200 — dosya, Content-Disposition: attachment, Cache-Control: no-store

ext, open yanıtında, baştaki 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:

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"
}
AlanNotlar
tokenopen'den gelen token
signature.kindDrawn, Typed veya Image, büyük/küçük harfe duyarsız; başka her şey Drawn olur. Sadece bir ipucu: yük her zaman bir PNG'dir
signature.payloadÖn ek data: olmayan çıplak bir base64 PNG. Gerçek bir PNG olmalı ve çözüldükten sonra MaxSignatureImageKb'dan büyük olmamalıdır
placement.page1‑tabanlı
placement.x / y / w / hSol‑üst 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
wordOutputpdf (varsayılan) veya docx; PDF kaynakları için yok sayılır. Başka her şey pdf olur
modecertified (varsayılan) veya visual. Başka her ş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 imzalanmış 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.

RotaDurumNe zamanGövde
herhangi404Widget etkin değilyalnızca durum
herhangi405Yanlış fiil (open ve run POST gerekir, download GET gerekir)yalnızca durum
open400Çok parçalı yükleme değilExpected a multipart file upload.
open400Dosya yok veya boşNo file uploaded.
open400.pdf veya .docx dışındaki her şeySigning supports PDF and Word (.docx) files only.
open413Yükleme MaxUploadMb'ı aşıyorFile is too large.
run400Gövde geçerli bir JSON değil veya boşMalformed request. / Empty request.
run400Token eksik veya GUID değilInvalid token.
run404Yükleme süresi doldu veya hiç açılmadıUpload expired — please re-open the file.
run400İmza yok veya yerleştirme yokNo signature supplied. / No placement supplied.
run400Yük base64 değil, boş, çok büyük veya PNG değilSignature image is not valid base64. / Signature image is empty. / Signature image is too large. / The signature image must be a PNG.
run400Yerleştirme sayfanın dışındadırThe signature or its placement is invalid.
run400Sertifikalı mod, ücretli lisans ve sertifika yokNo signing certificate configured.
run400Sertifikalı mod, geçerlilik süresi dışındaki bir sertifika ileThe signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd.
open, run500İşleme başarısız olduTemizlenmiş bir mesaj
download400Token eksik veya GUID değilyalnızca durum
download404Bilinmeyen veya süresi dolmuş tokenyalnızca durum

fetch ile tam bir tur:

javascript
// file: imzalanacak File; 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: imzalayın
  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 içermez. UI'nizi ve widget betiğini Doconut ile aynı origin'den sunun, ya da UI'nizin origin'i altında her iki /doconut yolunu da ters proxy yapın (middleware yolu ve kaynak yolu).

Üretimde

  1. Eklentiyi kurun çekirdek paketinin yanına, aynı sürümde: dotnet add package Doconut.NET8.Signer.

  2. Lisans dosyasını ekleyin. Doconut.Viewer.Signer.lic'yi Doconut.Viewer.lic ile aynı klasöre koyun.

  3. Sertifikanızı PFX olarak alın özel anahtarı ve veren zinciriyle birlikte, bir sertifika otoritesinden ya da kuruluşunuzun kendi PKI'sından. İlk olarak denemek için, bir demo lisansı (yerleşik demo sertifikası, filigranlı) ya da kendinden imzalı bir PFX kullanın.

  4. Sertifikayı yapılandırmadan okuyun, böylece değiştirildiğinde kod değişikliği gerekmez:

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

    .pfx'yi wwwroot dışında tutun ve şifreyi appsettings.json dışına saklayın: geliştirmede kullanıcı sırları (dotnet user-secrets set "DoconutSigner:Password" "<password>"), bir ortam değişkeni (DoconutSigner__Password) ya da üretimde bir kasada.

  5. 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 ya da 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 tüm makineler. Adobe'nun herhangi bir makinede güvendiği sertifikalar (Adobe Onaylı Güven Listesi) bizim bildiğimize göre, özel anahtar bir donanım token'ı veya HSM üzerinde verilmiştir ve bu eklenti bunu kullanamaz: sadece bir PFX'ten imzalar. Bu tür bir güvene dayanımdan önce sertifika sağlayıcınızla teyit edin.

Web çiftlikleri

Widget, open sunan 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ı kaydedin:

csharp
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;                   // en az 32 bayt, her düğümde aynı
    // 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.
  • FarmKey en az 32 bayt olmalı ve her düğümde aynı olmalıdır. Bir gizli depodan yükleyin; asla sabit kodlamayın. Kayıt, RootPath eksik olduğunda veya FarmKey 32 bayttan kısa olduğunda bir ArgumentException fı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

csharp
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ı (constructor) içtedir. sourceExtension, ".pdf" veya ".docx" olur. Ü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ı su işaretiyle işaretlenir.

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
}

Bir kez yerleştirilen tek bir görünür imza, artı isteğe bağlı imzalayan meta verileri.

VisibleSignature and SignatureKind

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

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 1 tabanlıdır; X, Y, W ve H, sol üst köşeden normalize edilmiş 0..1'dır.

SignatureMode and WordOutput

csharp
public enum SignatureMode { Certified, Visual }   // Certified varsayılan değerdir
public enum WordOutput { Pdf, Docx }              // Pdf varsayılan değerdir; PDF kaynakları için yok sayılır

SignResult

csharp
public sealed record SignResult(Stream Stream, string Extension);

İmzalı belge, aranabilir bir akış olarak ve uzantısı nokta ile birlikte (".pdf" veya ".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 boş değil, ya da PfxPath boş değil
}

Ya PfxBytes ya da PfxPath ayarlayın, ayrıca Password.

SignerWidgetOptions

csharp
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, çağrıların zincirlenebilmesi için DoconutOptions döndürür. Null bir SigningCertificate, geçici bir lisans altında demo sertifikasını ifade eder ve Görsel imzalar yalnızca ücretli bir lisans altında kullanılabilir.

Sorun Giderme

SemptomNedenÇözüm
AddDoconut() fırlatır The Signer plugin is registered via AddPlugin but no active license grants Signer.Lisans yok, bir TRIAL dosyası, Signer içermeyen bir lisans veya sürüm penceresinin dışındaki bir ücretli lisansSigner sağlayan bir lisans kurun veya AddPlugin<SignerPlugin>() kaldırın
AddDoconut() fırlatır AddSignerWidget() was called but the Signer plugin is not registered.Widget eklentisi olmadan etkinleştirildioptions.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>() ekleyin
AddDoconut() fırlatır Doconut Signer: the certificate file was not found at '{path}'.PfxPath eksik bir dosyaya işaret ediyorYolu düzeltin; dosyayı uygulamanın hesabının okuyabileceği bir yere dağıtın
AddDoconut() fırlatır Doconut Signer: the signing certificate could not be opened — the password is incorrect or the file is not a valid .pfx.Yanlış şifre veya PKCS#12 dosyası değilŞifreyi kontrol edin; gerçek bir .pfx kullanın
AddDoconut() fırlatır Doconut Signer: the signing certificate has no private key. Re-export the .pfx INCLUDING the private key.PFX, özel anahtarı olmadan dışa aktarıldıÖzel anahtarıyla tekrar dışa aktarın
Resolving DocumentSigner fırlatır No IDocumentSigner is registered.SignerPlugin kayıtlı değilAddPlugin<SignerPlugin>()'i AddDoconut() içine ekleyin
Çıktı su işaretiyle işaretleniyorLisans geçici (Demo/NFR)Signer sağlayan bir ücretli lisans kullanın
run cevap veriyor 400 No signing certificate configured.Ücretli bir lisans, Sertifikalı mod ve sertifika yokSigningCertificate yapılandırın, veya Görsel modda imzalayın
run cevap veriyor 400 The signing certificate expired on yyyy-MM-dd.Sertifika süresi dolmuşDeğiştirin; Görsel imzalar bu arada çalışmaya devam eder
Günlük, çıktının yerleşik demo sertifikasını kullandığını söylüyor, ancak ücretli bir lisans Sertifikalı imzalara izin vermiyorBu satır, lisans ne olursa olsun, hiçbir sertifika yapılandırılmadığında yazılırSigningCertificate'ı yapılandırın
Widget yüklendi ancak Signing is not enabled on this server. diyorAddSignerWidget() çağrılmadı, veya basePath, UseDoconut()'ın monte edildiği yerde eşleşmiyorAddSignerWidget()'ı çağırın; basePath'ı düzeltin
run cevap veriyor 400 The signature image must be a PNG., Signature image is not valid base64. veya Signature image is too large.Özel bir UI bir data: URL'si, bir JPG veya MaxSignatureImageKb'den fazla gönderdiKapas içinde çıplak bir base64 PNG gönderin
open cevap veriyor 413 File is too large.Yükleme, MaxUploadMb'ı aşıyorAddSignerWidget içinde MaxUploadMb'ı yükseltin; widget'ın maxUploadMb sadece istemci tarafı bir kontrol.
run veya download cevap veriyor 404 Upload expired — please re-open the file.30 dakikalık pencere geçti, veya bir web-farm düğümü yüklemeyi yapmadıDosyayı tekrar açın; bir farm içinde AddDoconutDistributedWidgets'ı kaydedin
İmzalı .docx bazı görüntüleyicilerde imza göstermiyorWord çıktısı bir OOXML paket imzası taşır, birçok görüntüleyici bunu göstermezVarsayılan olarak PDF'ye imzalayın
PDF okuyucular imzalayanın kimliğinin bilinmediğini söylüyorOkuyucu, sertifikanın köküne güvenmez (demo sertifikası asla güvenilir değildir)Okuyucularınızın güvendiği bir kökten sertifika kullanın
Widget, UI başka bir origin'de olduğunda başarısız olurUç noktalar CORS desteğine sahip değilUI'yi aynı origin'den sunun, veya Doconut yollarını ters proxy yapın
Tema uygulanmıyorSeçici, mount içinde bir öğeyi hedefliyorMount'un kendisini hedefleyin: #host.dsw veya #host

Bu sayfa yardımcı oldu mu?