Plugin ký tên

Ký tài liệu PDF và Word với chữ ký hiển thị và con dấu kỹ thuật số

Plugin Signer đặt một chữ ký hiển thị lên tài liệu và, mặc định, niêm phong nó bằng một chữ ký kỹ thuật số mà trình đọc PDF có thể xác minh. Nó ký các tệp PDF và Word (.docx). Chữ ký hiển thị luôn là một hình ảnh PNG: được vẽ, gõ, hoặc tải lên bởi người ký.

Giao diệnSử dụng khi
DocumentSigner (C#)Bạn ký trên máy chủ, không có trình duyệt tham gia
Widget nhúng (doconutSigner.js)Bạn muốn một màn hình tải lên, ký và tải xuống đã sẵn sàng trong trang của mình
Các điểm cuối HTTP (?sign=open|run|download)Bạn xây dựng UI ký riêng dựa trên hợp đồng máy chủ đã được tài liệu hoá

Mỗi chữ ký chỉ được đặt một lần, trên một trang. Tên người ký, lý do và vị trí có thể đi kèm với nó.

Cài đặt gói

Cài đặt plugin Signer ổn định mới nhất:

bash
dotnet add package Doconut.NET8.Signer

Để cố định plugin vào phiên bản mà tài liệu này mô tả, truyền phiên bản riêng biệt:

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

Giữ gói Signer ở cùng phiên bản với Doconut.NET8. ID gói là Doconut.NET8.Signer; .<version> chỉ xuất hiện trong tên tệp .nupkg đã tải xuống.

Tệp giấy phép của plugin, Doconut.Viewer.Signer.lic, được đặt trong cùng thư mục với Doconut.Viewer.lic; nó được đọc cùng với giấy phép của trình xem.

Nền tảng. Plugin chạy ở bất kỳ nơi nào Doconut.NET8 chạy: Windows, và Linux dựa trên glibc trên x64 (không phải Alpine hay các bản phân phối dựa trên musl khác). Trên Linux, cài đặt thư viện cấu hình phông chữ trước khi tài liệu đầu tiên mở:

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

Trên RHEL, Fedora và các bản phân phối tương tự, gói là fontconfig. Nếu không có, việc mở tài liệu sẽ thất bại với The system library libfontconfig1 is missing. Install it (Debian/Ubuntu: apt-get install -y libfontconfig1) and see the Linux section of the Doconut documentation.

Đăng ký plugin

Giống như mọi plugin Doconut, Signer đăng ký với AddPlugin<TPlugin>() bên trong AddDoconut():

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
});

Đó là tất cả những gì lớp mặt nạ C# cần. Widget và các điểm cuối HTTP của nó là một tùy chọn riêng, AddSignerWidget() (xem Widget nhúng).

Plugin cần một giấy phép cho phép khả năng Signer. Nếu không có, AddDoconut() sẽ ném lỗi khi khởi động, trước khi ứng dụng phục vụ yêu cầu:

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.

Nó ném lỗi khi không có giấy phép, tệp legacy TRIAL, giấy phép không có Signer, và giấy phép trả phí được sử dụng ngoài khoảng thời gian phiên bản của nó. Giấy phép Demo/NFR tạm thời được chấp nhận. Xem Cài đặt giấy phép để biết cách tải giấy phép.

Cấp phép & dấu watermark

Trạng thái giấy phépKhởi độngChữ ký đã chứng nhậnChữ ký trực quan
Giấy phép trả phí cho phép Signer, chứng chỉ đã cấu hìnhBắt đầuĐược niêm phong bằng chứng chỉ của bạn, sạch (watermarked: false)Sạch
Giấy phép trả phí cho phép Signer, không có chứng chỉBắt đầuBị từ chối: No signing certificate configured.Sạch
Giấy phép trả phí, chứng chỉ đã hết hạn hoặc chưa hiệu lựcBắt đầu (với widget được bật, một Cảnh báo được ghi lại)Bị từ chối: The signing certificate expired on yyyy-MM-dd.Sạch
Giấy phép Demo/NFR tạm thời, hoạt động hoặc hết hạnBắt đầuĐược niêm phong bằng chứng chỉ demo tích hợp, có watermark (watermarked: true)Có watermark
Không có giấy phép, tệp legacy TRIAL, giấy phép không có Signer, hoặc giấy phép trả phí ngoài khoảng thời gian phiên bảnAddDoconut() ném lỗi——

Quy tắc này giống nhau cho lớp mặt nạ C# và widget: đầu ra sẽ có watermark khi giấy phép không phải là giấy phép xem trả phí hoặc là tạm thời. Dưới giấy phép tạm thời, plugin luôn ký bằng chứng chỉ demo tích hợp, và bất kỳ chứng chỉ nào bạn cấu hình sẽ không được sử dụng.

Chứng chỉ demo tạo ra một con dấu thực, nhưng các trình đọc PDF không tin tưởng nó. Một tích hợp có thể được xây dựng và kiểm thử đầu cuối trên giấy phép đánh giá; để có đầu ra sạch, đáng tin cậy, bạn cần cả giấy phép trả phí và chứng chỉ ký của riêng bạn.

Sử dụng từ C#

DocumentSigner được đăng ký bởi AddDoconut() và được giải quyết từ dependency injection. Constructor của nó là internal, vì vậy không bao giờ new nó. Giải quyết nó mà không có AddPlugin<SignerPlugin>() sẽ ném 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 mặc định là Certified (chữ ký hiển thị + con dấu kỹ thuật số); WordOutput mặc định là 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 nhận luồng nguồn, phần mở rộng của nó (".pdf" hoặc ".docx"), yêu cầu, và chứng chỉ cho cuộc gọi này. Facade không đọc SignerWidgetOptions.SigningCertificate; cài đặt đó dành cho widget. Cung cấp null dưới giấy phép demo, hoặc ở chế độ Visual.

SignResult giữ tài liệu đã ký dưới dạng một luồng có thể seek, cộng với Extension của nó (".pdf" hoặc ".docx") để bạn có thể đặt tên cho tệp. Bạn sở hữu luồng: giải phóng nó khi bạn hoàn thành.

Một chữ ký Visual chỉ dán hình ảnh và không cần chứng chỉ:

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

Một nguồn Word sẽ được ký thành PDF trừ khi bạn yêu cầu đầu ra Word. Đặt tên kết quả từ 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 ném ngoại lệ thay vì trả về khi cuộc gọi không thể thành công:

Ngoại lệThông điệpKhi nào
InvalidOperationExceptionNo signing certificate configured.Chế độ Certified, giấy phép trả phí, và không có chứng chỉ được truyền
InvalidOperationExceptionThe signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd.Chế độ Certified với một chứng chỉ nằm ngoài khoảng thời gian hiệu lực
ArgumentExceptionThe sign request is invalid: the visible signature needs PNG bytes and the placement must be a normalized rectangle on a 1-based page.Dữ liệu PNG rỗng, hoặc vị trí không hợp lệ
NotSupportedExceptionThe signer supports PDF and Word (.docx) documents; got '{extension}'.Bất kỳ loại nguồn nào khác

Các chế độ ký, đầu ra Word và chứng chỉ

Các chế độ ký

SignRequest.Mode chọn liệu chữ ký có được niêm phong hay không.

Chế độKết quả tạo raChứng chỉCó thể xác minh
SignatureMode.Certified (default)Chữ ký hiển thị cộng với một niêm phong kỹ thuật sốYêu cầu khi có giấy phép trả phíCó
SignatureMode.VisualChỉ chữ ký hiển thịKhông bao giờ cầnKhông: nó là một hình ảnh

Sử dụng Certified khi chữ ký phải có thể chứng minh được: phê duyệt, hợp đồng, bất kỳ điều gì mà người xác minh cần kiểm tra về danh tính và tính toàn vẹn. Sử dụng Visual khi bạn chỉ cần hình thức của chữ ký, hoặc không có chứng chỉ. Giấy phép tạm thời sẽ đặt watermark lên cả hai.

Niêm phong PDF là các chữ ký tách rời PKCS#7 (adbe.pkcs7.detached) với SHA-256, cho các khóa RSA hoặc ECDSA. Chúng chứa các chứng chỉ của nhà phát hành được tìm thấy trong PFX của bạn, vì vậy một trình đọc tin tưởng root của bạn có thể xây dựng chuỗi. Niêm phong gốc Word là các chữ ký gói OOXML và chỉ mang chứng chỉ của người ký.

Tài liệu Word

Đối với nguồn .docx, SignRequest.WordOutput chọn đầu ra. Nó bị bỏ qua đối với các nguồn PDF, luôn tạo ra một PDF.

Đầu raĐiều gì xảy raHỗ trợ bộ xác minh
WordOutput.Pdf (mặc định)Tài liệu được chuyển đổi sang PDF, sau đó ký và niêm phongRộng: một PDF đã ký được xác thực ở mọi nơi
WordOutput.DocxTài liệu vẫn ở dạng Word: hình ảnh chữ ký được chèn vào, cộng thêm chữ ký gói OOXMLHạn chế: không phải mọi trình xem đều hiển thị chữ ký gói OOXML

Giữ PDF trừ khi người nhận cần một tệp Word có thể chỉnh sửa và chấp nhận hỗ trợ bộ xác minh hạn chế.

Cài đặt chứng chỉ

Để niêm phong bằng danh tính của bạn, cung cấp cho plugin một tệp PFX (PKCS#12) chứa khóa riêng. Đối với widget, đặt SignerWidgetOptions.SigningCertificate; đối với lớp mặt nạ C#, truyền chứng chỉ tới SignAsync. Cung cấp hoặc là dữ liệu byte hoặc một đường dẫn, cộng với mật khẩu:

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

Chứng chỉ chỉ được giữ trong bộ nhớ. Nó không bao giờ được ghi log, trả về cho client, hoặc lưu trữ, và mật khẩu không bao giờ xuất hiện trong dòng log hay thông báo lỗi.

Yêu cầu:

  • Một gói PFX / PKCS#12 có khóa riêng. Tệp chỉ chứa khóa công khai (.cer, .crt) không thể ký. Xuất chuỗi nhà phát hành cùng với nó, để các niêm phong PDF có thể mang theo.
  • Mật khẩu đúng.
  • Trong khoảng thời gian hiệu lực của nó. Chứng chỉ đã hết hạn hoặc chưa có hiệu lực không làm dừng ứng dụng: nó được ghi log là Cảnh báo khi khởi động, và các chữ ký Certified bị từ chối cho đến khi thay thế. Các chữ ký Visual không bị ảnh hưởng.
  • Cấp cho việc ký tài liệu: một mục đích khóa có digital signature hoặc non-repudiation, và một mục đích khóa mở rộng, nếu có, cho phép ký tài liệu, bảo vệ email hoặc xác thực khách hàng. Chứng chỉ được cấp cho mục đích khác, chẳng hạn chứng chỉ máy chủ TLS, vẫn có thể ký, nhưng sẽ được ghi log là Cảnh báo và các trình đọc PDF sẽ đánh dấu chữ ký.
  • Các token phần cứng, thẻ thông minh, HSM và kho chứng chỉ Windows không được hỗ trợ. Xuất chứng chỉ, cùng với khóa riêng và chuỗi, thành một tệp PFX.

Tạo một PFX từ chứng chỉ và khóa riêng bằng OpenSSL:

bash
openssl pkcs12 -export -out signing.pfx -inkey private.key -in certificate.crt
# Mật khẩu xuất mà bạn được yêu cầu là SigningCertificate.Password.

Xuất một tệp từ kho chứng chỉ Windows: mở certmgr.msc và tìm chứng chỉ (biểu tượng của nó hiển thị một chìa khóa khi có khóa riêng). Nhấp chuột phải, chọn All Tasks → Export…, chọn Yes, export the private key, chọn Personal Information Exchange – PKCS #12 (.PFX), và đặt mật khẩu.

Kiểm tra khởi động

Khi widget được bật, chứng chỉ trong SignerWidgetOptions.SigningCertificate được kiểm tra một lần, bên trong AddDoconut(), vì vậy một PFX cấu hình sai sẽ thất bại khi khởi động thay vì ở chữ ký đầu tiên. Ba vấn đề sẽ ném một InvalidOperationException:

Thông báoSửa chữa
Doconut Signer: the certificate file was not found at '{path}'.Sửa PfxPath; đảm bảo tệp được triển khai và có thể đọc được bởi tài khoản của ứng dụng
Doconut Signer: the signing certificate could not be opened — the password is incorrect or the file is not a valid .pfx.Kiểm tra mật khẩu; đảm bảo tệp là một .pfx thực, không phải là .cer hay .pem
Doconut Signer: the signing certificate has no private key. Re-export the .pfx INCLUDING the private key.Xuất lại PFX với khóa riêng

Nếu không, máy chủ sẽ ghi một dòng vào log khi khởi động. Thông tin khi chứng chỉ đã sẵn sàng:

text
Doconut Signer: using certificate '{subject}' (valid until yyyy-MM-dd). Signatures are digitally sealed.

Một Cảnh báo khi nó đã hết hạn, chưa có hiệu lực, hoặc không được cấp cho việc ký tài liệu:

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.

Và Thông tin khi không có chứng chỉ nào được cấu hình:

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.

Dòng cuối cùng đó giống nhau cho mọi giấy phép. Trong giấy phép trả phí, chứng chỉ demo không bao giờ được sử dụng: khi không có chứng chỉ, chỉ các chữ ký Visual hoạt động.

Lớp mặt nạ C# không được kiểm tra khi khởi động. Chứng chỉ bạn truyền tới SignAsync được đọc khi bạn ký, vì vậy một đường dẫn hoặc mật khẩu sai sẽ làm lệnh này thất bại.

Tiện ích nhúng

Kích hoạt các endpoint

Các endpoint ?sign=open|run|download của tiện ích được tắt theo mặc định. Kích hoạt chúng bên cạnh việc đăng ký plugin:

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
    options.AddSignerWidget(widget =>
    {
        widget.MaxUploadMb = 25;           // mặc định
        widget.MaxSignatureImageKb = 512;  // mặc định
        // widget.SigningCertificate: xem Certificate setup; để null cho demo (có dấu nước) ký
    });
});

AddSignerWidget() không có đối số sẽ kích hoạt tiện ích với các mặc định. Nó không tự cấp quyền ký: nó cần AddPlugin<SignerPlugin>(), hoặc AddDoconut() sẽ ném lỗi: Chữ ký không được bật trên máy chủ này.

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.

Nếu không có AddSignerWidget(), mọi yêu cầu ?sign= sẽ trả lời 404. Script vẫn được phục vụ, vì vậy tiện ích sẽ tải và vẽ khu vực thả, sau đó báo cáo Signing is not enabled on this server. trong yêu cầu đầu tiên của nó.

Nhúng nó

UseDoconutResources() phục vụ script tại {ResourcesPath}/js/doconutSigner.js (mặc định /doconut-res/js/doconutSigner.js). Đây là một tệp duy nhất, tự chứa và không có phụ thuộc:

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) nhận một bộ chọn CSS hoặc một phần tử, ném lỗi nếu không tìm thấy mount, và trả về một handle.

Người ký tải lên một tệp PDF hoặc .docx, tạo chữ ký (Vẽ trên canvas, Gõ tên bằng phông chữ chữ ký, hoặc Hình ảnh từ PNG, JPG hoặc GIF), kéo và thay đổi kích thước lên trang, và ký và tải xuống kết quả. Tiện ích luôn gửi chữ ký dưới dạng PNG; hình ảnh tải lên được chuyển đổi trong trình duyệt thành PNG có kích thước 520×160.

Tùy chọn

Tùy chọnKiểuMặc địnhGhi chú
basePathstring'/doconut'Nơi các endpoint ?sign= và hình ảnh xem trước được phục vụ
resPathstring'/doconut-res'Dành riêng; tiện ích đóng gói CSS riêng của nó
maxUploadMbnumber25Chỉ kiểm tra phía client, vì vậy tệp quá lớn sẽ thất bại nhanh. Giới hạn máy chủ là MaxUploadMb trong AddSignerWidget
maxSignatureKbnumber512Giới hạn phía client cho chế độ Image. Giữ nó bằng với MaxSignatureImageKb của máy chủ
previewWidthnumber560Chiều rộng pixel của bản xem trước trang
licenseUrlstring | nullnullBiến thông báo demo-watermark thành liên kết tới URL này
signatureModestring'certified'Kiểu chữ ký ban đầu: 'certified' hoặc 'visual'. Bất kỳ giá trị nào khác sẽ trở thành 'certified'
showSignatureModeTogglebooleantrueHiển thị lựa chọn Chữ ký kỹ thuật số / Chỉ hiển thị. Với false, tiện ích ký bằng signatureMode
wordOutputstring'pdf'Đầu ra ban đầu cho các nguồn .docx: 'pdf' hoặc 'docx'. Bất kỳ giá trị nào khác sẽ trở thành 'pdf'
showOutputFormatTogglebooleantrueHiển thị lựa chọn PDF / Word, chỉ dành cho các nguồn .docx. Với false, tiện ích sử dụng wordOutput
labelsobject{}Ghi đè bất kỳ tập con nào của các chuỗi tiếng Anh

Ẩn một công tắc không vô hiệu hoá tính năng; nó cố định giá trị. Hai cấu hình phổ biến:

javascript
// Cả hai công tắc đều được hiển thị, chữ ký số mặc định: một người ký tự tự phục vụ đầy đủ.
Doconut.signer('#host', { basePath: '/doconut', licenseUrl: '/pricing' });
javascript
// Chỉ hiển thị, không có công tắc: một con dấu đơn giản không cung cấp chữ ký số.
Doconut.signer('#host', {
  basePath: '/doconut',
  signatureMode: 'visual',
  showSignatureModeToggle: false
});

Các callback

CallbackKích hoạt khiDữ liệu
onReadyMột lần, khi mount (không lại khi reset())—
onSourceLoadedTệp được mở và bản xem trước của nó được hiển thị{ file: { token, name, pages, ext } }
onSignedKý thành công{ downloadToken, downloadName, watermarked }
onDownloadMỗi khi nhấn Download{ downloadName, downloadToken }
onErrorBước mở, ký hoặc tải xuống thất bại, hoặc tệp chế độ Image quá lớn{ message }

Một callback ném lỗi sẽ được bắt và ghi log; nó không bao giờ làm gián đoạn luồng của tiện ích.

Xử lý bắt buộc

Phương thứcHành vi
reset()Quay lại màn hình thả và xóa luồng hiện tại. Không kích hoạt lại onReady. Không thực hiện gì sau destroy()
loadFile(file)Bắt đầu luồng với một File. Không thực hiện gì trừ khi widget đang ở màn hình thả; nếu cần, gọi reset() trước.
destroy()Xóa các listener, làm trống mount và đóng băng 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());

Nhãn

Mỗi chuỗi đều có giá trị mặc định bằng tiếng Anh; labels ghi đè bất kỳ phần nào và phần còn lại vẫn giữ tiếng Anh. Các đoạn thay đổi tại thời gian chạy sử dụng {placeholders}, chẳng hạn như uploading: 'Uploading {name}…' và pages: '{n} pages'.

KhóaGiá trị mặc định tiếng Anh
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

Các khóa bổ sung bao gồm bước đặt vị trí, màn hình lỗi, mẫu liên kết của thông báo demo (demoNoticePrefix, demoNoticeLink, demoNoticeSuffix) và các thông báo aria-live.

Khi open hoặc run trả lời 404 mà không có lỗi JSON, widget sẽ hiển thị signingNotEnabled. Lỗi JSON từ máy chủ luôn được ưu tiên, vì vậy các thông báo như tải lên đã hết hạn vẫn hiển thị.

Tùy chỉnh giao diện

Widget thêm lớp dsw vào phần tử mount và đọc màu sắc, bán kính và phông chữ từ các thuộc tính tùy chỉnh CSS, vì vậy bạn có thể tùy chỉnh giao diện mà không cần chạm vào nội bộ:

css
#host.dsw {
  --dsw-accent: #b0522b;       /* liên kết, tiêu điểm, chế độ hoạt động */
  --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;   /* chế độ Type */
}

Mặc định: --dsw-accent: #2b6cb0, --dsw-bg: #ffffff, --dsw-fg: #1a202c, --dsw-muted: #718096, --dsw-border: #cbd5e0, --dsw-radius: 8px, một phông chữ UI hệ thống, và một phông chữ chữ ký dạng viết tay.

Xây dựng giao diện người dùng của riêng bạn

Widget là một client cho hợp đồng HTTP này. Ba route đều nằm dưới đường dẫn nơi UseDoconut() được gắn (thông thường là /doconut), và chúng trả lời 404 cho đến khi AddSignerWidget() được gọi. Lỗi mang theo một body JSON, { "error": "..." }, ngoại trừ các trường hợp trong bảng ghi là "chỉ trạng thái". Một giá trị ?sign= không biết sẽ trả lời 400.

Đường dẫnMục đíchPhản hồi thành công
POST ?sign=open (đa phần, một tệp)Tải lên một PDF hoặc .docx và mở nó để xem trước200 — { token, name, pages, ext }
POST ?sign=run (body JSON)Ký tệp đã tải lên200 — { downloadToken, downloadName, watermarked }
GET ?sign=download&token=<downloadToken>Phát luồng tệp đã ký200 — tệp, Content-Disposition: attachment, Cache-Control: no-store

ext trong phản hồi open bao gồm dấu chấm đầu tiên (".docx"). Bản xem trước trang sử dụng đường dẫn hình ảnh viewer tiêu chuẩn, {basePath}?token={token}&page={n}&thumb=1&width={px}; trang được hiển thị trở thành placement.page.

Thân 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"
}
TrườngGhi chú
tokenMã token từ open
signature.kindDrawn, Typed hoặc Image, không phân biệt chữ hoa/thường; bất kỳ giá trị nào khác sẽ trở thành Drawn. Chỉ là gợi ý: payload luôn là PNG
signature.payloadMột PNG base64 thuần, không có tiền tố data:. Nó phải là PNG thực và không lớn hơn MaxSignatureImageKb sau khi giải mã
placement.pagebắt đầu từ 1
placement.x / y / w / h0..1 đã chuẩn hoá từ góc trên‑trái, với x + w ≤ 1 và y + h ≤ 1
meta.signerName / reason / locationTùy chọn. Mỗi giá trị được cắt bỏ khoảng trắng, giá trị trống bị loại bỏ, và mỗi giá trị được cắt ở 256 ký tự
wordOutputpdf (mặc định) hoặc docx; bị bỏ qua cho nguồn PDF. Bất kỳ giá trị nào khác sẽ trở thành pdf
modecertified (mặc định) hoặc visual. Bất kỳ giá trị nào khác sẽ trở thành certified

downloadName theo đầu ra: <source>-signed.pdf hoặc <source>-signed.docx, và download gửi Content-Type tương ứng.

Nguồn đã tải lên và kết quả đã ký mỗi cái được giữ trong 30 phút. Sau thời gian đó, run và download trả lời 404 và tệp phải được mở lại. Tất cả token đều là GUID.

Đường dẫnTrạng tháiKhiNội dung
any404Widget không được bậtchỉ trạng thái
any405Sai động từ (open và run cần POST, download cần GET)chỉ trạng thái
open400Không phải tải lên đa phầnExpected a multipart file upload.
open400Không có tệp, hoặc tệp rỗngNo file uploaded.
open400Bất kỳ giá trị nào khác ngoài .pdf hoặc .docxSigning supports PDF and Word (.docx) files only.
open413Tải lên vượt quá MaxUploadMbFile is too large.
run400Body không phải JSON hợp lệ, hoặc rỗngMalformed request. / Empty request.
run400Token bị thiếu hoặc không phải GUIDInvalid token.
run404Tải lên đã hết hạn hoặc chưa bao giờ được mởUpload expired — please re-open the file.
run400Không có chữ ký, hoặc không có vị tríNo signature supplied. / No placement supplied.
run400Payload không phải base64, rỗng, quá lớn, hoặc không phải PNGSignature image is not valid base64. / Signature image is empty. / Signature image is too large. / The signature image must be a PNG.
run400Vị trí nằm ngoài trangThe signature or its placement is invalid.
run400Chế độ chứng nhận, giấy phép trả phí và không có chứng chỉNo signing certificate configured.
run400Chế độ chứng nhận với chứng chỉ ngoài thời gian hiệu lựcThe signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd.
open, run500Xử lý thất bạiMột thông báo đã được làm sạch
download400Token bị thiếu hoặc không phải GUIDchỉ trạng thái
download404Token không xác định hoặc đã hết hạnchỉ trạng thái

Một vòng tròn hoàn chỉnh với fetch:

javascript
// file: Tệp để ký; pngBase64: chữ ký dưới dạng PNG base64 thuần, không có tiền tố data:,
// ví dụ canvas.toDataURL('image/png').split(',')[1].
async function signFile(file, pngBase64) {
  const base = '/doconut';

  // 1. open: tải lên tệp
  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: ký 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: tải về tệp đã ký
  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);
}

Các endpoint là same-origin: phiên bản này không hỗ trợ CORS. Phục vụ UI và script widget của bạn từ cùng một nguồn gốc với Doconut, hoặc reverse-proxy cả các đường dẫn /doconut (đường dẫn middleware và đường dẫn tài nguyên) dưới nguồn gốc của UI của bạn.

Trong môi trường sản xuất

  1. Cài đặt plugin bên cạnh gói core, ở cùng phiên bản: dotnet add package Doconut.NET8.Signer.

  2. Thêm tệp giấy phép. Đặt Doconut.Viewer.Signer.lic trong cùng thư mục với Doconut.Viewer.lic.

  3. Lấy chứng chỉ của bạn dưới dạng PFX cùng với khóa riêng và chuỗi nhà phát hành, từ một cơ quan cấp chứng chỉ hoặc PKI nội bộ của tổ chức bạn. Để thử trước, sử dụng giấy phép demo (chứng chỉ demo tích hợp, có dấu nước) hoặc một PFX tự ký.

  4. Đọc chứng chỉ từ cấu hình, để việc thay đổi không bao giờ cần thay đổi mã:

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

    Giữ .pfx bên ngoài wwwroot, và giữ mật khẩu ra khỏi appsettings.json: bí mật người dùng trong phát triển (dotnet user-secrets set "DoconutSigner:Password" "<password>"), biến môi trường (DoconutSigner__Password) hoặc một kho lưu trữ trong môi trường sản xuất.

  5. Kiểm tra log khởi động. Nó nên hiển thị using certificate '{subject}' (valid until …). Signatures are digitally sealed.. Một cảnh báo thay vì đó có nghĩa là chứng chỉ đã hết hạn, chưa hợp lệ, hoặc không được cấp để ký tài liệu.

Tin cậy trong các trình đọc PDF. Một trình đọc hiển thị chữ ký là hợp lệ khi nó tin cậy gốc của chứng chỉ. Với PKI của tổ chức bạn, điều này áp dụng cho mọi máy tính tin cậy gốc của bạn, thường là mọi máy trong tổ chức. Các chứng chỉ mà Adobe tin cậy trên bất kỳ máy nào (Adobe Approved Trust List) theo hiểu biết của chúng tôi, được cấp với khóa riêng trên một token phần cứng hoặc HSM, mà plugin này không thể sử dụng: nó chỉ ký từ một PFX. Xác nhận với nhà cung cấp chứng chỉ của bạn trước khi dựa vào loại tin cậy này.

Cụm máy chủ web

Widget giữ mỗi lần tải lên và kết quả của nó trong bộ nhớ trên node đã phục vụ open. Đằng sau một bộ cân bằng tải không có phiên dính, một yêu cầu run, download hoặc xem trước sau này có thể tới một node khác và không tìm thấy lần tải lên. Đăng ký kho widget được chia sẻ và mã hoá một lần, sau AddDoconut():

csharp
byte[] farmKey = Convert.FromBase64String(builder.Configuration["Doconut:FarmKey"]);

builder.Services.AddDoconutDistributedWidgets(store =>
{
    store.RootPath = @"\\fileshare\doconut";   // một thư mục mà mọi nút đều có thể đọc và ghi
    store.FarmKey = farmKey;                   // ít nhất 32 byte, giống nhau trên mọi nút
    // store.Ttl = TimeSpan.FromMinutes(30);   // thời gian một tải lên được giữ (mặc định)
});
  • Một máy chủ đơn lẻ không cần gì: nếu không có cuộc gọi này, kho lưu trữ trong bộ nhớ sẽ được sử dụng.
  • Các lần tải lên và kết quả được mã hoá khi ở trạng thái nghỉ trên chia sẻ (AES-256, encrypt-then-MAC), và mỗi tệp được gắn với token của nó, vì vậy một token không bao giờ có thể đọc tệp của token khác.
  • FarmKey phải có ít nhất 32 byte và giống nhau trên mọi node. Tải nó từ kho bí mật; không bao giờ hard-code. Đăng ký sẽ ném một ArgumentException khi RootPath bị thiếu hoặc FarmKey ngắn hơn 32 byte.
  • Đặt RootPath tới cùng một vị trí chia sẻ mà trình xem phân tán sử dụng, và cung cấp cho mọi node cùng một chứng chỉ ký.

Tham chiếu API

Facade và các tùy chọn widget nằm trong không gian tên Doconut; các kiểu yêu cầu và kết quả nằm trong Doconut.Core.Models.Signing. SignerPlugin nằm trong 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);
}

Được giải quyết thông qua tiêm phụ thuộc; constructor là internal. sourceExtension là ".pdf" hoặc ".docx". Khi có giấy phép trả phí, cert được sử dụng và đầu ra sạch; khi có giấy phép tạm thời, chứng chỉ demo tích hợp được sử dụng, cert bị bỏ qua, và đầu ra có dấu watermark.

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
}

Một chữ ký hiển thị được đặt một lần, cộng với siêu dữ liệu người ký tùy chọn.

VisibleSignature and SignatureKind

csharp
public sealed record VisibleSignature(SignatureKind Kind, byte[] PngBytes)
{
    public bool IsValid { get; }   // PngBytes không rỗng
}

public enum SignatureKind { Drawn, Typed, Image }

PngBytes là một PNG cho mọi loại. Chữ ký được vẽ hoặc gõ là trong suốt; hình ảnh tải lên giữ nguyên độ trong suốt mà nó có, vì vậy JPG không trong suốt vẫn không trong suốt. Kind chỉ là một gợi ý.

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 bắt đầu từ 1; X, Y, W và H được chuẩn hoá 0..1 từ góc trên‑trái.

SignatureMode and WordOutput

csharp
public enum SignatureMode { Certified, Visual }   // Certified là mặc định
public enum WordOutput { Pdf, Docx }              // Pdf là mặc định; bị bỏ qua đối với nguồn PDF

SignResult

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

Tài liệu đã ký dưới dạng stream có thể seek, và phần mở rộng của nó kèm dấu chấm (".pdf" hoặc ".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 không rỗng, hoặc PfxPath không trống
}

Đặt PfxBytes hoặc PfxPath, cộng với Password.

SignerWidgetOptions

csharp
public sealed class SignerWidgetOptions
{
    public int MaxUploadMb { get; set; } = 25;
    public int MaxSignatureImageKb { get; set; } = 512;
    public SigningCertificate? SigningCertificate { get; set; }
}

Đặt thông qua DoconutOptions.AddSignerWidget(Action<SignerWidgetOptions>? configure = null), nó trả về DoconutOptions để các lời gọi có thể được nối chuỗi. Một SigningCertificate null có nghĩa là chứng chỉ demo dưới giấy phép tạm thời, và chỉ có chữ ký Visual khi có giấy phép trả phí.

Khắc phục sự cố

Triệu chứngNguyên nhânGiải pháp
AddDoconut() ném The Signer plugin is registered via AddPlugin but no active license grants Signer.Không có giấy phép, một tệp TRIAL, một giấy phép thiếu Signer, hoặc một giấy phép trả phí ngoài khoảng thời gian phiên bản của nóCài đặt một giấy phép cho phép Signer, hoặc loại bỏ AddPlugin<SignerPlugin>()
AddDoconut() ném AddSignerWidget() was called but the Signer plugin is not registered.Widget được bật mà không có plugin của nóThêm options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>()
AddDoconut() ném Doconut Signer: the certificate file was not found at '{path}'.PfxPath trỏ tới một tệp bị thiếuSửa đường dẫn; triển khai tệp ở nơi tài khoản ứng dụng có thể đọc được
AddDoconut() ném Doconut Signer: the signing certificate could not be opened — the password is incorrect or the file is not a valid .pfx.Mật khẩu sai, hoặc không phải là tệp PKCS#12Kiểm tra mật khẩu; sử dụng một .pfx thực
AddDoconut() ném Doconut Signer: the signing certificate has no private key. Re-export the .pfx INCLUDING the private key.PFX đã được xuất mà không có khóa riêngXuất lại với khóa riêng
Resolving DocumentSigner ném No IDocumentSigner is registered.SignerPlugin chưa được đăng kýThêm AddPlugin<SignerPlugin>() vào bên trong AddDoconut()
Đầu ra có dấu watermarkGiấy phép là tạm thời (Demo/NFR)Sử dụng giấy phép trả phí cho phép Signer
run trả lời 400 No signing certificate configured.Giấy phép trả phí, chế độ Certified, và không có chứng chỉCấu hình SigningCertificate, hoặc ký ở chế độ Visual
run trả lời 400 The signing certificate expired on yyyy-MM-dd.Chứng chỉ đã hết hạnThay thế nó; chữ ký Visual vẫn hoạt động trong thời gian này
Log cho biết đầu ra "sử dụng chứng chỉ demo tích hợp", nhưng giấy phép trả phí từ chối chữ ký CertifiedDòng này được ghi bất cứ khi nào không có chứng chỉ được cấu hình, bất kể giấy phép nàoCấu hình SigningCertificate
Widget tải nhưng hiển thị Signing is not enabled on this server.AddSignerWidget() chưa được gọi, hoặc basePath không khớp với nơi UseDoconut() được gắnGọi AddSignerWidget(); sửa basePath
run trả lời 400 The signature image must be a PNG., Signature image is not valid base64. hoặc Signature image is too large.UI tùy chỉnh đã gửi một URL data:, một JPG, hoặc hơn MaxSignatureImageKbGửi một PNG base64 thuần trong giới hạn
open trả lời 413 File is too large.Tải lên vượt quá MaxUploadMbKhai báo MaxUploadMb trong AddSignerWidget; maxUploadMb của widget chỉ là kiểm tra phía client
run hoặc download trả lời 404 Upload expired — please re-open the file.Cửa sổ 30 phút đã hết, hoặc một nút web-farm không có tệp tải lênMở lại tệp; trong một farm, đăng ký AddDoconutDistributedWidgets
Một .docx đã ký không hiển thị chữ ký trong một số trình xemĐầu ra Word chứa chữ ký gói OOXML, mà nhiều trình xem không hiển thịKý sang PDF, mặc định
Trình đọc PDF nói danh tính người ký không xác địnhTrình đọc không tin cậy gốc của chứng chỉ (chứng chỉ demo không bao giờ được tin cậy)Sử dụng chứng chỉ từ một gốc mà trình đọc của bạn tin cậy
Widget thất bại khi UI ở nguồn khácCác endpoint không hỗ trợ CORSPhục vụ UI từ cùng nguồn, hoặc reverse-proxy các đường Doconut
Giao diện không áp dụngBộ chọn nhắm vào một phần tử bên trong mountNhắm vào chính mount: #host.dsw hoặc #host

Trang này có hữu ích không?