ドキュメント
拡張フィールド
基本のフィールドに加えて、形式 0.0.2 は次の任意フィールドを規定します。いずれも署名対象ペイロードに含まれるため、署名後に変更すると署名が破壊されます。連署の宣言(require)は「連署ワークフロー」、タイムスタンプは「長期保存」で説明します。
部分署名(scope)
マーカで囲んだセクションのみに署名します。セクション外の注記や記入欄は、署名後も署名を破壊せずに編集できます。
セクションマーカ
<!-- mdsig:section id -->と<!-- /mdsig:section -->の行で囲む。各マーカは単独で1行を占める。- ID は
[a-z0-9-]+。入れ子と同じ ID の重複は不可で、開始マーカには終了マーカが必要。 - フェンスで囲まれたコードブロック内のマーカは無視する。
検証
- ハッシュの入力は、列挙した各セクションの
normalize(section)を列挙順に連結したもの。 - マーカが規則に違反していれば malformed、列挙した ID が見つからなければ invalid(
scope-missing)。 - 検証者は、有効と報告するすべての箇所で部分署名であることを表示する(例:valid (partial: terms, fees))。
scope のないブロックは、セクションを含むスライス全体を対象とします。セクション外の編集後もチェーンを有効に保つには、後続の署名者全員が scope を使用する必要があります。scope を持つブロックは require を満たしません。
# 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: |
sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 ./diagram.png
sha256:8f434346648f6b96df89dda901c5176b10a6d83961dd3c1ac88b59b2dc327aa4 https://example.com/chart.png
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: の行を持ちます。
リストを信頼する条件
- リストを文書として検証し、成功する。
- リストのチェーンに、撤回対象のブロックと同じ
methodとsigner(tofuはさらに同じpubkey)を持つ有効なブロックがある。 - リストの検証では、リスト内の
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)となるため、将来の拡張が理解されないまま受理されることはありません。