署名プラグイン
可視署名とデジタルシールで PDF と Word 文書に署名
Signer プラグインは文書に可視署名を配置し、デフォルトでは PDF リーダーが検証できるデジタル署名でシールします。PDF と Word (.docx) ファイルに署名します。可視署名は常に PNG 画像で、描画、入力、または署名者によるアップロードのいずれかです。
| 表面 | 使用シーン |
|---|---|
DocumentSigner (C#) | サーバー上で署名し、ブラウザは関与しません |
ドロップインウィジェット (doconutSigner.js) | ページ内に既成のアップロード、署名、ダウンロード画面が欲しい場合 |
HTTP エンドポイント(DocImage.axd)(?sign=open|run|download) | 文書化されたサーバー契約に対して独自の署名 UI を構築したい場合 |
各署名は 1 ページに 1 回だけ配置されます。署名者の名前、理由、場所は署名と共に保持されます。
パッケージのインストール
Install-Package Doconut.NETFramework.Signerこのドキュメントで説明しているリリースにプラグインを固定するには:
Install-Package Doconut.NETFramework.Signer -Version 26.10.0Signer パッケージは Doconut.NETFramework と同じバージョンに保ってください。
プラグインのライセンスファイル Doconut.Viewer.Signer.lic は Doconut.Viewer.lic と同じフォルダーに配置します。ビューアのライセンスと一緒に読み込まれます。
プラグインの登録
すべての Doconut プラグインと同様に、Signer は AddPlugin<TPlugin>() を DoconutHost.Initialize に登録し、Application_Start から呼び出されます:
Doconut.DoconutHost.Initialize(options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
});Doconut.DoconutHost.Shutdown() を Application_End に追加すると、アプリプールがリサイクルされた際にバックグラウンド作業がきれいに停止します。
これで C# ファサードに必要なものはすべてです。ウィジェットとその HTTP エンドポイントは別途オプトインで、AddSignerWidget() です(ドロップインウィジェット を参照)。
プラグインは Signer 機能を付与するライセンスが必要です。ライセンスがない場合、DoconutHost.Initialize は Application_Start から例外をスローします:
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.System.Web では、すべてのリクエストが空の 500 を返し、理由は Windows のイベントログ(ソース ASP.NET)にのみ記録されます。ライセンスがない場合、レガシー TRIAL ファイル、Signer が欠如したライセンス、バージョン期間外で使用された有料ライセンスの場合に例外がスローされます。一時的なデモ/NFR ライセンスは受け入れられます。ライセンス設定 を参照してください。
ライセンスと透かし
| ライセンス状態 | 起動時 | 認証署名 | 可視署名 |
|---|---|---|---|
Signer を付与する有料ライセンス、証明書が設定済み | 開始 | 証明書でシールされ、クリーン(watermarked: false) | クリーン |
Signer を付与する有料ライセンス、証明書なし | 開始 | 拒否: No signing certificate configured. | クリーン |
| 有料ライセンス、証明書が期限切れまたはまだ有効でない | 開始 | 拒否: The signing certificate expired on yyyy-MM-dd. | クリーン |
| 一時的なデモ/NFR ライセンス、アクティブまたは期限切れ | 開始 | 組み込みデモ証明書でシールされ、透かし付き(watermarked: true) | 透かし付き |
ライセンスなし、レガシー TRIAL ファイル、Signer が欠如したライセンス、またはバージョン期間外の有料ライセンス | Application_Start が例外をスローし、すべてのリクエストが空の 500 を返す | — | — |
このルールは C# ファサードとウィジェットの両方に同じです。ライセンスが有料ビューアライセンスでないか、一時的な場合、出力に透かしが付けられます。一時的なライセンスの場合、プラグインは常に組み込みのデモ証明書で署名し、設定した証明書は使用されません。
デモ証明書は本物のシールを生成しますが、PDF リーダーはそれを信頼しません。評価ライセンスでエンドツーエンドの統合を構築・テストできますが、クリーンで信頼できる出力を得るには、有料ライセンスと独自の署名証明書の両方が必要です。
C# からの使用
DocumentSigner は DoconutHost.Initialize によって登録されます; DoconutHost.Services から解決してください。そのコンストラクタは 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, 81920, ct);
return output.ToArray();
}
}
}SignAsync はソースストリーム、その拡張子(".pdf" または ".docx")、リクエスト、そして証明書 この呼び出し用に 受け取ります。ファサードは SignerWidgetOptions.SigningCertificate を読み取りません;その設定はウィジェット用です。デモライセンス下、または Visual モードで null を渡してください。
SignResult は署名済みドキュメントをシーク可能なストリームとして保持し、さらにその Extension(".pdf" または ".docx")も保持するので、ファイル名を付けることができます。ストリームはあなたの所有です:使用後は必ず破棄してください。
MVC 5 コントローラで
アクションを非同期にし、署名を await してください。このものは Visual 署名をスタンプし、証明書は不要です:
[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);
}Word ソースは、Word 出力を要求しない限り PDF に署名されます。結果は result.Extension から名前付けしてください:
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 は呼び出しが成功しない場合に返す代わりに例外をスローします:
| 例外 | メッセージ | 条件 |
|---|---|---|
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 (default) | 可視署名とデジタルシールの両方 | 有料ライセンスが必要 | はい |
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 に渡します。バイト列またはパスのいずれかとパスワードを提供してください。App_Data はファイルの配置先として適しています。IIS は決して提供しないためです:
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"] ?? "",
};
});
});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"] ?? "",
};
});
});SigningCertificate のプロパティは init-only であり、C# 7.3(.NET Framework プロジェクトのデフォルト)では設定できません。プロジェクト ファイルで <LangVersion> を 9.0 以降に設定してください。
証明書はメモリ内にのみ保持されます。ログに記録されたり、クライアントに返されたり、永続化されたりすることはなく、パスワードがエラーメッセージに表示されることもありません。
要件:
- PFX / PKCS#12 バンドル プライベートキー付き。公開鍵のみのファイル(
.cer、.crt)では署名できません。発行者チェーンをエクスポートしておくと、PDF シールがそれを保持できます。 - 正しいパスワード。
- 有効期間内であること。期限切れまたはまだ有効でない証明書はアプリの動作を停止させませんが、Certified 署名は置き換えられるまで拒否されます。Visual 署名は影響を受けません。
- 文書署名用に発行: digital signature または non-repudiation のキー使用法、そして存在すれば文書署名、メール保護、クライアント認証を許可する拡張キー使用法。TLS サーバー証明書など別の目的で発行された証明書でも署名は可能ですが、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 内の証明書が DoconutHost.Initialize 内で一度だけチェックされるため、設定ミスした PFX は最初の署名時ではなくスタートアップ時に失敗します。3 つの問題が Application_Start から InvalidOperationException をスローし、すべてのリクエストは空の 500 で応答します;メッセージは Windows イベントログに記録されます。
| メッセージ | 修正 |
|---|---|
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 を再エクスポートしてください |
ASP.NET Core では、ホストはスタートアップ時に証明書名を記した 1 行をログに記録したり、期限切れや署名用に発行されていないことを警告したりします。DoconutHost はその行を書き込まないため、.NET Framework では認証モードでテスト文書に署名して新しい証明書を確認してください。
C# のファサードはスタートアップ時にチェックされません。SignAsync に渡す証明書は署名時に読み込まれるため、パスやパスワードが間違っているとその呼び出しが失敗します。
ドロップインウィジェット
エンドポイントを有効化
ウィジェットの ?sign=open|run|download エンドポイントは DocImage.axd によって提供され、デフォルトでは オフ です。プラグイン登録の横でそれらを有効化してください:
Doconut.DoconutHost.Initialize(options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
options.AddSignerWidget(widget =>
{
widget.MaxUploadMb = 25; // デフォルト
widget.MaxSignatureImageKb = 512; // デフォルト
// widget.SigningCertificate: 証明書の設定を参照してください; デモ(透かし入り)署名のために null のままにしてください
});
});
// System.Web は Doconut が見る前にアップロード全体を読み取ります: maxRequestLength (KB) と
// Web.config の widget の MaxUploadMb の上にある maxAllowedContentLength (bytes)AddSignerWidget() は引数なしでウィジェットをデフォルト設定で有効にします。それだけでは署名権限は付与されません:AddPlugin<SignerPlugin>() が必要です、または DoconutHost.Initialize がスローします:
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.エンドポイントとスクリプトはハンドラと Web.config に登録されたモジュールによって提供されます:
<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>モジュールはウィジェットが有効かどうかに関わらずスクリプトを提供します。AddSignerWidget() がない場合、ウィジェットは読み込まれドロップゾーンを描画しますが、最初のリクエストは 404 で応答します:ウィジェットはその後 Signing is not enabled on this server. を報告します。
アップロード制限
ASP.NET は DocImage.axd が実行される前にリクエストボディ全体を読み取ります。MaxUploadMb を超えホストの制限未満のアップロードはウィジェット独自の JSON 413(File is too large.)を取得します。ホストの制限を超えるアップロードはまず IIS によって拒否され、ウィジェットが読み取れないエラーページが返されます。ホストの制限はウィジェットの上限よりも高く保ってください:
<system.web>
<httpRuntime maxRequestLength="30720" /> <!-- KILOBYTES: 30 MB -->
</system.web>
<system.webServer>
<security>
<requestFiltering>
<requestLimits maxAllowedContentLength="31457280" /> <!-- BYTES: 30 MB -->
</requestFiltering>
</security>
</system.webServer>Content-Length(チャンク)なしで送信されたアップロードがホストの制限を超える場合も、IIS のエラーページが返されます;このケースに対する回避策はありません。
埋め込む
スクリプトは /doconut-res/js/doconutSigner.js で提供されます。単一の自己完結型ファイルで、依存関係はありません。basePath をハンドラに設定してください:
<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) は CSS セレクタまたは要素を受け取り、マウントが見つからない場合は例外をスローし、ハンドルを返します。ウィジェットのデフォルト basePath、/doconut は ASP.NET Core エンドポイントです。このパッケージでは '/DocImage.axd' である必要があります。
署名者は PDF または .docx ファイルをアップロードし、署名を作成します(キャンバス上で Draw、署名フォントで Type、または PNG、JPG、GIF の Image)。ページ上にドラッグしてサイズを調整し、署名して結果をダウンロードします。ウィジェットは常に署名を PNG として送信します。アップロードされた画像はブラウザ内で 520×160 に合わせた PNG に変換されます。
オプション
| オプション | 型 | デフォルト | 備考 |
|---|---|---|---|
basePath | string | '/doconut' | ?sign= エンドポイントとプレビュー画像が提供される場所です。このパッケージで '/DocImage.axd' を設定してください |
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: '/DocImage.axd', licenseUrl: '/pricing' });// 視覚的のみ、トグルなし: デジタル署名が提供されないシンプルなスタンプ。
Doconut.signer('#host', {
basePath: '/DocImage.axd',
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: '/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());ラベル
すべての文字列には英語のデフォルトがあります; labels は任意のサブセットを上書きし、残りは英語のままです。実行時に変化するフラグメントは {placeholders} を使用し、例えば uploading: 'Uploading {name}…' と pages: '{n} pages' です。
| Key | English default |
|---|---|
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; /* タイプモード */
}デフォルト: --dsw-accent: #2b6cb0、--dsw-bg: #ffffff、--dsw-fg: #1a202c、--dsw-muted: #718096、--dsw-border: #cbd5e0、--dsw-radius: 8px、システム UI フォント、そして手書き風署名フォント。
独自フロントエンドを構築する
ウィジェットは DocImage.axd 上のこの HTTP 契約のクライアントです。ルートは AddSignerWidget() が呼び出されるまで 404 に応答します。エラーは JSON 本文、{ "error": "..." } を含みますが、テーブルで「status only」と記載されている場合は除きます。未知の ?sign= 値は 400 で応答します。
| ルート | 目的 | 成功レスポンス |
|---|---|---|
POST /DocImage.axd?sign=open(マルチパート、単一ファイル) | PDF または .docx をアップロードし、プレビュー用に開く | 200 — { token, name, pages, ext } |
POST /DocImage.axd?sign=run(JSON 本文) | アップロードされたファイルに署名する | 200 — { downloadToken, downloadName, watermarked } |
GET /DocImage.axd?sign=download&token=<downloadToken> | 署名済みファイルをストリームする | 200 — ファイル、Content-Disposition: attachment、Cache-Control: no-store |
ext は open 応答に含まれ、先頭のドット(".docx")が含まれます。ページプレビューは標準のビューア画像ルート /DocImage.axd?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 | プレーンな base64 PNG、data: プレフィックスなし。実際の 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 です。
| ルート | ステータス | 条件 | 本文 |
|---|---|---|---|
| any | 404 | ウィジェットが有効ではありません | ステータスのみ |
| any | 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 を超えています(ただし IIS の制限は超えていません) | 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: 署名する File; pngBase64: data: プレフィックスなしのベア base64 PNG 署名,
// 例として canvas.toDataURL('image/png').split(',')[1].
async function signFile(file, pngBase64) {
const base = '/DocImage.axd';
// 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 とウィジェットスクリプトを提供するか、UI のオリジン下で DocImage.axd と /doconut-res をリバースプロキシしてください。
本番環境で
-
プラグインをインストール してください。コアパッケージと同じバージョンで隣に置きます:
Install-Package Doconut.NETFramework.Signer. -
ライセンスファイルを追加してください。
Doconut.Viewer.Signer.licをDoconut.Viewer.licと同じフォルダーに置きます. -
証明書を PFX として取得してください。プライベートキーと発行者チェーンを含むものを、認証局または組織の独自 PKI から取得します。まず試す場合は、デモライセンス(組み込みのデモ証明書、透かし入り)または自己署名の PFX を使用してください.
-
設定から証明書を読み取ります。これにより、変更してもコードの変更は不要です:
xml<appSettings> <add key="DoconutSigner:PfxPath" value="~/App_Data/your-certificate.pfx" /> </appSettings>csharpvar 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"] ?? "", }); });.pfxをApp_Dataに保管してください。IIS は決して提供しません。また、パスワードを平文のWeb.configに置かないでください。暗号化された設定セクション、またはデプロイ時に読み取るシークレットストアを使用します. -
認証モードでテスト文書に署名します。期限切れまたはまだ有効でない証明書は
The signing certificate expired on yyyy-MM-dd.(またはis not valid before)で拒否され、PDF リーダーは署名を信頼しているかどうかを表示します.
PDF リーダーでの信頼。リーダーは、証明書のルートを信頼している場合に署名を有効と表示します。組織の PKI を使用すれば、ルートを信頼するすべてのマシン(通常は組織内のすべてのマシン)で有効です。Adobe が任意のマシンで信頼する証明書(Adobe Approved Trust List)は、私たちが知る限り、ハードウェアトークンまたは HSM 上のプライベートキーで発行されており、このプラグインはそれを使用できません:PFX からのみ署名します。その種の信頼に依存する前に、証明書プロバイダーに確認してください。
Web ファーム
ウィジェットは、open を提供したサーバーのメモリ内に各アップロードとその結果を保持します。スティッキーセッションなしのロードバランサーの背後では、後続の run、download、またはプレビューリクエストが別のサーバーに届き、アップロードが見つからないことがあります。DoconutHost.Initialize の第2引数を通じて、共有かつ暗号化されたウィジェットストアを登録してください:
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"; // すべてのサーバーが読み書きできるフォルダー
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);
}DoconutHost.Services から解決されます。コンストラクタは 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 と 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 と 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 を設定します。セッターは init-only で、プロジェクトは C# 9.0 以降が必要です。
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 署名は有料ライセンス時のみ使用できます。
トラブルシューティング
| 症状 | 原因 | 対策 |
|---|---|---|
プラグインを追加した後、すべてのリクエストが空の 500 を返し、イベントログに The Signer plugin is registered via AddPlugin but no active license grants Signer. が表示されます | ライセンスがない、TRIAL ファイル、Signer が含まれていないライセンス、またはバージョン期間外の有料ライセンス | Signer を付与するライセンスをインストールするか、AddPlugin<SignerPlugin>() を削除してください |
イベントログに AddSignerWidget() was called but the Signer plugin is not registered. が表示されます | ウィジェットがプラグインなしで有効になっています | options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>() を追加してください |
イベントログに 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. が表示されます | パスワードが間違っている、または PKCS#12 ファイルではありません | パスワードを確認し、実際の .pfx を使用してください |
イベントログに Doconut Signer: the signing certificate has no private key. Re-export the .pfx INCLUDING the private key. が表示されます | PFX が秘密鍵なしでエクスポートされました | 秘密鍵付きで再度エクスポートしてください |
new SigningCertificate { … } がコンパイルできません | プロジェクトは C# 7.3 を使用しており、init-only プロパティを設定できません | <LangVersion> を 9.0 以降に設定してください |
DocumentSigner の解決時に No IDocumentSigner is registered. がスローされます | SignerPlugin が登録されていません | DoconutHost.Initialize に AddPlugin<SignerPlugin>() を追加してください |
| 出力に透かしが入ります | ライセンスが一時的です(デモ/NFR) | Signer を付与する有料ライセンスを使用してください |
run が 400 No signing certificate configured. と応答します | 有料ライセンス、Certified モード、証明書がない場合 | SigningCertificate を構成するか、Visual モードで署名してください |
run が 400 The signing certificate expired on yyyy-MM-dd. と応答します | 証明書が期限切れです | 交換してください;その間、Visual 署名は引き続き機能します |
ウィジェットは読み込まれますが、Signing is not enabled on this server. と表示されます | AddSignerWidget() が呼び出されていないか、basePath が '/DocImage.axd' ではありません | AddSignerWidget() を呼び出し、basePath: '/DocImage.axd' を設定してください |
| 大容量のアップロードでウィジェットのメッセージではなく IIS エラーページが表示されます | maxRequestLength / maxAllowedContentLength が MaxUploadMb 未満です | 両方のホスト制限を MaxUploadMb 以上に引き上げてください |
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 分のウィンドウが経過したか、ファーム内の別サーバーにアップロードがありません | ファイルを再度開いてください;ファーム内では AddDoconutDistributedWidgets を登録してください |
署名された .docx が一部のビューアで署名が表示されません | Word 出力には OOXML パッケージ署名が含まれますが、多くのビューアはそれを表示しません | デフォルトの PDF に署名してください |
| PDF リーダーは署名者の身元が不明であると表示します | リーダーは証明書のルートを信頼していません(デモ証明書は決して信頼されません) | 読者が信頼するルートからの証明書を使用してください |
| UI が別オリジンにあるとウィジェットが失敗します | エンドポイントに CORS サポートがありません | UI を同一オリジンから提供するか、DocImage.axd と /doconut-res をリバースプロキシしてください |
| テーマが適用されません | セレクタがマウント内部の要素を対象にしています | マウント自体を対象にしてください:#host.dsw または #host |
フレームワークノート
ASP.NET Core パッケージと比較すると、このパッケージはホスティングのみが異なります。API、エンドポイント契約、ウィジェットスクリプト、ライセンス規則は同じです。
- 登録 は
Application_Startにあり、DoconutHost.Initializeを通じて行われ、builder.Services.AddDoconutの代わりです。AddDoconutDistributedWidgetsのようなサービスは第2引数に渡します。 - エンドポイント は
DocImage.axdによって提供され、スクリプトはDoconutResourceModuleによって提供され、両方ともWeb.configに登録されます。UseDoconut()とUseDoconutResources()の代わりです。ウィジェットにはbasePath: '/DocImage.axd'が必要です。 - 起動失敗 は各リクエストで空の
500として現れ、理由は Windows のイベントログに記録されます。 - アップロード は Doconut が見る前に ASP.NET によって全体が読み込まれるため、IIS の制限は
MaxUploadMbより上である必要があります。 - 起動時のログ行なし 証明書に関して: 3 つの証明書エラーは依然としてスローされますが、証明書名を示す行は書き込まれません。
- C# 9.0 以降 が
SigningCertificateの init-only プロパティを設定するために必要です。 - Windows のみ、.NET Framework パッケージの残りと同様です。
このページは役に立ちましたか?