サイナープラグイン

可視署名とデジタルシールで 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.NET6.Signer

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

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

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

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

プラットフォーム。 プラグインは Doconut.NET6 が動作する環境であればどこでも動作します: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 を付与する有料ライセンス、証明書なし起動拒否: No signing certificate configured.クリーン
有料ライセンス、証明書が期限切れまたはまだ有効でない起動(ウィジェットが有効で、警告がログに記録されます)拒否: 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 (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 (デフォルト)ドキュメントは 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 としてログに記録され、置き換えられるまで認証済み署名は拒否されます。ビジュアル署名は影響を受けません。
  • 文書署名用に発行: キー使用法に digital signature または non-repudiation が含まれ、拡張キー使用法があれば文書署名、メール保護、クライアント認証を許可するもの。TLS サーバー証明書など別の目的で発行された証明書でも署名は可能ですが、Warning としてログに記録され、PDF リーダーは署名にフラグを付けます。
  • ハードウェアトークン、スマートカード、HSM、Windows 証明書ストアはサポートされていません。証明書をプライベートキーとチェーンと共にエクスポートして PFX にしてください。

証明書とそのプライベートキーから PFX を作成(OpenSSL 使用):

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 (multipart, one file)PDF または .docx をアップロードし、プレビュー用に開きます200 — { token, name, pages, ext }
POST ?sign=run (JSON body)アップロードされたファイルに署名します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.payloaddata: プレフィックスなしのベアな 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 です。

ルートステータス条件本文
any404ウィジェットが有効化されていませんステータスのみ
any405誤った HTTP メソッド(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: 署名する 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 と同じオリジンから提供するか、/doconut の両方のパス(ミドルウェアパスとリソースパス)を UI のオリジン下でリバースプロキシしてください。

本番環境で

  1. プラグインをインストール コアパッケージの隣に、同じバージョンで: dotnet add package Doconut.NET6.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 と SignatureKind(可視署名 と 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(署名モード と Word 出力)

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 署名のみが使用されます。

トラブルシューティング

症状原因対策
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() が呼び出されていない、または basePath が UseDoconut() のマウント位置と一致しません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 分のウィンドウが経過した、またはウェブファームノードにアップロードがありませんファイルを再度開いてください;ファーム環境では AddDoconutDistributedWidgets を登録してください
署名された .docx が一部のビューアで署名が表示されませんWord 出力は OOXML パッケージ署名を含んでおり、多くのビューアは表示しませんデフォルトの PDF に署名してください
PDF リーダーが署名者の身元が不明だと言いますリーダーが証明書のルートを信頼していません(デモ証明書は決して信頼されません)リーダーが信頼するルートからの証明書を使用してください
UI が別オリジンにあるとウィジェットが失敗しますエンドポイントに CORS サポートがありませんUI を同一オリジンから提供するか、Doconut パスをリバースプロキシしてください
テーマが適用されませんセレクタがマウント内部の要素を対象にしていますマウント自体を対象にしてください:#host.dsw または #host

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