Plugin ký

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ặtKhi nào sử dụng
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 trên DocImage.axd (?sign=open|run|download)Bạn xây dựng UI 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

powershell
Install-Package Doconut.NETFramework.Signer

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

powershell
Install-Package Doconut.NETFramework.Signer -Version 26.10.0

Giữ gói Signer ở cùng phiên bản với Doconut.NETFramework.

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.

Đăng ký plugin

Giống như mọi plugin Doconut, Signer đăng ký với AddPlugin<TPlugin>() trong DoconutHost.Initialize, được gọi từ Application_Start:

csharp
Doconut.DoconutHost.Initialize(options =>
{
    options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
    options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
});

Thêm Doconut.DoconutHost.Shutdown() vào Application_End để công việc nền dừng sạch sẽ khi pool ứng dụng được tái tạo.

Đó là tất cả những gì lớp mặt tiền C# cần. Widget và các endpoint HTTP của nó là một tùy chọn riêng, AddSignerWidget() (xem Tiện ích nhúng).

Plugin cần một giấy phép cung cấp khả năng Signer. Nếu không có, DoconutHost.Initialize sẽ ném lỗi từ Application_Start:

text
The Signer plugin is registered via AddPlugin but no active license grants Signer. Remove the AddPlugin<...>() call or install a license (or trial/demo) that includes Signer.

Trong System.Web điều này có nghĩa là mỗi yêu cầu trả về một 500 trống, và lý do chỉ có trong nhật ký sự kiện Windows (nguồn ASP.NET). 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ó. 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.

Cấp phép & dấu nước

Trạng thái giấy phépKhởi độngChữ ký đã xác thựcChữ ký hiển thị
Giấy phép trả phí cung cấp Signer, chứng chỉ đã cấu hìnhBắt đầuĐược niêm phong bằng chứng chỉ của bạn, sạch (watermarked: false)Sạch
Giấy phép trả phí cung cấp Signer, không có chứng chỉBắt đầuBị từ chối: No signing certificate configured.Sạch
Giấy phép trả phí, chứng chỉ đã hết hạn hoặc chưa hợp lệBắt đầuBị 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ạnBắ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ảnApplication_Start ném lỗi; mỗi yêu cầu trả về một 500 trống——

Quy tắc này giống nhau cho lớp mặt tiền 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 đều không được sử dụng.

Chứng chỉ demo tạo ra một con dấu thật, 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 tra toàn bộ trên một giấy phép đánh giá; để có đầu ra sạch và đáng tin cậy, bạn cần cả một 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 DoconutHost.Initialize; giải quyết nó từ DoconutHost.Services. 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>().

csharp
using Doconut;
using Doconut.Core.Models.Signing;

public sealed class ContractSigning
{
    private readonly DocumentSigner _signer;

    public ContractSigning(DocumentSigner signer) => _signer = signer;

    public async Task<byte[]> SignAsync(Stream pdf, byte[] signaturePng, SigningCertificate certificate, CancellationToken ct)
    {
        var request = new SignRequest(
            new VisibleSignature(SignatureKind.Drawn, signaturePng),
            new SignaturePlacement(Page: 1, X: 0.58, Y: 0.80, W: 0.32, H: 0.12),
            SignerName: "Ada Lovelace",
            Reason: "I approve this document",
            Location: "London, UK");
        // Mode mặc định là Certified (visible signature + digital seal); 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, 81920, 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. Truyền 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.

Trong một controller MVC 5

Biến hành động thành bất đồng bộ và await chữ ký. Cái này dán một chữ ký Visual, không cần chứng chỉ:

csharp
[HttpPost]
public async Task<ActionResult> Sign(HttpPostedFileBase file)
{
    var signer = Doconut.DoconutHost.Services.GetRequiredService<DocumentSigner>();
    byte[] signaturePng = System.IO.File.ReadAllBytes(Server.MapPath("~/App_Data/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(
        file.InputStream, Path.GetExtension(file.FileName), request, ct: Response.ClientDisconnectedToken);
    string contentType = result.Extension == ".pdf"
        ? "application/pdf"
        : "application/vnd.openxmlformats-officedocument.wordprocessingml.document";
    return File(result.Stream, contentType, Path.GetFileNameWithoutExtension(file.FileName) + "-signed" + result.Extension);
}

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:

csharp
var signer = Doconut.DoconutHost.Services.GetRequiredService<DocumentSigner>();
byte[] signaturePng = File.ReadAllBytes(HostingEnvironment.MapPath("~/App_Data/signature.png"));

var request = new SignRequest(
    new VisibleSignature(SignatureKind.Drawn, signaturePng),
    new SignaturePlacement(Page: 1, X: 0.58, Y: 0.80, W: 0.32, H: 0.12),
    WordOutput: WordOutput.Docx);

SignResult result = await signer.SignAsync(stream, ".docx", request, ct: ct);
string downloadName = "contract-signed" + result.Extension;   // ".docx"

SignAsync ném ngoại lệ thay vì trả về khi cuộc gọi không thể thành công:

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

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

Các chế độ ký

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

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

Sử dụng Certified khi chữ ký phải có thể chứng minh được: phê duyệt, hợp đồng, bất kỳ điều gì mà người xác minh cần kiểm tra để xác nhận 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ẽ đánh dấu mờ 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 raHỗ trợ xác minh
WordOutput.Pdf (mặc định)Tài liệu được chuyển đổi sang PDF, sau đó ký và niêm phongRộng: một PDF đã ký được xác minh ở mọi nơi
WordOutput.DocxTài liệu vẫn ở dạng Word: hình ảnh chữ ký được đặt vào, cộng thêm một chữ ký gói OOXMLHạn chế: không phải mọi trình xem đều hiển thị chữ ký gói OOXML

Giữ PDF trừ khi người nhận cần một tệp Word có thể chỉnh sửa và chấp nhận hỗ trợ 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) 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 hoặc là dữ liệu byte hoặc một đường dẫn, cùng với mật khẩu. App_Data là vị trí tốt cho tệp, vì IIS không bao giờ phục vụ nó:

csharp
Doconut.DoconutHost.Initialize(options =>
{
    options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
    options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
    options.AddSignerWidget(widget =>
    {
        widget.SigningCertificate = new SigningCertificate
        {
            PfxBytes = File.ReadAllBytes(HostingEnvironment.MapPath("~/App_Data/signing.pfx")),
            Password = System.Configuration.ConfigurationManager.AppSettings["DoconutSigner:Password"] ?? "",
        };
    });
});
csharp
Doconut.DoconutHost.Initialize(options =>
{
    options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
    options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
    options.AddSignerWidget(widget =>
    {
        widget.SigningCertificate = new SigningCertificate
        {
            PfxPath = HostingEnvironment.MapPath("~/App_Data/signing.pfx"),
            Password = System.Configuration.ConfigurationManager.AppSettings["DoconutSigner:Password"] ?? "",
        };
    });
});

Các thuộc tính của SigningCertificate là chỉ khởi tạo, mà C# 7.3 (mặc định cho các dự án .NET Framework) không thể đặt. Đặt <LangVersion> thành 9.0 hoặc phiên bản mới hơn trong tệp dự án.

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 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 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, nhưng chữ ký Certified sẽ bị từ chối cho đến khi được thay thế. Chữ ký Visual không bị ảnh hưởng.
  • Được cấp cho việc ký tài liệu: một mục đích khóa với chữ ký số hoặc không thể chối bỏ, 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 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 PFX.

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

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

Xuất một từ 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 DoconutHost.Initialize, 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 từ Application_Start, và mỗi yêu cầu sau đó trả về một 500 trống; thông báo nằm trong nhật ký sự kiện Windows:

Thông điệpSử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 app pool
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

Trên ASP.NET Core, host cũng ghi một dòng khi khởi động để chỉ tên chứng chỉ, hoặc cảnh báo rằng nó đã hết hạn hoặc không được cấp để ký. DoconutHost không ghi dòng đó, vì vậy trên .NET Framework hãy kiểm tra một chứng chỉ mới bằng cách ký một tài liệu thử nghiệm ở chế độ Certified.

Facade 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ẽ khiến lời gọi đó thất bại.

Widget dạng Drop-in

Kích hoạt các endpoint

Các endpoint ?sign=open|run|download của widget được phục vụ bởi DocImage.axd và mặc định là tắt. Kích hoạt chúng bên cạnh việc đăng ký plugin:

csharp
Doconut.DoconutHost.Initialize(options =>
{
    options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/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ấu hình Certificate; để null cho ký demo (có watermark)
    });
});
// System.Web đọc toàn bộ tệp tải lên trước khi Doconut thấy nó: giữ maxRequestLength (KB) và
// maxAllowedContentLength (bytes) trong Web.config phía trên MaxUploadMb của widget.

AddSignerWidget() không có đối số sẽ kích hoạt widget với các giá trị mặc định. Nó không tự cấp quyền ký: nó cần AddPlugin<SignerPlugin>(), hoặc DoconutHost.Initialize sẽ ném:

text
AddSignerWidget() was called but the Signer plugin is not registered. Add options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>() (the widget needs it), or remove the AddSignerWidget() call.

Các endpoint và script được phục vụ bởi handler và module đã đăng ký trong Web.config:

xml
<system.webServer>
  <handlers>
    <add name="DocImage" verb="GET,HEAD,POST" path="DocImage.axd" type="Doconut.DocImageHandler, Doconut" />
  </handlers>
  <modules>
    <add name="DoconutResources" type="Doconut.DoconutResourceModule, Doconut" />
  </modules>
</system.webServer>

Module cung cấp script bất kể widget có được bật hay không. Nếu không có AddSignerWidget(), widget sẽ tải và vẽ vùng thả của nó, và yêu cầu đầu tiên sẽ trả lời 404: widget sau đó báo cáo Signing is not enabled on this server.

Giới hạn tải lên

ASP.NET đọc toàn bộ nội dung yêu cầu trước khi DocImage.axd chạy. Một tải lên vượt quá MaxUploadMb nhưng dưới giới hạn của host sẽ nhận được JSON 413 riêng của widget (File is too large.). Một tải lên vượt quá giới hạn của host sẽ bị IIS từ chối trước, kèm trang lỗi mà widget không thể đọc. Giữ cả hai giới hạn của host ở mức cao hơn mức tối đa của widget:

xml
<system.web>
  <httpRuntime maxRequestLength="30720" />           <!-- KILOBYTES: 30 MB -->
</system.web>
<system.webServer>
  <security>
    <requestFiltering>
      <requestLimits maxAllowedContentLength="31457280" />  <!-- BYTES: 30 MB -->
    </requestFiltering>
  </security>
</system.webServer>

Một tải lên được gửi mà không có Content-Length (chunked) và vượt quá giới hạn của host cũng sẽ nhận được trang lỗi của IIS; không có cách khắc phục cho trường hợp này.

Nhúng

Script được phục vụ tại /doconut-res/js/doconutSigner.js. Nó là một tệp duy nhất, tự chứa và không có phụ thuộc. Đặt basePath vào trình xử lý:

html
<div id="host"></div>
<script src="/doconut-res/js/doconutSigner.js"></script>
<script>
  const handle = Doconut.signer('#host', { basePath: '/DocImage.axd' });
</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. basePath mặc định của widget, /doconut, là endpoint ASP.NET Core; trên gói này nó phải là '/DocImage.axd'.

Người ký tải lên một tệp PDF hoặc .docx, tạo chữ ký (Draw trên canvas, Type một 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ả. Widget luôn gửi chữ ký dưới dạng PNG; hình ảnh đã tải lên được chuyển đổi trong trình duyệt thành PNG có kích thước 520×160.

Tùy chọn

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

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

javascript
// Cả hai công tắc đều được hiển thị, chữ ký số mặc định: một công cụ ký tự tự phục vụ đầy đủ.
Doconut.signer('#host', { basePath: '/DocImage.axd', licenseUrl: '/pricing' });
javascript
// Chỉ hiển thị hình ảnh, 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: '/DocImage.axd',
  signatureMode: 'visual',
  showSignatureModeToggle: false
});

Các callback

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

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

Truy cập mệnh lệnh

Phương thứcHành vi
reset()Quay lại màn hình thả và xóa luồng hiện tại. Không kích hoạt lại onReady. Không thực hiện gì sau destroy()
loadFile(file)Bắt đầu luồng với một File. Không thực hiện gì nếu widget không ở màn hình thả; nếu cần, gọi reset() trước
destroy()Xóa các listener, làm trống mount, và đóng băng instance
javascript
const signerWidget = Doconut.signer('#host', {
  basePath: '/DocImage.axd',
  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 như uploading: 'Uploading {name}…' và pages: '{n} pages'.

KhóaMặc định tiếng Anh
dropPromptDrag & drop a PDF or Word file here
dropHintPDF or Word (.docx)
chooseFileChoose file
signatureHeadingYour signature
modeDraw / modeType / modeImageDraw / Type / Image
metaSummarySignature details (optional)
metaSignerName / metaReason / metaLocationSigner name / Reason / Location
signatureTypeSignature type
modeCertified / modeVisualDigital signature / Visual only
modeVisualNoteNo certificate — a visible mark only, not cryptographically verifiable.
outputFormatOutput format
outputPdf / outputWordPDF / Word (.docx)
signActionSign document
downloadDownload
demoNoticeDemo — signed with the Doconut demo certificate; output is watermarked.
signingNotEnabledSigning is not enabled on this server.
page / pages1 page / {n} pages

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

Khi open hoặc run trả lời 404 mà không có lỗi JSON, widget 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ử gắn kết 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 bên trong:

css
#host.dsw {
  --dsw-accent: #b0522b;       /* liên kết, tiêu điểm, chế độ hoạt động */
  --dsw-bg: #fffaf3;
  --dsw-fg: #3b2a1a;
  --dsw-muted: #8a7a68;
  --dsw-border: #e0cbb0;
  --dsw-radius: 14px;
  --dsw-font: Georgia, "Times New Roman", serif;
  --dsw-signature-font: "Segoe Script", "Brush Script MT", cursive;   /* chế độ Type */
}

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

Xây dựng giao diện phía máy khách của bạn

Widget là một client cho hợp đồng HTTP này trên DocImage.axd. Các đường dẫn trả lời 404 cho đến khi AddSignerWidget() được gọi. Lỗi mang theo một thân 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ẫnMục đíchPhản hồi thành công
POST /DocImage.axd?sign=open (multipart, một tệp)Tải lên một PDF hoặc .docx và mở để xem trước200 — { token, name, pages, ext }
POST /DocImage.axd?sign=run (JSON body)Ký tệp đã tải lên200 — { downloadToken, downloadName, watermarked }
GET /DocImage.axd?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 trình xem tiêu chuẩn, /DocImage.axd?token={token}&page={n}&thumb=1&width={px}; trang được hiển thị trở thành placement.page.

Thân run:

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

downloadName theo đầu ra: <source>-signed.pdf hoặc <source>-signed.docx, và download gửi Content-Type phù hợp.

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ả các token đều là GUID.

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

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

javascript
// file: tệp File để 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 = '/DocImage.axd';

  // 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 từ cùng một nguồn gốc với ứng dụng, hoặc reverse-proxy DocImage.axd và /doconut-res dưới nguồn gốc UI của bạn.

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

  1. Cài đặt plugin bên cạnh gói core, ở cùng phiên bản: Install-Package Doconut.NETFramework.Signer.

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

  3. Lấy chứng chỉ của bạn dưới dạng PFX kèm theo 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ử nghiệm 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ý.

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

    xml
    <appSettings>
      <add key="DoconutSigner:PfxPath" value="~/App_Data/your-certificate.pfx" />
    </appSettings>
    csharp
    var settings = System.Configuration.ConfigurationManager.AppSettings;
    
    Doconut.DoconutHost.Initialize(options =>
    {
        options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
        options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
        options.AddSignerWidget(widget => widget.SigningCertificate = new SigningCertificate
        {
            PfxPath = HostingEnvironment.MapPath(settings["DoconutSigner:PfxPath"]),
            Password = settings["DoconutSigner:Password"] ?? "",
        });
    });

    Giữ .pfx trong App_Data, nơi IIS không bao giờ phục vụ, và giữ mật khẩu ra khỏi một Web.config thuần: sử dụng một phần cấu hình được mã hoá, hoặc một kho bí mật mà quá trình triển khai của bạn đọc.

  5. Ký một tài liệu thử nghiệm ở chế độ Certified. Một chứng chỉ đã hết hạn hoặc chưa có hiệu lực sẽ bị từ chối với The signing certificate expired on yyyy-MM-dd. (hoặc is not valid before), và một trình đọc PDF sẽ hiển thị liệu nó có tin cậy chữ ký hay không.

Tin cậy trong trình đọc PDF. Một trình đọc sẽ 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 trên 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 phát hành 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. Hãy 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.

Môi trường web farm

Widget giữ mỗi lần tải lên và kết quả của nó trong bộ nhớ trên máy chủ đã phục vụ open. Khi đứng sau một bộ cân bằng tải mà không có sticky sessions, 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 máy chủ 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á thông qua đối số thứ hai của DoconutHost.Initialize:

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

Doconut.DoconutHost.Initialize(
    options =>
    {
        options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
        options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
        options.AddSignerWidget();
    },
    services => services.AddDoconutDistributedWidgets(store =>
    {
        store.RootPath = @"\\fileshare\doconut";   // một thư mục mà mọi máy chủ có thể đọc và ghi
        store.FarmKey = farmKey;                   // ít nhất 32 byte, giống nhau trên mọi máy chủ
        // 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 gọi lệnh 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ã hoá khi nghỉ trên chia sẻ (AES-256, encrypt-then-MAC), và mỗi tệp được gắn với token của nó, vì vậy một token không bao giờ có thể đọc tệp của token khác.
  • FarmKey phải có ít nhất 32 byte và giống nhau trên mọi máy chủ. Tải nó từ một kho bí mật; không bao giờ hard-code. Đăng ký sẽ ném một ArgumentException khi RootPath bị thiếu hoặc FarmKey ngắn hơn 32 byte.
  • Đặt RootPath tới cùng một vị trí chia sẻ mà trình xem phân tán sử dụng, và cung cấp cho mọi máy chủ cùng một chứng chỉ ký.

Tham chiếu API

Facade và các tùy chọn widget nằm trong không gian tên Doconut; các kiểu yêu cầu và kết quả nằm trong Doconut.Core.Models.Signing. SignerPlugin nằm trong Doconut.Plugins.Signer.

DocumentSigner

csharp
public sealed class DocumentSigner
{
    public Task<SignResult> SignAsync(
        Stream source, string sourceExtension, SignRequest request,
        SigningCertificate? cert = null, CancellationToken ct = default);
}

Được giải quyết từ DoconutHost.Services; 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ó watermark.

SignRequest

csharp
public sealed record SignRequest(
    VisibleSignature   Signature,
    SignaturePlacement Placement,
    string?            SignerName = null,
    string?            Reason     = null,
    string?            Location   = null,
    WordOutput         WordOutput = WordOutput.Pdf,
    SignatureMode      Mode       = SignatureMode.Certified)
{
    public bool IsValid { get; }   // Signature.IsValid && Placement.IsValid
}

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

VisibleSignature và SignatureKind

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

public enum SignatureKind { Drawn, Typed, Image }

PngBytes là một PNG cho mọi loại. 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 một JPG không trong suốt vẫn không trong suốt. Kind chỉ là một gợi ý.

SignaturePlacement

csharp
public readonly record struct SignaturePlacement(int Page, double X, double Y, double W, double H)
{
    public bool IsValid { get; }   // Page >= 1; X, Y >= 0; W, H > 0; X + W <= 1; Y + H <= 1
}

Page bắt đầu từ 1; X, Y, W và H được chuẩn hoá 0..1 từ góc trên‑trái.

SignatureMode và WordOutput

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

SignResult

csharp
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

csharp
public sealed class SigningCertificate
{
    public byte[]? PfxBytes { get; init; }
    public string? PfxPath  { get; init; }
    public string  Password { get; init; } = "";
    public bool    HasMaterial { get; }   // PfxBytes không rỗng, hoặc PfxPath không trống
}

Đặt PfxBytes hoặc PfxPath, cộng với Password. Các setter chỉ có thể init: dự án cần C# 9.0 hoặc cao hơn.

SignerWidgetOptions

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

Đặt qua DoconutOptions.AddSignerWidget(Action<SignerWidgetOptions>? configure = null), nó trả về DoconutOptions để các lời gọi có thể được xâu 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ứngNguyên nhânKhắc phục
Mỗi yêu cầu trả về một 500 trống sau khi thêm plugin; nhật ký sự kiện hiển thị 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 giấy phép trả phí ngoài 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>()
Nhật ký sự kiện hiển thị 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>()
Nhật ký sự kiện hiển thị Doconut Signer: the certificate file was not found at '{path}'.PfxPath trỏ tới một tệp bị thiếuSửa đường dẫn; triển khai tệp ở nơi tài khoản app pool có thể đọc được
Nhật ký sự kiện hiển thị 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#12Kiểm tra mật khẩu; sử dụng một .pfx thực
Nhật ký sự kiện hiển thị Doconut Signer: the signing certificate has no private key. Re-export the .pfx INCLUDING the private key.PFX đã được xuất mà không có khóa riêngXuất lại với khóa riêng
new SigningCertificate { … } không biên dịchDự án sử dụng C# 7.3, không thể đặt thuộc tính chỉ initĐặt <LangVersion> thành 9.0 hoặc cao hơn
Giải quyết DocumentSigner gây ra No IDocumentSigner is registered.SignerPlugin chưa được đăng kýThêm AddPlugin<SignerPlugin>() trong DoconutHost.Initialize
Đầu ra có watermarkGiấy phép là tạm thời (Demo/NFR)Sử dụng giấy phép trả phí cho phép Signer
run trả lời 400 No signing certificate configured.Giấy phép trả phí, chế độ Certified, và không có chứng chỉCấu hình SigningCertificate, hoặc ký ở chế độ Visual
run trả lời 400 The signing certificate expired on yyyy-MM-dd.Chứng chỉ đã hết hạnThay thế nó; chữ ký Visual vẫn hoạt động trong thời gian này
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 phải là '/DocImage.axd'Gọi AddSignerWidget(); đặt basePath: '/DocImage.axd'
Tải lên lớn hiển thị trang lỗi IIS thay vì thông báo của widgetmaxRequestLength / maxAllowedContentLength dưới MaxUploadMbTăng cả hai giới hạn host lên trên MaxUploadMb
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.Giao diện tùy chỉnh gửi một URL data:, một JPG, hoặc hơn MaxSignatureImageKbGửi một PNG base64 thuần trong giới hạn
open trả lời 413 File is too large.Tải lên vượt quá MaxUploadMbTă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áy chủ khác trong farm không có tệp tải lênMở lại tệp; trong 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 cho biết danh tính người ký không xác địnhTrình đọc không tin cậy gốc của chứng chỉ (chứng chỉ demo không bao giờ được tin cậy)Sử dụng chứng chỉ từ một gốc mà trình đọc của bạn tin cậy
Widget thất bại khi UI ở nguồn khácCác endpoint không hỗ trợ CORSPhục vụ UI từ cùng nguồn, hoặc reverse-proxy DocImage.axd và /doconut-res
Giao diện không áp dụngSelector nhắm tới một phần tử bên trong mountNhắm tới chính mount: #host.dsw hoặc #host

Ghi chú khung

  • Đăng ký nằm trong Application_Start, thông qua DoconutHost.Initialize, thay vì builder.Services.AddDoconut. Các dịch vụ như AddDoconutDistributedWidgets được đưa vào đối số thứ hai của nó.
  • Các điểm cuối được phục vụ bởi DocImage.axd và script bởi DoconutResourceModule, cả hai đều được đăng ký trong Web.config, thay vì UseDoconut() và UseDoconutResources(). Widget cần basePath: '/DocImage.axd'.
  • Lỗi khởi động xuất hiện dưới dạng một 500 trống trên mỗi yêu cầu, với lý do được ghi trong nhật ký sự kiện Windows.
  • Tải lên được ASP.NET đọc toàn bộ trước khi Doconut xử lý, vì vậy các giới hạn IIS phải lớn hơn MaxUploadMb.
  • Không có dòng nhật ký khởi động về chứng chỉ: ba lỗi chứng chỉ vẫn được ném ra, nhưng dòng ghi tên chứng chỉ không được viết.
  • C# 9.0 hoặc mới hơn cần thiết để thiết lập các thuộc tính chỉ‑init của SigningCertificate.
  • Chỉ Windows, như phần còn lại của gói .NET Framework.

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