ドキュメント

拡張フィールド

基本のフィールドに加えて、形式 0.0.2 は次の任意フィールドを規定します。いずれも署名対象ペイロードに含まれるため、署名後に変更すると署名が破壊されます。連署の宣言(require)は「連署ワークフロー」、タイムスタンプは「長期保存」で説明します。

部分署名(scope)

マーカで囲んだセクションのみに署名します。セクション外の注記や記入欄は、署名後も署名を破壊せずに編集できます。

セクションマーカ

  1. <!-- mdsig:section id --> と <!-- /mdsig:section --> の行で囲む。各マーカは単独で1行を占める。
  2. ID は [a-z0-9-]+。入れ子と同じ ID の重複は不可で、開始マーカには終了マーカが必要。
  3. フェンスで囲まれたコードブロック内のマーカは無視する。

検証

  1. ハッシュの入力は、列挙した各セクションの normalize(section) を列挙順に連結したもの。
  2. マーカが規則に違反していれば malformed、列挙した ID が見つからなければ invalid(scope-missing)。
  3. 検証者は、有効と報告するすべての箇所で部分署名であることを表示する(例:valid (partial: terms, fees))。

scope のないブロックは、セクションを含むスライス全体を対象とします。セクション外の編集後もチェーンを有効に保つには、後続の署名者全員が scope を使用する必要があります。scope を持つブロックは require を満たしません。

terms と fees のみに署名した文書
# Statement of Work

<!-- mdsig:section terms -->
## Terms
Delivery by 2026-12-31.
<!-- /mdsig:section -->

## Notes
(editable after signing)

<!-- mdsig:section fees -->
## Fees
JPY 1,200,000
<!-- /mdsig:section -->

<!-- md-signature
…
scope: section:terms,section:fees
…
-->
hash = H(normalize(terms) || normalize(fees))
mdsig sign sow.md -m tofu -s alice@laptop -k ~/.mdsig/alice --scope terms,fees

添付ファイルの固定(resources)

文書が参照するスクリーンショット、図、データファイル、URL を SHA-256 で固定します。本文だけでなく、参照先の差し替えも検出できます。

参照の書式

  • 各行は sha256:<16進数> <ref>。ハッシュはファイルまたは HTTP 応答本文の正確なバイト列に対して計算する。
  • ref は https:// の URL、または文書のディレクトリを基準とする相対パス。絶対パス、ドライブレター、\、.. は使用できない。

検証

状況 結果
ローカルのファイルが存在しない invalid · resource-missing
ハッシュが一致しない(ローカル、URL とも) invalid · resource-mismatch
URL を取得しない(既定) 未検査と報告する
URL を取得できない unresolved

URL を取得すると、文書が検証されていることが配信元に伝わります。このため URL は利用者が要求した場合のみ取得し、https:// に限り、応答は 50 MB まで、プライベートアドレスへの接続は拒否します。

resources の値
resources: |
  sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 ./diagram.png
  sha256:8f434346648f6b96df89dda901c5176b10a6d83961dd3c1ac88b59b2dc327aa4 https://example.com/chart.png
CLI で固定する、URL も検証する
mdsig sign report.md -m git-hosting -s github.com/alice \
  --resource ./data.csv --auto-resources
mdsig verify --fetch-resources report.md

--auto-resources は、コードフェンスの外で ![..](..) や <img src> が参照するローカル画像をすべて固定します。リモートの内容は CDN の再エンコードなどで変化しうるため、長期の証拠にはローカルのコピーを固定してください。

有効期限(expires)

署名の有効期限です。見積書の有効期間や、一定期間だけ有効な承認に使用します。

  • 形式は ts と同じ YYYY-MM-DDTHH:MM:SSZ。実在しない日時(2月30日、24時など)は malformed。
  • 検証者の時計で期限を過ぎていれば invalid(expired)。
  • CLI の --expires は日時のほか、現在からの期間(30d、12h)を受け付ける。
expires: 2027-03-31T23:59:59Z
mdsig sign quote.md -m git-hosting -s github.com/alice --expires 30d

撤回(revocation_url)

署名者は、自身の撤回リストの https:// URL を署名に含められます。リスト自体も md-signature 文書で、本文に撤回した署名ごとに revoked: の行を持ちます。

リストを信頼する条件

  1. リストを文書として検証し、成功する。
  2. リストのチェーンに、撤回対象のブロックと同じ method と signer(tofu はさらに同じ pubkey)を持つ有効なブロックがある。
  3. リストの検証では、リスト内の revocation_url、リモートのリソース、require を評価しない(循環の防止)。

検証の結果

ブロックの識別子が、信頼したリストに含まれる invalid · revoked
リストを取得できない、または信頼できない unresolved
利用者が取得を無効にした(--no-revocation)、オフライン 撤回は未検査と報告する。これだけでは無効にしない
署名ブロック内のフィールド
revocation_url: https://example.com/.well-known/mdsig-revoked.md
撤回リスト(それ自体が署名済み文書)
# Revoked signatures

revoked: sha256:6f1e…c2a9
revoked: sha256:0b7d…41fe

<!-- md-signature
method: dns
signer: example.com
…
-->
mdsig revoke contract.md --list mdsig-revoked.md -m dns -s example.com -k ~/.mdsig/example

識別子は撤回対象ブロックの署名対象ペイロードの SHA-256 です。ECDSA や OpenPGP の署名は秘密鍵なしで別のバイト列に変形できるため、sig から計算すると撤回を回避されます。mdsig revoke は識別子を計算してリストに追記し、リストに署名し直します。

アルゴリズムと私的拡張

alg

ed25519 は実装必須。webauthn-es256・openpgp・rfc3161 は検証の実装を推奨。ml-dsa-44・ml-dsa-65・slh-dsa-sha2-128s・ed25519+ml-dsa-65 は予約済み。未対応のアルゴリズムは unsupported として報告。

x_*

x_ で始まるキーは自由に使用できます。意味は規定されませんが、署名対象ペイロードに含まれます。それ以外の未定義のキーを持つブロックは malformed(unknown-field)となるため、将来の拡張が理解されないまま受理されることはありません。

仕様書 §5.6 セクション署名§5.7 外部リソース§5.9 有効期限と撤回