Plugin Signer
Sign PDF and Word documents with a visible signature and a digital seal
Plugin Signer đặt một chữ ký có thể nhìn thấy trên tài liệu và, theo mặc định, niêm phong nó bằng một chữ ký số mà trình đọc PDF có thể xác minh. Nó ký các tệp PDF và Word (.docx). Chữ ký có thể nhìn thấy 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ện | Sử dụng khi |
|---|---|
DocumentSigner (C#) | Bạn ký trên máy chủ, không có trình duyệt tham gia |
Drop-in widget (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 |
HTTP endpoints (?sign=open|run|download) | Bạn xây dựng giao diện ký của riêng mình dựa trên hợp đồng máy chủ đã được tài liệu hoá |
Mỗi chữ ký đượ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:
dotnet add package Doconut.NET6.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:
dotnet add package Doconut.NET6.Signer --version 26.10.0Giữ gói Signer ở cùng phiên bản với Doconut.NET6. ID gói là Doconut.NET6.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, nằm 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.NET6 chạy: Windows và Linux dựa trên glibc trên kiến trúc x64 (không phải Alpine hoặc 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 được mở:
apt-get update && apt-get install -y libfontconfig1Trê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>() trong AddDoconut():
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 endpoint HTTP của nó là một tùy chọn riêng, AddSignerWidget() (xem Drop-in widget).
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ụ một yêu cầu:
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 thiếu 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 License Setup để biết cách tải giấy phép.
Cấp phép & đánh dấu
| Trạng thái giấy phép | Khởi động | Chữ ký đã chứng nhận | Chữ ký trực quan |
|---|---|---|---|
Giấy phép trả phí cho phép Signer, chứng chỉ đã cấu hình | Bắ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 đầu | Bị 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 hợp lệ | Bắ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, đang hoạt động hoặc đã hết hạn | Bắ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 thiếu Signer, hoặc giấy phép trả phí ngoài khoảng thời gian phiên bản | AddDoconut() 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ử toàn bộ 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 mình.
Sử dụng từ C#
DocumentSigner được đăng ký bởi AddDoconut() và được giải quyết thông qua tiêm phụ thuộc. Constructor của nó là nội bộ, 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>().
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 lấy 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. Giao diện 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 luồng có thể tìm kiếm, 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.
Chữ ký Visual chỉ dán hình ảnh và không cần chứng chỉ:
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);Nguồn Word đượ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:
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ệp | Khi nào |
|---|---|---|
InvalidOperationException | No signing certificate configured. | Chế độ Certified, giấy phép trả phí, và không có chứng chỉ được truyền |
InvalidOperationException | The signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd. | Chế độ Certified với chứng chỉ nằm ngoài thời gian hiệu lực |
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. | Dữ liệu PNG rỗng, hoặc vị trí không hợp lệ |
NotSupportedException | The 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 ra | Chứng chỉ | Có thể xác minh |
|---|---|---|---|
SignatureMode.Certified (default) | Chữ ký hiển thị cộng với niêm phong kỹ thuật số | Yêu cầu khi có giấy phép trả phí | Có |
SignatureMode.Visual | Chỉ chữ ký hiển thị | Không bao giờ cần | Khô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, dành cho các khóa RSA hoặc ECDSA. Chúng mang theo các chứng chỉ phát hành được tìm thấy trong PFX của bạn, vì vậy một trình đọc tin cậy gốc 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 theo 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 ra | Hỗ 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 phong | Rộng: một PDF đã ký được xác minh ở mọi nơi |
WordOutput.Docx | Tài liệu vẫn ở dạng Word: hình ảnh chữ ký được chèn vào, cộng với chữ ký gói OOXML | Hạ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 bao C#, truyền chứng chỉ tới SignAsync. Cung cấp các byte hoặc một đường dẫn, cùng với mật khẩu:
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"],
};
});
});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ỉ có 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 dưới dạng 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 với 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 client. 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 dưới dạng 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, sang một tệp PFX.
Tạo một PFX từ chứng chỉ và khóa riêng bằng OpenSSL:
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 khi 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áo | Khắc phục |
|---|---|
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 .cer hoặc .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:
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:
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:
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 bao C# không được kiểm tra khi khởi động. Chứng chỉ bạn truyền tới SignAsync được đọc khi ký, vì vậy đường dẫn hoặc mật khẩu sai sẽ làm lệnh gọi đó 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 mặc định. Kích hoạt chúng bên cạnh việc đăng ký plugin:
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; để nó null cho ký demo (watermarked)
});
});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:
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 cung cấp, vì vậy tiện ích sẽ tải và vẽ vùng thả của nó, sau đó báo Signing is not enabled on this server. trong yêu cầu đầu tiên.
Nhúng nó
UseDoconutResources() cung cấp 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, không có phụ thuộc:
<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ý (Draw trên canvas, Type tên bằng phông chữ chữ ký, hoặc Image từ PNG, JPG hoặc GIF), kéo và thay đổi kích thước lên trang, sau đó 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 sẽ đượ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ọn | Kiểu | Mặc định | Ghi chú |
|---|---|---|---|
basePath | string | '/doconut' | Nơi các endpoint ?sign= và hình ảnh xem trước được cung cấp |
resPath | string | '/doconut-res' | Dành riêng; tiện ích gói kèm CSS của riêng nó |
maxUploadMb | number | 25 | Chỉ 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 |
maxSignatureKb | number | 512 | Giới hạn phía client cho chế độ Image. Giữ nó bằng với MaxSignatureImageKb của máy chủ |
previewWidth | number | 560 | Chiều rộng pixel của bản xem trước trang |
licenseUrl | string | null | null | Biến thông báo watermark demo thành liên kết tới URL này |
signatureMode | string | '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' |
showSignatureModeToggle | boolean | true | Hiển thị lựa chọn Digital signature / Visual only. Khi có false, tiện ích sẽ ký bằng signatureMode |
wordOutput | string | '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' |
showOutputFormatToggle | boolean | true | Hiển thị lựa chọn PDF / Word, chỉ cho các nguồn .docx. Khi có false, tiện ích sẽ sử dụng wordOutput |
labels | object | {} | 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:
// 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' });// Chỉ hiển thị, không có công tắc: một dấu đơn giản không cung cấp chữ ký số.
Doconut.signer('#host', {
basePath: '/doconut',
signatureMode: 'visual',
showSignatureModeToggle: false
});Các hàm gọi lại
| Hàm gọi lại | Khi nào kích hoạt | Dữ liệu |
|---|---|---|
onReady | Một lần, khi gắn (không lại khi reset()) | — |
onSourceLoaded | Tệp được mở và bản xem trước của nó được hiển thị | { file: { token, name, pages, ext } } |
onSigned | Ký thành công | { downloadToken, downloadName, watermarked } |
onDownload | Mỗi khi nhấn Download | { downloadName, downloadToken } |
onError | Bướ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 hàm gọi lại 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ức | Hành vi |
|---|---|
reset() | Trở về 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 làm gì sau destroy() |
loadFile(file) | Bắt đầu luồng với một File. Không làm 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 |
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 có mặc định tiếng Anh; labels ghi đè bất kỳ tập con 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 uploading: 'Uploading {name}…' và pages: '{n} pages'.
| Khóa | Mặc định tiếng Anh |
|---|---|
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 |
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 hiển thị signingNotEnabled. Lỗi JSON từ máy chủ luôn ư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ộ:
#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 cursive.
Xây dựng giao diện phía trước của 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 /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 bảng ghi "chỉ trạng thái". Một giá trị ?sign= không biết trả lời 400.
| Đường dẫn | Mục đích | Phả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ở để xem trước | 200 — { token, name, pages, ext } |
POST ?sign=run (body JSON) | Ký tệp đã tải lên | 200 — { 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 hiển thị trở thành placement.page.
Thân run:
{
"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ường | Ghi chú |
|---|---|
token | Mã token từ open |
signature.kind | Drawn, 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. Gợi ý: payload luôn là PNG |
signature.payload | Mộ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.page | Cơ sở 1 |
placement.x / y / w / h | Normalized 0..1 từ góc trên‑trái, với x + w ≤ 1 và y + h ≤ 1 |
meta.signerName / reason / location | Tù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ự |
wordOutput | pdf (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 |
mode | certified (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ý đều đượ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ẫn | Trạng thái | Khi | Nội dung |
|---|---|---|---|
| any | 404 | Widget không được bật | chỉ trạng thái |
| any | 405 | Động từ sai (open và run cần POST, download cần GET) | chỉ trạng thái |
open | 400 | Không phải tải lên đa phần | Expected a multipart file upload. |
open | 400 | Không có tệp, hoặc tệp rỗng | No file uploaded. |
open | 400 | Bất kỳ giá trị nào khác ngoài .pdf hoặc .docx | Signing supports PDF and Word (.docx) files only. |
open | 413 | Tải lên vượt quá MaxUploadMb | File is too large. |
run | 400 | Nội dung không phải JSON hợp lệ, hoặc rỗng | Malformed request. / Empty request. |
run | 400 | Token bị thiếu hoặc không phải GUID | Invalid token. |
run | 404 | Tải lên đã hết hạn hoặc chưa bao giờ được mở | Upload expired — please re-open the file. |
run | 400 | Không có chữ ký, hoặc không có vị trí | No signature supplied. / No placement supplied. |
run | 400 | Payload không phải base64, rỗng, quá lớn, hoặc không phải PNG | Signature image is not valid base64. / Signature image is empty. / Signature image is too large. / The signature image must be a PNG. |
run | 400 | Vị trí nằm ngoài trang | The signature or its placement is invalid. |
run | 400 | Chế độ chứng nhận, giấy phép trả phí và không có chứng chỉ | No signing certificate configured. |
run | 400 | Chế độ chứng nhận với chứng chỉ ngoài thời gian hiệu lực | The signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd. |
open, run | 500 | Xử lý thất bại | Một thông báo đã được làm sạch |
download | 400 | Token bị thiếu hoặc không phải GUID | chỉ trạng thái |
download | 404 | Token không biết hoặc đã hết hạn | chỉ trạng thái |
Một vòng trọn vẹn với fetch:
// 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 điểm cuối 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
-
Cài đặt plugin cạnh gói lõi, ở cùng phiên bản:
dotnet add package Doconut.NET6.Signer. -
Thêm tệp giấy phép. Đặt
Doconut.Viewer.Signer.lictrong cùng thư mục vớiDoconut.Viewer.lic. -
Lấy chứng chỉ của bạn dưới dạng PFX kèm 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ý.
-
Đọc chứng chỉ từ cấu hình, để việc thay đổi không bao giờ cần sửa mã:
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"] ?? "", }); });Giữ
.pfxở bên ngoàiwwwroot, và giữ mật khẩu ra khỏiappsettings.json: bí mật người dùng trong quá trình phát triển (dotnet user-secrets set "DoconutSigner:Password" "<password>"), biến môi trường (DoconutSigner__Password) hoặc một kho bảo mật trong môi trường sản xuất. -
Kiểm tra nhật ký 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 tưởng vào trình đọc PDF. Một trình đọc hiển thị chữ ký là hợp lệ khi nó tin tưởng vào 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 tưởng 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 tưởng trên bất kỳ máy nào (Danh sách Tin cậy Được Adobe Phê duyệt) theo như chúng tôi biết, đượ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.
Trang trại web
Widget giữ mỗi lần tải lên và kết quả của nó trong bộ nhớ trên nút đã phục vụ open. Đằng sau một bộ cân bằng tải mà không có phiên làm việc dính (sticky sessions), một yêu cầu run, download hoặc xem trước sau này có thể tới một nút khác và không tìm thấy lần tải lên. Đăng ký kho widget được chia sẻ và mã hóa một lần, sau AddDoconut():
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 trong bộ nhớ sẽ được sử dụng.
- Các lần tải lên và kết quả được mã hóa khi nghỉ trên chia sẻ (AES-256, encrypt-then-MAC), và mỗi tệp được liên kết 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.
FarmKeyphải có ít nhất 32 byte và giống nhau trên mọi nút. Tải nó từ kho bí mật; không bao giờ mã cứng. Đăng ký sẽ ném mộtArgumentExceptionkhiRootPathbị thiếu hoặcFarmKeyngắn hơn 32 byte.- Chỉ định
RootPathtới cùng vị trí chia sẻ mà trình xem phân tán sử dụng, và cung cấp cho mọi nút 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
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à nội bộ. 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 nước.
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
}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
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 được 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
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
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 các nguồn PDFSignResult
public sealed record SignResult(Stream Stream, string Extension);Tài liệu đã ký dưới dạng luồng có thể tìm kiếm, và phần mở rộng của nó kèm dấu chấm (".pdf" hoặc ".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 không rỗng, hoặc PfxPath không trống
}Đặt PfxBytes hoặc PfxPath, cộng thêm Password.
SignerWidgetOptions
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 dưới giấy phép trả phí.
Khắc phục sự cố
| Triệu chứng | Nguyên nhân | Cách khắc phục |
|---|---|---|
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 không có Signer, hoặc một giấy phép trả phí ngoài khung 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 chỉ tới một tệp bị thiếu | Sử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 tệp PKCS#12 | Kiể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êng | Xuất lại nó với khóa riêng |
Giải quyết 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 nước | Giấ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ạn | Thay 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ý Certified | Dò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 | Cấu hình SigningCertificate |
Widget tải nhưng nói 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ắn | Gọ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 MaxSignatureImageKb | Gửi một PNG base64 thuần trong giới hạn |
open trả lời 413 File is too large. | Việc tải lên vượt quá MaxUploadMb | Tăng 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ên | Mở 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 mang một 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 định | Trình đọc không tin tưởng gốc của chứng chỉ (chứng chỉ demo không bao giờ được tin cậy) | Sử dụng một chứng chỉ từ gốc mà trình đọc của bạn tin cậy |
| Widget thất bại khi UI ở nguồn khác | Các endpoint không hỗ trợ CORS | Phục vụ UI từ cùng nguồn, hoặc reverse-proxy các đường Doconut |
| Giao diện không áp dụng | Bộ chọn nhắm tới một phần tử bên trong mount | Nhắm tới chính mount: #host.dsw hoặc #host |
Trang này có hữu ích không?