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ện | Sử 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:
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:
dotnet add package Doconut.NET8.Signer --version 26.10.0Giữ 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ở:
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>() bên 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 đ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:
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é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 hiệu lực | 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, 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 không có 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ử đầ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>().
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ỉ:
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:
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 một chứng chỉ nằm ngoài khoảng 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 một 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, 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 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 thực ở 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 thêm 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 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:
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ỉ 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:
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áo | Sử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:
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 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:
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.
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:
<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ọ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 phục vụ |
resPath | string | '/doconut-res' | Dành riêng; tiện ích đóng gói CSS riêng của 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 demo-watermark 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 Chữ ký kỹ thuật số / Chỉ hiển thị. Với false, tiện ích 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ỉ dành cho các nguồn .docx. Với false, tiện ích 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 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
| Callback | Kích hoạt khi | Dữ liệu |
|---|---|---|
onReady | Một lần, khi mount (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 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ức | Hà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 |
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óa | Giá trị 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 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ộ:
#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ẫ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ở nó để 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 được 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. Chỉ là 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 | bắt đầu từ 1 |
placement.x / y / w / h | 0..1 đã chuẩn hoá 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ý 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ẫn | Trạng thái | Khi | Nội dung |
|---|---|---|---|
| any | 404 | Widget không được bật | chỉ trạng thái |
| any | 405 | Sai động từ (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 | Body 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 xác định hoặc đã hết hạn | chỉ trạng thái |
Một vòng tròn hoàn chỉnh 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 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
-
Cài đặt plugin bên cạnh gói core, ở cùng phiên bản:
dotnet add package Doconut.NET8.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 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ý.
-
Đọ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" }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ữ
.pfxbên ngoàiwwwroot, và giữ mật khẩu ra khỏiappsettings.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. -
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():
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.
FarmKeyphả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ộtArgumentExceptionkhiRootPathbị thiếu hoặcFarmKeyngắn hơn 32 byte.- Đặt
RootPathtớ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
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
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 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 nguồn PDFSignResult
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
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
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ứng | Nguyên nhân | Giả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ế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 là 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 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 watermark | 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 nào | Cấ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ắ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. | Tải lên vượt quá MaxUploadMb | Khai 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ê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 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 định | Trì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á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 vào một phần tử bên trong mount | Nhắm vào chính mount: #host.dsw hoặc #host |
Trang này có hữu ích không?