サイナープラグイン
可視署名とデジタルシールで 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 プラグインをインストールします:
dotnet add package Doconut.NET8.Signerこのドキュメントで説明しているリリースにプラグインを固定するには、バージョンを別途指定します:
dotnet add package Doconut.NET8.Signer --version 26.10.0Doconut.NET8 と同じバージョンで Signer パッケージを保ちます。パッケージ ID は Doconut.NET8.Signer です。.<version> はダウンロードされた .nupkg のファイル名にのみ現れます。
プラグインのライセンスファイル Doconut.Viewer.Signer.lic は Doconut.Viewer.lic と同じフォルダーに配置します。ビューアのライセンスと共に読み込まれます。
プラットフォーム。 プラグインは Doconut.NET8 が動作する場所ならどこでも動作します:Windows と x64 の glibc ベース Linux(Alpine や他の musl ベースディストリビューションは除く)。Linux では、最初の文書を開く前にフォント設定ライブラリをインストールしてください:
apt-get update && apt-get install -y libfontconfig1RHEL、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>() に登録します:
builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
});これが C# ファサードに必要なすべてです。ウィジェットとその HTTP エンドポイントは別途オプトインで、AddSignerWidget() です(ドロップインウィジェット を参照)。
プラグインは Signer 機能を付与するライセンスが必要です。これがないと、AddDoconut() はアプリがリクエストを処理する前の起動時に例外をスローします:
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>(). がスローされます
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 署名は画像のみをスタンプし、証明書は不要です:
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 から名前付けしてください:
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 は呼び出しが成功しない場合に返す代わりに例外をスローします:
| 例外 | メッセージ | 条件 |
|---|---|---|
InvalidOperationException | No signing certificate configured. | 認証モード、課金ライセンス、かつ証明書が渡されていない場合 |
InvalidOperationException | The signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd. | 有効期限外の証明書がある認証モード |
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. | 空の PNG バイト、または無効な配置 |
NotSupportedException | The 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 に渡します。バイト列またはパスのいずれかと、パスワードを提供してください:
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"],
};
});
});証明書はメモリ内にのみ保持されます。ログに記録されたり、クライアントに返されたり、永続化されたりすることはなく、パスワードがログ行やエラーメッセージに表示されることもありません。
要件:
- PFX / PKCS#12 バンドル プライベートキー付き。公開鍵のみのファイル(
.cer、.crt)では署名できません。発行者チェーンもエクスポートし、PDF シールがそれを保持できるようにしてください。 - 正しいパスワード。
- 有効期間内であること。期限切れまたはまだ有効でない証明書はアプリの動作を停止させません:起動時に Warning としてログに記録され、置き換えられるまで Certified 署名は拒否されます。Visual 署名は影響を受けません。
- 文書署名用に発行: キー使用法に digital signature または non-repudiation が含まれ、拡張キー使用法があれば文書署名、メール保護、クライアント認証を許可します。他の目的(例: TLS サーバー証明書)で発行された証明書でも署名は可能ですが、Warning としてログに記録され、PDF リーダーは署名にフラグを付けます。
- ハードウェアトークン、スマートカード、HSM、Windows 証明書ストアはサポートされていません。証明書をプライベートキーとチェーンと共にエクスポートし、PFX にしてください。
OpenSSL を使用して証明書とプライベートキーから PFX を作成:
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行を書き込みます。証明書が準備できたときの情報:
Doconut Signer: using certificate '{subject}' (valid until yyyy-MM-dd). Signatures are digitally sealed.期限切れ、まだ有効でない、または文書署名用に発行されていない場合は Warning:
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:
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 エンドポイントは デフォルトでオフ です。プラグインの登録の横でそれらを有効にします:
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() が例外を投げます:
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)。これは依存関係のない単一の自己完結型ファイルです:
<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 に変換されます。
オプション
| オプション | 型 | デフォルト | 備考 |
|---|---|---|---|
basePath | string | '/doconut' | ?sign= エンドポイントとプレビュー画像が提供される場所 |
resPath | string | '/doconut-res' | 予約済み;ウィジェットは独自の CSS をバンドルします |
maxUploadMb | number | 25 | クライアント側のみのチェックなので、サイズオーバーのファイルはすぐに失敗します。サーバー上限は AddSignerWidget の MaxUploadMb です |
maxSignatureKb | number | 512 | Image モードのクライアント側上限です。サーバー側の MaxSignatureImageKb と同じにしてください |
previewWidth | number | 560 | ページプレビューのピクセル幅 |
licenseUrl | string | null | null | デモウォーターマークの通知をこの URL へのリンクに変換します |
signatureMode | string | 'certified' | 初期署名タイプ: 'certified' または 'visual'。それ以外の値は 'certified' になります |
showSignatureModeToggle | boolean | true | Digital signature / Visual only の選択肢を表示します。false がある場合、ウィジェットは signatureMode で署名します |
wordOutput | string | 'pdf' | .docx ソースの初期出力: 'pdf' または 'docx'。それ以外の値は 'pdf' になります |
showOutputFormatToggle | boolean | true | PDF / Word の選択肢を表示します(.docx ソースのみ)。false がある場合、ウィジェットは wordOutput を使用します |
labels | object | {} | 英語文字列の任意のサブセットを上書きします |
トグルを非表示にしても機能が無効になるわけではなく、値が固定されます。一般的な構成例が2つあります:
// 両方のトグルが表示され、デジタル署名がデフォルト: フルセルフサービス署名者。
Doconut.signer('#host', { basePath: '/doconut', licenseUrl: '/pricing' });// 視覚的のみ、トグルなし: デジタル署名が提供されないシンプルなスタンプ。
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() | リスナーを削除し、マウントを空にし、インスタンスを凍結します。 |
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' があります。
| キー | 英語のデフォルト |
|---|---|
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 |
さらに、配置ステップ、エラー画面、デモ通知のリンクフォーム(demoNoticePrefix、demoNoticeLink、demoNoticeSuffix)および aria-live の告知をカバーするキーがあります。
open または run が JSON エラーなしで 404 に応答した場合、ウィジェットは signingNotEnabled を表示します。サーバーからの JSON エラーは常に優先されるため、期限切れのアップロードなどのメッセージは表示されたままです。
テーマ設定
ウィジェットはマウント要素に dsw クラスを追加し、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 本文:
{
"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"
}| フィールド | 備考 |
|---|---|
token | open からのトークン |
signature.kind | Drawn、Typed、または Image(大文字小文字は区別しません)。それ以外はすべて Drawn になります。ヒントだけですが、ペイロードは常に PNG です。 |
signature.payload | プレフィックス data: のない生の base64 PNG。実際の PNG である必要があり、デコード後のサイズは MaxSignatureImageKb を超えてはいけません。 |
placement.page | 1ベース |
placement.x / y / w / h | 左上隅から正規化された 0..1、x + w ≤ 1 と y + h ≤ 1 |
meta.signerName / reason / location | 任意。各項目はトリムされ、空白の値は除外され、各項目は 256 文字で切り捨てられます。 |
wordOutput | pdf(デフォルト)または docx;PDF ソースでは無視されます。それ以外はすべて pdf になります。 |
mode | certified(デフォルト)または visual。それ以外はすべて certified になります。 |
downloadName は出力に続きます: <source>-signed.pdf または <source>-signed.docx、そして download は一致する Content-Type を送信します。
アップロードされたソースと署名済み結果はそれぞれ 30 分 保存されます。その後、run と download が 404 で応答し、ファイルは再度開く必要があります。すべてのトークンは GUID です。
| ルート | ステータス | 条件 | 本文 |
|---|---|---|---|
| 任意 | 404 | ウィジェットが有効化されていません | ステータスのみ |
| 任意 | 405 | 誤った動詞(open と run は POST が必要、download は GET が必要) | ステータスのみ |
open | 400 | マルチパートアップロードではありません | Expected a multipart file upload. |
open | 400 | ファイルがない、または空です | No file uploaded. |
open | 400 | .pdf または .docx 以外のすべて | Signing supports PDF and Word (.docx) files only. |
open | 413 | アップロードが MaxUploadMb を超えています | File is too large. |
run | 400 | 本文が有効な JSON ではない、または空です | Malformed request. / Empty request. |
run | 400 | トークンが欠如しているか GUID ではありません | Invalid token. |
run | 404 | アップロードが期限切れ、または開かれませんでした | Upload expired — please re-open the file. |
run | 400 | 署名がない、または配置がありません | No signature supplied. / No placement supplied. |
run | 400 | ペイロードが base64 ではない、空、サイズが大きすぎる、または 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 | 配置がページ外です | The signature or its placement is invalid. |
run | 400 | 認証モード、有料ライセンス、かつ証明書がありません | No signing certificate configured. |
run | 400 | 有効期限外の証明書を持つ認証モード | The signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd. |
open, run | 500 | 処理に失敗しました | サニタイズされたメッセージ |
download | 400 | トークンが欠如しているか GUID ではありません | ステータスのみ |
download | 404 | 不明または期限切れのトークン | ステータスのみ |
fetch を使用した完全な往復:
// 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 の両方のパス(ミドルウェアパスとリソースパス)をリバースプロキシしてください。
本番環境で
-
プラグインをインストール してください。コアパッケージと同じバージョンで、隣に配置します:
dotnet add package Doconut.NET8.Signer. -
ライセンスファイルを追加 します。
Doconut.Viewer.Signer.licをDoconut.Viewer.licと同じフォルダーに置きます. -
証明書を PFX 形式で取得 してください。プライベートキーと発行者チェーンを含むものを、認証局または組織の PKI から取得します。まず試す場合は、デモライセンス(組み込みのデモ証明書、透かし付き)または自己署名の PFX を使用してください.
-
設定から証明書を読み取ります。これにより、証明書を変更してもコードの変更は不要です:
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"] ?? "", }); });.pfxをwwwrootの外部に保管し、パスワードはappsettings.jsonに入れないでください。開発時はユーザーシークレット(dotnet user-secrets set "DoconutSigner:Password" "<password>")、本番時は環境変数(DoconutSigner__Password)またはボールトに保存します. -
スタートアップログを確認 してください。
using certificate '{subject}' (valid until …). Signatures are digitally sealed.と表示されるはずです。警告が出る場合は、証明書が期限切れ、まだ有効でない、または文書署名用に発行されていないことを意味します.
PDF リーダーへの信頼。リーダーは、証明書のルートを信頼している場合に署名を有効と表示します。組織の PKI を使用すれば、ルートを信頼するすべてのマシン(通常は組織内のすべてのマシン)で有効です。Adobe が任意のマシンで信頼する証明書(Adobe Approved Trust List)は、私たちの知る限りハードウェアトークンまたは HSM 上のプライベートキーで発行されており、このプラグインはそれを使用できません:PFX からのみ署名します。そのような信頼に依存する前に、証明書プロバイダーに確認してください。
Web ファーム
ウィジェットは、open を提供したノードのメモリ上に各アップロードとその結果を保持します。スティッキーセッションのないロードバランサーの背後では、後続の run、download、またはプレビューリクエストが別のノードに到達し、アップロードが見つからないことがあります。AddDoconut() 後に、共有かつ暗号化されたウィジェットストアを一度だけ登録してください:
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
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
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
public sealed record VisibleSignature(SignatureKind Kind, byte[] PngBytes)
{
public bool IsValid { get; } // PngBytes は空ではありません
}
public enum SignatureKind { Drawn, Typed, Image }PngBytes はすべての種類に対して PNG です。描画または入力された署名は透明です;アップロードされた画像は元の透明性を保持するため、不透明な JPG は不透明なままです。Kind はヒントにすぎません。
SignaturePlacement
public readonly record struct SignaturePlacement(int Page, double X, double Y, double W, double H)
{
public bool IsValid { get; } // Page >= 1; X, Y >= 0; W, H > 0; X + W <= 1; Y + H <= 1
}Page は 1 から始まります;X、Y、W、H は左上隅から正規化された 0..1 です。
SignatureMode and WordOutput
public enum SignatureMode { Certified, Visual } // Certified はデフォルトです
public enum WordOutput { Pdf, Docx } // Pdf はデフォルトです; PDF ソースでは無視されますSignResult
public sealed record SignResult(Stream Stream, string Extension);署名されたドキュメントはシーク可能なストリームとして提供され、拡張子はドット付き(".pdf" または ".docx")です。
SigningCertificate
public sealed class SigningCertificate
{
public byte[]? PfxBytes { get; init; }
public string? PfxPath { get; init; }
public string Password { get; init; } = "";
public bool HasMaterial { get; } // PfxBytes は空ではなく、または PfxPath は空白ではありません
}PfxBytes または PfxPath のいずれかを設定し、さらに Password を設定します。
SignerWidgetOptions
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 |
このページは役に立ちましたか?