署名プラグイン

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

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

表面使用シーン
DocumentSigner (C#)サーバー上で署名し、ブラウザは関与しません
ドロップインウィジェット (doconutSigner.js)ページ内に既成のアップロード、署名、ダウンロード画面が欲しい場合
HTTP エンドポイント(DocImage.axd)(?sign=open|run|download)文書化されたサーバー契約に対して独自の署名 UI を構築したい場合

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

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

powershell
Install-Package Doconut.NETFramework.Signer

このドキュメントで説明しているリリースにプラグインを固定するには:

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

Signer パッケージは Doconut.NETFramework と同じバージョンに保ってください。

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

プラグインの登録

すべての Doconut プラグインと同様に、Signer は AddPlugin<TPlugin>() を DoconutHost.Initialize に登録し、Application_Start から呼び出されます:

csharp
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 から例外をスローします:

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.

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>(). がスローされます

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, 81920, ct);
            return output.ToArray();
        }
    }
}

SignAsync はソースストリーム、その拡張子(".pdf" または ".docx")、リクエスト、そして証明書 この呼び出し用に 受け取ります。ファサードは SignerWidgetOptions.SigningCertificate を読み取りません;その設定はウィジェット用です。デモライセンス下、または Visual モードで null を渡してください。

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

MVC 5 コントローラで

アクションを非同期にし、署名を await してください。このものは Visual 署名をスタンプし、証明書は不要です:

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);
}

Word ソースは、Word 出力を要求しない限り PDF に署名されます。結果は 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 は呼び出しが成功しない場合に返す代わりに例外をスローします:

例外メッセージ条件
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 (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 は決して提供しないためです:

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"] ?? "",
        };
    });
});

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 を作成:

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 内の証明書が 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 によって提供され、デフォルトでは オフ です。プラグイン登録の横でそれらを有効化してください:

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;           // デフォルト
        widget.MaxSignatureImageKb = 512;  // デフォルト
        // widget.SigningCertificate: 証明書の設定を参照してください; デモ(透かし入り)署名のために null のままにしてください
    });
});
// System.Web は Doconut が見る前にアップロード全体を読み取ります: maxRequestLength (KB) と
// Web.config の widget の MaxUploadMb の上にある maxAllowedContentLength (bytes)

AddSignerWidget() は引数なしでウィジェットをデフォルト設定で有効にします。それだけでは署名権限は付与されません:AddPlugin<SignerPlugin>() が必要です、または DoconutHost.Initialize がスローします:

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.

エンドポイントとスクリプトはハンドラと 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>

モジュールはウィジェットが有効かどうかに関わらずスクリプトを提供します。AddSignerWidget() がない場合、ウィジェットは読み込まれドロップゾーンを描画しますが、最初のリクエストは 404 で応答します:ウィジェットはその後 Signing is not enabled on this server. を報告します。

アップロード制限

ASP.NET は DocImage.axd が実行される前にリクエストボディ全体を読み取ります。MaxUploadMb を超えホストの制限未満のアップロードはウィジェット独自の JSON 413(File is too large.)を取得します。ホストの制限を超えるアップロードはまず IIS によって拒否され、ウィジェットが読み取れないエラーページが返されます。ホストの制限はウィジェットの上限よりも高く保ってください:

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>

Content-Length(チャンク)なしで送信されたアップロードがホストの制限を超える場合も、IIS のエラーページが返されます;このケースに対する回避策はありません。

埋め込む

スクリプトは /doconut-res/js/doconutSigner.js で提供されます。単一の自己完結型ファイルで、依存関係はありません。basePath をハンドラに設定してください:

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) は CSS セレクタまたは要素を受け取り、マウントが見つからない場合は例外をスローし、ハンドルを返します。ウィジェットのデフォルト basePath、/doconut は ASP.NET Core エンドポイントです。このパッケージでは '/DocImage.axd' である必要があります。

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

オプション

オプション型デフォルト備考
basePathstring'/doconut'?sign= エンドポイントとプレビュー画像が提供される場所です。このパッケージで '/DocImage.axd' を設定してください
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: '/DocImage.axd', licenseUrl: '/pricing' });
javascript
// 視覚的のみ、トグルなし: デジタル署名が提供されないシンプルなスタンプ。
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()リスナーを削除し、マウントを空にし、インスタンスを凍結します
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());

ラベル

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

KeyEnglish default
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;   /* タイプモード */
}

デフォルト: --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 本文:

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プレーンな base64 PNG、data: プレフィックスなし。実際の 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 です。

ルートステータス条件本文
any404ウィジェットが有効ではありませんステータスのみ
any405誤った動詞(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 を超えています(ただし IIS の制限は超えていません)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: 署名する 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 をリバースプロキシしてください。

本番環境で

  1. プラグインをインストール してください。コアパッケージと同じバージョンで隣に置きます: Install-Package Doconut.NETFramework.Signer.

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

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

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

    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"] ?? "",
        });
    });

    .pfx を App_Data に保管してください。IIS は決して提供しません。また、パスワードを平文の Web.config に置かないでください。暗号化された設定セクション、またはデプロイ時に読み取るシークレットストアを使用します.

  5. 認証モードでテスト文書に署名します。期限切れまたはまだ有効でない証明書は 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引数を通じて、共有かつ暗号化されたウィジェットストアを登録してください:

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";   // すべてのサーバーが読み書きできるフォルダー
        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);
}

DoconutHost.Services から解決されます。コンストラクタは 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 と 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 と 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 を設定します。セッターは init-only で、プロジェクトは C# 9.0 以降が必要です。

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 署名は有料ライセンス時のみ使用できます。

トラブルシューティング

症状原因対策
プラグインを追加した後、すべてのリクエストが空の 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 パッケージの残りと同様です。

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