Plugin Signer
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ị trê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ý.
| Bề mặt | Khi nào sử dụng |
|---|---|
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 tự xây dựng giao diện ký của 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.NETStandard.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.NETStandard.Signer --version 26.10.0Giữ gói Signer ở cùng phiên bản với Doconut.NETStandard. ID gói là Doconut.NETStandard.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.
Đă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 C# cần. Widget và các endpoint 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ụ 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ó sẽ 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ó. Các 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 nước
| Trạng thái giấy phép | Khởi động | Chữ ký đã xác thực | 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 có 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, đ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ó dấu nước (watermarked: true) | Có dấu nước |
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 C# và widget: đầu ra sẽ có dấu nước 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 sự, nhưng các trình đọc PDF không tin cậy nó. Một tích hợp có thể được xây dựng và thử nghiệm toàn bộ trên một 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");
// Chế độ 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 này: 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);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 cho 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ỉ 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 dưới 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 kiểm tra cần xác minh danh tính và tính toàn vẹn. Sử dụng Visual khi bạn chỉ cần hình dạng của chữ ký, hoặc không có chứng chỉ. Giấy phép tạm thời sẽ đánh dấu watermark cho 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 mang theo các chứng chỉ phát hành có trong PFX của bạn, vì vậy một trình đọc tin tưởng 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ỉ 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 đó được 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 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ấu hình 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) bao gồm khóa riêng. Đối với widget, đặt SignerWidgetOptions.SigningCertificate; đối với lớp C#, truyền chứng chỉ cho 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 hoặc 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 là Cảnh báo khi khởi động, và các chữ ký Được chứng nhận bị từ chối cho đến khi thay thế. Các chữ ký Visual không bị ảnh hưởng.
- Được cấp để 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. Một chứng chỉ được cấp cho mục đích khác, như chứng chỉ máy chủ TLS, vẫn có thể ký, nhưng nó được ghi log là Cảnh báo và các trình đọc PDF sẽ đánh dấu chữ ký.
- 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 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ừ 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 | Cách 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 là .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 để 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. Với 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 C# không được kiểm tra khi khởi động. Chứng chỉ bạn truyền cho 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 cuộc gọi đó thất bại.
Tiện ích nhúng sẵn
Kích hoạt các endpoint
Các endpoint ?sign=open|run|download của widget mặc định là tắt. 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 Cài đặt Chứng chỉ; để nó null cho việc ký demo (có dấu nước)
});
});AddSignerWidget() không có đối số sẽ kích hoạt widget 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 phục vụ, vì vậy widget sẽ tải và vẽ vùng thả của nó, sau đó báo cáo Signing is not enabled on this server. trong yêu cầu đầu tiê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, 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 selector 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 từ PNG, JPG hoặc GIF), kéo và thay đổi kích thước lên trang, và ký rồi tải xuống kết quả. Widget 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 phục vụ |
resPath | string | '/doconut-res' | Dành riêng; widget 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 Digital signature / Visual only. Khi có false, widget 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. Khi có false, widget 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 hiển thị, chữ ký số mặc định: một người ký tự phục vụ tự động đầ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 hàm gọi lại
| Hàm gọi lại | Khi nào được kích hoạt | Dữ liệu |
|---|---|---|
onReady | Một lần, khi gắn (không lặp lại trên 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 Tải xuống | { downloadName, downloadToken } |
onError | Bước mở, ký hoặc tải xuống thất bại, hoặc tệp ở chế độ Hình ảnh quá lớn | { message } |
Một hàm gọi lại ném lỗi sẽ được bắt và ghi lại; 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 tiện ích đang ở màn hình thả; gọi reset() trước nếu cần |
destroy() | Xóa các listener, làm trống phần gắn, 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ột giá trị mặc định 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 | 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, tiện ích 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
Tiện ích thêm lớp dsw vào phần tử gắn của nó 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 can thiệp 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ữ ký dạng viết tay.
Xây dựng giao diện phía trước của bạn
Tiện ích là một khách hàng cho hợp đồng HTTP này. Ba đường dẫn đề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ừ nơi bảng ghi chỉ trạng thái. Một giá trị ?sign= không xác định 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 (định dạng 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.
Phần 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 trim, 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 | Thân |
|---|---|---|---|
| any | 404 | Tiện ích không được bật | chỉ trạng thái |
| any | 405 | Phương thức HTTP 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 .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 | Thân 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 vẹn với fetch:
// file: Tệp cần 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. Hãy 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.NETStandard.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, hãy 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 nó 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 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 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 (Danh sách Tin cậy Được Adobe Phê duyệt) theo hiểu biết của chúng tôi, được cấp với khóa riêng trên 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 đó.
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 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, một yêu cầu run, download hoặc yêu cầu xem trước sau này có thể tới một nút khác và không tìm thấy 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ó lời gọi này, kho lưu trong bộ nhớ sẽ được sử dụng.
- Các tải lên và kết quả được mã hoá khi nghỉ trên chia sẻ (AES-256, encrypt-then-MAC), và mỗi tệp được ràng buộc 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.- Đặt
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.
Trình ký tài liệu
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". Với giấy phép trả phí, cert được sử dụng và đầu ra sạch; với 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ó watermark.
Yêu cầu ký
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 thêm siêu dữ liệu người ký tùy chọn.
Chữ ký hiển thị và Loại chữ ký
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. Một chữ ký được vẽ hoặc gõ là trong suốt; hình ảnh tải lên giữ độ trong suốt ban đầu, vì vậy JPG không trong suốt vẫn không trong suốt. Kind chỉ là một gợi ý.
Vị trí chữ ký
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.
Chế độ chữ ký và Đầu ra Word
public enum SignatureMode { Certified, Visual } // Certified là mặc định
public enum WordOutput { Pdf, Docx } // Pdf là mặc định; bị bỏ qua cho các nguồn PDFKết quả ký
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").
Chứng chỉ ký
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
}Có thể đặt PfxBytes hoặc PfxPath, cộng thêm Password.
Tùy chọn widget người ký
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 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ài đặt một giấy phép cung cấ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 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 |
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ó watermark | Giấy phép là tạm thời (Demo/NFR) | Sử dụng giấy phép trả phí cung cấ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 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. | 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 cho biết 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) | Sử dụng chứng chỉ từ một gốc mà trình đọc của bạn tin tưởng |
| 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 |
| Theme không áp dụng | Selector 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?