サイナープラグイン

可視署名とデジタルシールで PDF と Word 文書に署名

Signer プラグインは文書に可視署名を配置し、デフォルトで PDF リーダーが検証できるデジタル署名でシールします。PDF と Word (.docx) ファイルに署名します。可視署名は常に PNG 画像で、描画、入力、または署名者がアップロードしたものです。

対象使用シーン
DocumentSigner (C#)サーバー上で署名し、ブラウザは関与しません
Drop-in widget (doconutSigner.js)ページ内にアップロード、署名、ダウンロード画面がすぐに使えるウィジェットが欲しい
HTTP endpoints (?sign=open|run|download)文書化されたサーバー契約に基づいて独自の署名 UI を構築したい

各署名は1ページに1回だけ配置されます。署名者の名前、理由、場所はそれと共に保持されます。

パッケージのインストール

最新の安定版 Signer プラグインをインストールします:

bash
dotnet add package Doconut.NET8.Signer

このドキュメントで説明しているリリースにプラグインを固定するには、バージョンを別途指定します:

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

Doconut.NET8 と同じバージョンで Signer パッケージを保ちます。パッケージ ID は Doconut.NET8.Signer です。.<version> はダウンロードされた .nupkg のファイル名にのみ現れます。

プラグインのライセンスファイル Doconut.Viewer.Signer.lic は Doconut.Viewer.lic と同じフォルダーに配置します。ビューアのライセンスと共に読み込まれます。

プラットフォーム。 プラグインは Doconut.NET8 が動作する場所ならどこでも動作します:Windows と x64 の glibc ベース Linux(Alpine や他の musl ベースディストリビューションは除く)。Linux では、最初の文書を開く前にフォント設定ライブラリをインストールしてください:

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

RHEL、Fedora などの類似ディストリビューションではパッケージは fontconfig です。これがないと、文書を開く際に The system library libfontconfig1 is missing. Install it (Debian/Ubuntu: apt-get install -y libfontconfig1) and see the Linux section of the Doconut documentation. が発生します。

プラグインの登録

すべての Doconut プラグインと同様に、Signer は AddDoconut() 内の AddPlugin<TPlugin>() に登録します:

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

これが C# ファサードに必要なすべてです。ウィジェットとその HTTP エンドポイントは別途オプトインで、AddSignerWidget() です(ドロップインウィジェット を参照)。

プラグインは Signer 機能を付与するライセンスが必要です。これがないと、AddDoconut() はアプリがリクエストを処理する前の起動時に例外をスローします:

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.

ライセンスがない場合、レガシー TRIAL ファイルがある場合、Signer が含まれないライセンス、またはバージョン期間外の有料ライセンスを使用した場合に例外がスローされます。Temporary Demo/NFR ライセンスは受け入れられます。ライセンスのロード方法については ライセンス設定 を参照してください。

ライセンスと透かし

ライセンス状態起動時認証署名可視署名
Signer を付与する有料ライセンス、証明書が設定済み起動証明書でシールされ、クリーン(watermarked: false)クリーン
Signer を付与する有料ライセンス、証明書なし起動Refused: No signing certificate configured.クリーン
有料ライセンス、証明書が期限切れまたはまだ有効でない起動(ウィジェットが有効で、警告がログに記録されます)Refused: The signing certificate expired on yyyy-MM-dd.クリーン
一時的な Demo/NFR ライセンス、アクティブまたは期限切れ起動組み込みデモ証明書でシールされ、透かし付き(watermarked: true)透かし付き
ライセンスなし、レガシー TRIAL ファイル、Signer がないライセンス、またはバージョン期間外の有料ライセンスAddDoconut() がスロー——

この規則は C# ファサードとウィジェットの両方に同じです:ライセンスが有料ビューアライセンスでないか、一時的な場合、出力に透かしが付けられます。一時的なライセンスの場合、プラグインは常に組み込みデモ証明書で署名し、設定した証明書は使用されません。

デモ証明書は本物のシールを生成しますが、PDF リーダーはそれを信頼しません。評価ライセンスでエンドツーエンドの統合を構築・テストできますが、クリーンで信頼できる出力を得るには有料ライセンスと独自の 署名証明書 の両方が必要です。

C#からの使用

DocumentSigner は AddDoconut() によって登録され、依存性注入から解決されます。そのコンストラクタは internal なので、決して new しないでください。AddPlugin<SignerPlugin>() なしで解決しようとすると 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 はデフォルトで Certified(可視署名 + デジタルシール)に設定されます; WordOutput はデフォルトで 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 はソースストリーム、その拡張子(".pdf" または ".docx")、リクエスト、そして証明書 この呼び出し用 を受け取ります。ファサードは SignerWidgetOptions.SigningCertificate を読み取りません;その設定はウィジェット用です。デモライセンス下、または Visual モードで null を渡してください。

SignResult は署名済みドキュメントをシーク可能なストリームとして保持し、さらにその Extension(".pdf" または ".docx")を保持するので、ファイル名を付けることができます。ストリームはあなたの所有です:使用後は破棄してください。

Visual 署名は画像のみをスタンプし、証明書は不要です:

csharp
var signer = app.Services.GetRequiredService<DocumentSigner>();
byte[] signaturePng = File.ReadAllBytes("signature.png");

var request = new SignRequest(
    new VisibleSignature(SignatureKind.Image, signaturePng),
    new SignaturePlacement(Page: 1, X: 0.58, Y: 0.80, W: 0.32, H: 0.12),
    Mode: SignatureMode.Visual);

SignResult result = await signer.SignAsync(stream, ".pdf", request, ct: ct);

Word ソースは、Word 出力を要求しない限り PDF に署名されます。結果は result.Extension から名前付けしてください:

csharp
var signer = app.Services.GetRequiredService<DocumentSigner>();
byte[] signaturePng = File.ReadAllBytes("signature.png");

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

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

SignAsync は呼び出しが成功しない場合に返す代わりに例外をスローします:

例外メッセージ条件
InvalidOperationExceptionNo signing certificate configured.認証モード、課金ライセンス、かつ証明書が渡されていない場合
InvalidOperationExceptionThe signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd.有効期限外の証明書がある認証モード
ArgumentExceptionThe sign request is invalid: the visible signature needs PNG bytes and the placement must be a normalized rectangle on a 1-based page.空の PNG バイト、または無効な配置
NotSupportedExceptionThe signer supports PDF and Word (.docx) documents; got '{extension}'.その他のすべてのソースタイプ

署名モード、Word 出力と証明書

署名モード

SignRequest.Mode は署名がシールされるかどうかを選択します。

モード生成物証明書検証可能
SignatureMode.Certified (デフォルト)可視署名とデジタルシール課金ライセンス下で必須はい
SignatureMode.Visual可視署名のみ不要いいえ:画像です

Certified を使用するのは、署名が証明可能である必要がある場合です:承認、契約、検証者が身元と完全性を確認するために必要なすべて。Visual を使用するのは、署名の外観だけが必要な場合、または証明書がない場合です。臨時ライセンスは両方に透かしを入れます。

PDF シールは PKCS#7 デタッチド署名(adbe.pkcs7.detached)で、SHA-256、RSA または ECDSA 鍵用です。PFX に含まれる発行者証明書を保持するため、ルートを信頼するリーダーはチェーンを構築できます。Word ネイティブのシールは OOXML パッケージ署名で、署名者証明書のみを保持します。

Word ドキュメント

.docx ソースの場合、SignRequest.WordOutput が出力を選択します。PDF ソースでは無視され、常に PDF が生成されます。

出力何が起こるか検証者サポート
WordOutput.Pdf (default)ドキュメントは PDF に変換され、署名されシールが付与されます広範囲: 署名された PDF はどこでも検証可能
WordOutput.Docxドキュメントは Word のままで、署名画像が配置され、さらに OOXML パッケージ署名が付加されます限定的: すべてのビューアが OOXML パッケージ署名を表示するわけではありません

受信者が編集可能な Word ファイルを必要とし、限定的な検証者サポートを受け入れる場合を除き、PDF を使用してください。

証明書の設定

自分の身元でシールを作成するには、プライベートキーを含む PFX (PKCS#12) ファイルをプラグインに提供します。ウィジェットの場合は SignerWidgetOptions.SigningCertificate を設定し、C# ファサードの場合は証明書を SignAsync に渡します。バイト列またはパスのいずれかと、パスワードを提供してください:

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
    options.AddSignerWidget(widget =>
    {
        widget.SigningCertificate = new SigningCertificate
        {
            PfxBytes = File.ReadAllBytes("/secure/signing.pfx"),
            Password = builder.Configuration["Signing:PfxPassword"],
        };
    });
});
csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
    options.AddSignerWidget(widget =>
    {
        widget.SigningCertificate = new SigningCertificate
        {
            PfxPath = "/secure/signing.pfx",
            Password = builder.Configuration["Signing:PfxPassword"],
        };
    });
});

証明書はメモリ内にのみ保持されます。ログに記録されたり、クライアントに返されたり、永続化されたりすることはなく、パスワードがログ行やエラーメッセージに表示されることもありません。

要件:

  • PFX / PKCS#12 バンドル プライベートキー付き。公開鍵のみのファイル(.cer、.crt)では署名できません。発行者チェーンもエクスポートし、PDF シールがそれを保持できるようにしてください。
  • 正しいパスワード。
  • 有効期間内であること。期限切れまたはまだ有効でない証明書はアプリの動作を停止させません:起動時に Warning としてログに記録され、置き換えられるまで Certified 署名は拒否されます。Visual 署名は影響を受けません。
  • 文書署名用に発行: キー使用法に digital signature または non-repudiation が含まれ、拡張キー使用法があれば文書署名、メール保護、クライアント認証を許可します。他の目的(例: TLS サーバー証明書)で発行された証明書でも署名は可能ですが、Warning としてログに記録され、PDF リーダーは署名にフラグを付けます。
  • ハードウェアトークン、スマートカード、HSM、Windows 証明書ストアはサポートされていません。証明書をプライベートキーとチェーンと共にエクスポートし、PFX にしてください。

OpenSSL を使用して証明書とプライベートキーから PFX を作成:

bash
openssl pkcs12 -export -out signing.pfx -inkey private.key -in certificate.crt
# エクスポート パスワードとして求められるものは SigningCertificate.Password です。

Windows 証明書ストアからエクスポート: certmgr.msc を開き、証明書を探します(プライベートキーがある場合はアイコンに鍵が表示されます)。右クリックし、All Tasks → Export… を選択し、Yes, export the private key を選び、Personal Information Exchange – PKCS #12 (.PFX) を選択してパスワードを設定します。

起動時チェック

ウィジェットが有効化されると、SignerWidgetOptions.SigningCertificate の証明書が一度だけ、AddDoconut() 内でチェックされます。そのため、設定ミスの PFX は最初の署名時ではなく起動時に失敗します。3 つの問題が InvalidOperationException をスローします:

メッセージ対策
Doconut Signer: the certificate file was not found at '{path}'.PfxPath を修正し、ファイルがデプロイされアプリのアカウントから読み取れることを確認してください
Doconut Signer: the signing certificate could not be opened — the password is incorrect or the file is not a valid .pfx.パスワードを確認し、ファイルが実際の .pfx であり、.cer や .pem ではないことを確認してください
Doconut Signer: the signing certificate has no private key. Re-export the .pfx INCLUDING the private key.プライベートキー付きで PFX を再エクスポートしてください

それ以外の場合、ホストは起動時にログに1行を書き込みます。証明書が準備できたときの情報:

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

期限切れ、まだ有効でない、または文書署名用に発行されていない場合は Warning:

text
Doconut Signer: the signing certificate '{subject}' expired on yyyy-MM-dd. Certified signatures will be refused until it is replaced.
Doconut Signer: the signing certificate '{subject}' is not valid before yyyy-MM-dd. Certified signatures will be refused until then.
Doconut Signer: the signing certificate '{subject}' is not issued for document signing (its key usage excludes it). PDF readers will flag these signatures.

証明書が設定されていない場合は Information:

text
Doconut Signer: no signing certificate configured — output uses the built-in demo certificate and is watermarked. Set SignerWidgetOptions.SigningCertificate to sign with your own certificate.

最後の行はすべてのライセンスで同じです。有料ライセンスではデモ証明書は使用されません:証明書がない場合、Visual 署名のみが機能します。

C# ファサードは起動時にチェックされません。SignAsync に渡す証明書は署名時に読み取られるため、パスやパスワードが間違っているとその呼び出しが失敗します。

ドロップインウィジェット

エンドポイントを有効化する

ウィジェットの ?sign=open|run|download エンドポイントは デフォルトでオフ です。プラグインの登録の横でそれらを有効にします:

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
    options.AddSignerWidget(widget =>
    {
        widget.MaxUploadMb = 25;           // デフォルト
        widget.MaxSignatureImageKb = 512;  // デフォルト
        // widget.SigningCertificate: 証明書設定を参照; デモ(透かし入り)署名のために null のままにしてください
    });
});

AddSignerWidget() に引数を渡さないと、デフォルト設定でウィジェットが有効になります。これだけでは署名権限は付与されません:AddPlugin<SignerPlugin>() が必要か、AddDoconut() が例外を投げます:

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.

AddSignerWidget() がない場合、すべての ?sign= リクエストは 404 で応答します。スクリプト自体は配信され続けるため、ウィジェットはロードされドロップゾーンを描画し、最初のリクエストで Signing is not enabled on this server. を報告します。

埋め込む

UseDoconutResources() はスクリプトを {ResourcesPath}/js/doconutSigner.js で提供します(デフォルトは /doconut-res/js/doconutSigner.js)。これは依存関係のない単一の自己完結型ファイルです:

html
<div id="host"></div>
<script src="/doconut-res/js/doconutSigner.js"></script>
<script>
  const handle = Doconut.signer('#host', { basePath: '/doconut' });
</script>

Doconut.signer(selectorOrElement, options) は CSS セレクタまたは要素を受け取り、マウントが見つからない場合は例外を投げ、ハンドルを返します。

署名者は PDF または .docx ファイルをアップロードし、署名を作成します(キャンバス上で Draw、署名フォントで Type、または PNG、JPG、GIF の Image)。それをページ上にドラッグしてサイズ調整し、署名して結果をダウンロードします。ウィジェットは常に署名を PNG として送信します。アップロードされた画像はブラウザ内で 520×160 に合わせた PNG に変換されます。

オプション

オプション型デフォルト備考
basePathstring'/doconut'?sign= エンドポイントとプレビュー画像が提供される場所
resPathstring'/doconut-res'予約済み;ウィジェットは独自の CSS をバンドルします
maxUploadMbnumber25クライアント側のみのチェックなので、サイズオーバーのファイルはすぐに失敗します。サーバー上限は AddSignerWidget の MaxUploadMb です
maxSignatureKbnumber512Image モードのクライアント側上限です。サーバー側の MaxSignatureImageKb と同じにしてください
previewWidthnumber560ページプレビューのピクセル幅
licenseUrlstring | nullnullデモウォーターマークの通知をこの URL へのリンクに変換します
signatureModestring'certified'初期署名タイプ: 'certified' または 'visual'。それ以外の値は 'certified' になります
showSignatureModeTogglebooleantrueDigital signature / Visual only の選択肢を表示します。false がある場合、ウィジェットは signatureMode で署名します
wordOutputstring'pdf'.docx ソースの初期出力: 'pdf' または 'docx'。それ以外の値は 'pdf' になります
showOutputFormatTogglebooleantruePDF / Word の選択肢を表示します(.docx ソースのみ)。false がある場合、ウィジェットは wordOutput を使用します
labelsobject{}英語文字列の任意のサブセットを上書きします

トグルを非表示にしても機能が無効になるわけではなく、値が固定されます。一般的な構成例が2つあります:

javascript
// 両方のトグルが表示され、デジタル署名がデフォルト: フルセルフサービス署名者。
Doconut.signer('#host', { basePath: '/doconut', licenseUrl: '/pricing' });
javascript
// 視覚的のみ、トグルなし: デジタル署名が提供されないシンプルなスタンプ。
Doconut.signer('#host', {
  basePath: '/doconut',
  signatureMode: 'visual',
  showSignatureModeToggle: false
});

コールバック

コールバック発火条件ペイロード
onReadyマウント時に一度だけ(reset() では再度発火しません)—
onSourceLoadedファイルが開かれ、プレビューが表示されます{ file: { token, name, pages, ext } }
onSigned署名が成功したとき{ downloadToken, downloadName, watermarked }
onDownloadダウンロードクリック時に毎回{ downloadName, downloadToken }
onError開く、署名、またはダウンロードのいずれかのステップが失敗したとき、または Image モードのファイルが大きすぎるとき{ message }

例外を投げるコールバックは捕捉されログに記録されます;ウィジェットのフローを壊すことはありません。

命令的ハンドル

メソッド動作
reset()ドロップ画面に戻り、現在のフローをクリアします。onReady を再度発火させません。destroy() 後は何もしません。
loadFile(file)File でフローを開始します。ウィジェットがドロップ画面にない限り何もしません。必要に応じて最初に reset() を呼び出してください。
destroy()リスナーを削除し、マウントを空にし、インスタンスを凍結します。
javascript
const signerWidget = Doconut.signer('#host', {
  basePath: '/doconut',
  onSigned: (result) => console.log('signed', result.downloadName, result.watermarked),
  onError: (error) => console.warn(error.message)
});
document.getElementById('start-over').addEventListener('click', () => signerWidget.reset());

ラベル

すべての文字列は英語のデフォルトを持ちます;labels が任意のサブセットを上書きし、残りは英語のままです。実行時に変化するフラグメントは {placeholders} を使用し、例えば uploading: 'Uploading {name}…' や pages: '{n} pages' があります。

キー英語のデフォルト
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

さらに、配置ステップ、エラー画面、デモ通知のリンクフォーム(demoNoticePrefix、demoNoticeLink、demoNoticeSuffix)および aria-live の告知をカバーするキーがあります。

open または run が JSON エラーなしで 404 に応答した場合、ウィジェットは signingNotEnabled を表示します。サーバーからの JSON エラーは常に優先されるため、期限切れのアップロードなどのメッセージは表示されたままです。

テーマ設定

ウィジェットはマウント要素に dsw クラスを追加し、CSS カスタムプロパティから色、半径、フォントを取得するため、内部を触らずにテーマを設定できます:

css
#host.dsw {
  --dsw-accent: #b0522b;       /* リンク、フォーカス、アクティブモード */
  --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;   /* Typeモード */
}

デフォルト: --dsw-accent: #2b6cb0、--dsw-bg: #ffffff、--dsw-fg: #1a202c、--dsw-muted: #718096、--dsw-border: #cbd5e0、--dsw-radius: 8px、システム UI フォント、そして筆記体の署名フォント。

独自のフロントエンドを構築する

ウィジェットはこの HTTP 契約のクライアントです。3 つのルートはすべて UseDoconut() がマウントされているパス(通常は /doconut)の下にあり、AddSignerWidget() が呼び出されるまで 404 に応答します。エラーは JSON 本文({ "error": "..." })を伴いますが、テーブルで「ステータスのみ」と記載されている場合は除きます。未知の ?sign= 値は 400 で応答します。

ルート目的成功レスポンス
POST ?sign=open(マルチパート、単一ファイル)PDF または .docx をアップロードし、プレビュー用に開きます200 — { token, name, pages, ext }
POST ?sign=run(JSON ボディ)アップロードされたファイルに署名します200 — { downloadToken, downloadName, watermarked }
GET ?sign=download&token=<downloadToken>署名済みファイルをストリーミングします200 — ファイル、Content-Disposition: attachment、Cache-Control: no-store

ext は open レスポンスに含まれ、先頭のドット(".docx")が付加されます。ページプレビューは標準のビューア画像ルート {basePath}?token={token}&page={n}&thumb=1&width={px} を使用し、表示されるページは placement.page になります。

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"
}
フィールド備考
tokenopen からのトークン
signature.kindDrawn、Typed、または Image(大文字小文字は区別しません)。それ以外はすべて Drawn になります。ヒントだけですが、ペイロードは常に PNG です。
signature.payloadプレフィックス data: のない生の base64 PNG。実際の PNG である必要があり、デコード後のサイズは MaxSignatureImageKb を超えてはいけません。
placement.page1ベース
placement.x / y / w / h左上隅から正規化された 0..1、x + w ≤ 1 と y + h ≤ 1
meta.signerName / reason / location任意。各項目はトリムされ、空白の値は除外され、各項目は 256 文字で切り捨てられます。
wordOutputpdf(デフォルト)または docx;PDF ソースでは無視されます。それ以外はすべて pdf になります。
modecertified(デフォルト)または visual。それ以外はすべて certified になります。

downloadName は出力に続きます: <source>-signed.pdf または <source>-signed.docx、そして download は一致する Content-Type を送信します。

アップロードされたソースと署名済み結果はそれぞれ 30 分 保存されます。その後、run と download が 404 で応答し、ファイルは再度開く必要があります。すべてのトークンは GUID です。

ルートステータス条件本文
任意404ウィジェットが有効化されていませんステータスのみ
任意405誤った動詞(open と run は POST が必要、download は GET が必要)ステータスのみ
open400マルチパートアップロードではありませんExpected a multipart file upload.
open400ファイルがない、または空ですNo file uploaded.
open400.pdf または .docx 以外のすべてSigning supports PDF and Word (.docx) files only.
open413アップロードが MaxUploadMb を超えていますFile is too large.
run400本文が有効な JSON ではない、または空ですMalformed request. / Empty request.
run400トークンが欠如しているか GUID ではありませんInvalid token.
run404アップロードが期限切れ、または開かれませんでしたUpload expired — please re-open the file.
run400署名がない、または配置がありませんNo signature supplied. / No placement supplied.
run400ペイロードが base64 ではない、空、サイズが大きすぎる、または PNG ではありませんSignature image is not valid base64. / Signature image is empty. / Signature image is too large. / The signature image must be a PNG.
run400配置がページ外ですThe signature or its placement is invalid.
run400認証モード、有料ライセンス、かつ証明書がありませんNo signing certificate configured.
run400有効期限外の証明書を持つ認証モードThe signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd.
open, run500処理に失敗しましたサニタイズされたメッセージ
download400トークンが欠如しているか GUID ではありませんステータスのみ
download404不明または期限切れのトークンステータスのみ

fetch を使用した完全な往復:

javascript
// file: 署名対象のファイル; pngBase64: data: プレフィックスなしのベア base64 PNG 署名,
// 例として canvas.toDataURL('image/png').split(',')[1].
async function signFile(file, pngBase64) {
  const base = '/doconut';

  // 1. open: ファイルをアップロード
  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: 署名する
  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: 署名済みファイルを取得
  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);
}

エンドポイントは same-origin です: このバージョンは CORS をサポートしていません。UI とウィジェットスクリプトは Doconut と同じオリジンから提供するか、UI のオリジン下で /doconut の両方のパス(ミドルウェアパスとリソースパス)をリバースプロキシしてください。

本番環境で

  1. プラグインをインストール してください。コアパッケージと同じバージョンで、隣に配置します: dotnet add package Doconut.NET8.Signer.

  2. ライセンスファイルを追加 します。Doconut.Viewer.Signer.lic を Doconut.Viewer.lic と同じフォルダーに置きます.

  3. 証明書を PFX 形式で取得 してください。プライベートキーと発行者チェーンを含むものを、認証局または組織の PKI から取得します。まず試す場合は、デモライセンス(組み込みのデモ証明書、透かし付き)または自己署名の PFX を使用してください.

  4. 設定から証明書を読み取ります。これにより、証明書を変更してもコードの変更は不要です:

    json
    "DoconutSigner": { "PfxPath": "certs/your-certificate.pfx" }
    csharp
    var signerSettings = builder.Configuration.GetSection("DoconutSigner");
    
    builder.Services.AddDoconut(options =>
    {
        options.LicensePath = "Doconut.Viewer.lic";
        options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
        options.AddSignerWidget(widget => widget.SigningCertificate = new SigningCertificate
        {
            PfxPath = Path.Combine(builder.Environment.ContentRootPath, signerSettings["PfxPath"]),
            Password = signerSettings["Password"] ?? "",
        });
    });

    .pfx を wwwroot の外部に保管し、パスワードは appsettings.json に入れないでください。開発時はユーザーシークレット(dotnet user-secrets set "DoconutSigner:Password" "<password>")、本番時は環境変数(DoconutSigner__Password)またはボールトに保存します.

  5. スタートアップログを確認 してください。using certificate '{subject}' (valid until …). Signatures are digitally sealed. と表示されるはずです。警告が出る場合は、証明書が期限切れ、まだ有効でない、または文書署名用に発行されていないことを意味します.

PDF リーダーへの信頼。リーダーは、証明書のルートを信頼している場合に署名を有効と表示します。組織の PKI を使用すれば、ルートを信頼するすべてのマシン(通常は組織内のすべてのマシン)で有効です。Adobe が任意のマシンで信頼する証明書(Adobe Approved Trust List)は、私たちの知る限りハードウェアトークンまたは HSM 上のプライベートキーで発行されており、このプラグインはそれを使用できません:PFX からのみ署名します。そのような信頼に依存する前に、証明書プロバイダーに確認してください。

Web ファーム

ウィジェットは、open を提供したノードのメモリ上に各アップロードとその結果を保持します。スティッキーセッションのないロードバランサーの背後では、後続の run、download、またはプレビューリクエストが別のノードに到達し、アップロードが見つからないことがあります。AddDoconut() 後に、共有かつ暗号化されたウィジェットストアを一度だけ登録してください:

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

builder.Services.AddDoconutDistributedWidgets(store =>
{
    store.RootPath = @"\\fileshare\doconut";   // 各ノードが読み書きできるフォルダー
    store.FarmKey = farmKey;                   // 少なくとも 32 バイトで、すべてのノードで同一
    // store.Ttl = TimeSpan.FromMinutes(30);   // アップロードが保持される期間 (デフォルト)
});
  • 単一サーバーは何も必要としません: この呼び出しがなければインメモリストアが使用されます.
  • アップロードと結果は、共有上で保存時に暗号化されます(AES-256、encrypt-then-MAC)。各ファイルはトークンに紐付けられるため、あるトークンが別のファイルを読むことはできません.
  • FarmKey は少なくとも 32 バイトで、すべてのノードで同一である必要があります。シークレットストアからロードし、ハードコードしないでください。RootPath が欠如しているか、FarmKey が 32 バイト未満の場合、登録時に ArgumentException がスローされます.
  • RootPath を分散ビューアが使用するのと同じ共有場所に設定し、すべてのノードに同一の署名証明書を提供してください.

APIリファレンス

ファサードとウィジェットオプションは Doconut 名前空間にあり、リクエストと結果の型は Doconut.Core.Models.Signing にあります。SignerPlugin は 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);
}

依存性注入から解決されます;コンストラクタは internal です。sourceExtension は ".pdf" または ".docx" です。有料ライセンスの場合、cert が使用され出力はクリーンです;一時ライセンスの場合、組み込みのデモ証明書が使用され、cert は無視され、出力に透かしが入ります。

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
}

1 回だけ配置される可視署名が1つと、オプションの署名者メタデータがあります。

VisibleSignature and SignatureKind

csharp
public sealed record VisibleSignature(SignatureKind Kind, byte[] PngBytes)
{
    public bool IsValid { get; }   // PngBytes は空ではありません
}

public enum SignatureKind { Drawn, Typed, Image }

PngBytes はすべての種類に対して PNG です。描画または入力された署名は透明です;アップロードされた画像は元の透明性を保持するため、不透明な JPG は不透明なままです。Kind はヒントにすぎません。

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 は 1 から始まります;X、Y、W、H は左上隅から正規化された 0..1 です。

SignatureMode and WordOutput

csharp
public enum SignatureMode { Certified, Visual }   // Certified はデフォルトです
public enum WordOutput { Pdf, Docx }              // Pdf はデフォルトです; PDF ソースでは無視されます

SignResult

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

署名されたドキュメントはシーク可能なストリームとして提供され、拡張子はドット付き(".pdf" または ".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 は空ではなく、または PfxPath は空白ではありません
}

PfxBytes または PfxPath のいずれかを設定し、さらに Password を設定します。

SignerWidgetOptions

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

DoconutOptions.AddSignerWidget(Action<SignerWidgetOptions>? configure = null) を通じて設定します。これにより DoconutOptions が返され、呼び出しをチェーンできます。null の SigningCertificate は一時ライセンス下のデモ証明書を意味し、Visual 署名は有料ライセンス時のみ使用できます。

Troubleshooting

症状原因対策
AddDoconut() が The Signer plugin is registered via AddPlugin but no active license grants Signer. をスローしますライセンスがない、TRIAL ファイル、Signer が含まれていないライセンス、またはバージョン期間外の有料ライセンスSigner を付与するライセンスをインストールするか、AddPlugin<SignerPlugin>() を削除してください
AddDoconut() が AddSignerWidget() was called but the Signer plugin is not registered. をスローしますウィジェットがプラグインなしで有効になっているoptions.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>() を追加してください
AddDoconut() が Doconut Signer: the certificate file was not found at '{path}'. をスローしますPfxPath が存在しないファイルを指していますパスを修正し、アプリのアカウントが読み取れる場所にファイルを配置してください
AddDoconut() が Doconut Signer: the signing certificate could not be opened — the password is incorrect or the file is not a valid .pfx. をスローしますパスワードが間違っている、または PKCS#12 ファイルではありませんパスワードを確認し、実際の .pfx を使用してください
AddDoconut() が Doconut Signer: the signing certificate has no private key. Re-export the .pfx INCLUDING the private key. をスローしますPFX がプライベートキーなしでエクスポートされましたプライベートキーを含めて再エクスポートしてください
DocumentSigner の解決時に No IDocumentSigner is registered. がスローされますSignerPlugin が登録されていませんAddDoconut() 内に AddPlugin<SignerPlugin>() を追加してください
出力に透かしが入りますライセンスが一時的です(デモ/NFR)Signer を付与する有料ライセンスを使用してください
run が 400 No signing certificate configured. と応答します有料ライセンス、Certified モード、証明書がないSigningCertificate を構成するか、Visual モードで署名してください
run が 400 The signing certificate expired on yyyy-MM-dd. と応答します証明書が期限切れです交換してください;その間、Visual 署名は引き続き機能します
ログに出力が「組み込みデモ証明書を使用しています」と表示されても、有料ライセンスが Certified 署名を拒否しますこの行は、ライセンスに関係なく証明書が設定されていない場合に書き込まれますSigningCertificate を構成してください
ウィジェットはロードされますが、Signing is not enabled on this server. と表示されますAddSignerWidget() が呼び出されていないか、UseDoconut() がマウントされている場所と basePath が一致しませんAddSignerWidget() を呼び出し、basePath を修正してください
run が 400 The signature image must be a PNG.、Signature image is not valid base64.、または Signature image is too large. と応答しますカスタム UI が data: URL、JPG、または MaxSignatureImageKb を超えるものを送信しましたキャップ内でベアな base64 PNG を送信してください
open が 413 File is too large. と応答しますアップロードが MaxUploadMb を超えていますAddSignerWidget で MaxUploadMb を上げてください;ウィジェットの maxUploadMb はクライアント側のチェックのみです
run または download が 404 Upload expired — please re-open the file. と応答します30 分のウィンドウが経過したか、Web ファームのノードにアップロードがありませんファイルを再度開いてください;ファーム内では AddDoconutDistributedWidgets を登録してください
署名された .docx が一部のビューアで署名が表示されませんWord 出力は OOXML パッケージ署名を含んでおり、多くのビューアはそれを表示しませんデフォルトの PDF に署名してください
PDF リーダーが署名者の身元が不明と表示しますリーダーが証明書のルートを信頼していません(デモ証明書は決して信頼されません)読者が信頼するルートの証明書を使用してください
UI が別オリジンにあるとウィジェットが失敗しますエンドポイントに CORS 対応がありませんUI を同一オリジンから提供するか、Doconut パスをリバースプロキシしてください
テーマが適用されませんセレクタがマウント内部の要素を対象にしていますマウント自体を対象にしてください:#host.dsw または #host

このページは役に立ちましたか?