ドキュメント
形式と署名の計算
署名ブロックの書式、ハッシュの対象となる範囲、秘密鍵が署名するバイト列を順に説明します。別の言語で実装する場合は、このページと検証手順のページが出発点になります。
署名ブロックの形式
署名ブロックは、<!-- md-signature の行で開始し
--> の行で終了する HTML コメントです。内部には key: value
形式のフィールドを1行に1つずつ記述し、文書の末尾に配置します。
| キー | 要否 | 内容 |
|---|---|---|
v |
必須 | 形式のバージョン。現行のバージョンは 0.0.2(0.0.1 も検証できる)。 |
method |
必須 | 公開鍵の解決方法。dns・git-hosting・pgp・tofu のいずれか。タイムスタンプ専用ブロックは tsa。 |
signer |
必須 | 署名者の識別子。構文は method
に依存する(github.com/alice、example.com など)。 |
ts |
必須 |
署名者が申告する署名時刻(UTC、YYYY-MM-DDTHH:MM:SSZ)。申告値にすぎず、第三者の証拠にはならない。 |
hash |
必須 | 対象スライスのダイジェスト。<hash-alg>: に続けて小文字の16進数。既定は sha256(tsa ブロックは sha512 も使用できる)。 |
sig |
必須 | 署名対象ペイロードに対する署名。base64:
に続けてパディング付きの標準 base64。 |
alg |
任意 | 署名アルゴリズム。省略時は ed25519。 |
role reason |
任意 | 役割(推奨値は author・reviewer・approver・witness)と、自由記述の理由。 |
selector key_fp pubkey
fpr |
条件付き | 方式ごとの鍵情報(「公開鍵の解決」で説明)。 |
rp_id webauthn_* |
条件付き | alg が
webauthn-es256 の場合は必須、それ以外の場合は記述不可。 |
expires scope require
resources revocation_url tsa_* |
任意 | 期限・部分署名・リソース・撤回(「拡張フィールド」)、必須の連署(「連署ワークフロー」)、タイムスタンプ(「長期保存」)。 |
x_* |
任意 | 私的利用の拡張。意味は規定されないが、署名対象ペイロードに含まれる。 |
<!-- md-signature
v: 0.0.2
method: tofu
signer: bob@laptop
pubkey: ed25519:/FHNjmIYoaONpH7QAjDwWAgW7RO6MwOsXeuRFUiQgCU=
role: author
reason: Initial draft
ts: 2026-11-16T09:00:00Z
alg: ed25519
hash: sha256:f06c734545219e83074ab04481e4b4715054a8f1ac88367c90d2ce24bc76705c
sig: |
base64:L+agHbaU8iBuejrzPWgQpCrXjJoWmtyKYGho0iGOWzy/XNIsWF0CwRQTLf5azW0Gubg1x
bp5QDS+poEfmIodBA==
-->
構文規則
- 開始行は
<!-- md-signature、終了行は-->のみで構成する。フィールドの順序は任意で、同じキーの重複は malformed。 - 空行を含めない。CommonMark は空行で HTML ブロックを終了するため、以降の行が表示されてしまう。
- 値に
--と制御文字を含めない。--はコメントを途中で終了させ、可視の Markdown を注入される原因になる。生成者はこの入力を修正せず拒否する。 key: |と2スペース字下げの継続行で折り返し値となり、各行をLFで連結して扱う。リストと、76文字を超えるバイナリ値に使用する。- 本書で未定義のキーは
malformed(
unknown-field)。x_で始まるキーのみ例外。将来の拡張を解釈しない検証者による誤判定を防止する。
正規化とハッシュチェーン
各ブロックの hash は、ファイル先頭からそのブロックの開始行の直前までのバイト列(スライス)を正規化して計算します。後続の署名者は先行するブロックも含めて署名するため、署名は追記専用のチェーンを形成します。
正規化 normalize(S)
- 先頭の UTF-8 BOM(
EF BB BF)を除去する。 CRLFをLFに置換し、残ったCRもLFに置換する。- 末尾の
LF・SP・HTABをすべて除去する。 LFをちょうど1つ付加する。
Unicode 正規化は行わないため、NFC と NFD は別の文書として扱われます。これ以外のバイトを変更すると、文書内部の空白であっても署名は破壊されます。文書は有効な UTF-8 であることが必要です。
チェーンの検出
- ファイル末尾から走査し、末尾の空白は無視する。
- 最終行が
-->であれば、直前の<!-- md-signatureまでを1つのブロックとして読む(間の行がすべて有効なフィールド行の場合)。ブロック間の空白行を読み飛ばして繰り返す。 - ブロックでも空白でもないテキストに到達した時点で停止する。そこまでが本文。
本文中のブロック(後ろに文章が続くコード例など)はチェーンに含まれず、検証されません。最後のブロックの後に空白以外のテキストがある場合、そのテキストはどの署名の対象でもないため、検証は失敗します。生成者も、この状態の文書への連署を拒否します。
hash₁ = "sha256:" hex(SHA-256(normalize(slice₁)))
hash₂ = "sha256:" hex(SHA-256(normalize(slice₂)))
ブロック 1 の値を1文字でも変更すると slice₂ が変化し、ブロック 2 の hash が一致しなくなります。
署名対象ペイロード
秘密鍵で署名する対象は、ブロックのフィールドから組み立てた短いテキストです。このテキストに hash が含まれるため、1つの署名で文書本体とメタデータの両方を保護します。
組み立て手順
- フィールドから
sig、tsa_url、tsa_token、webauthn_authenticator_data、webauthn_client_dataを除外する。 - キーを ASCII バイト列として比較し、昇順に整列する。
- 各フィールドを
key=valueとして出力する。値内のLFはLFと2スペースとして出力する。キーは英小文字で始まるため、継続行が別のフィールドと誤認されることはない。 LFで連結し(末尾にLFは付けない)、先頭にmd-signature/v1とLFを付加する。- UTF-8
でエンコードし、
sig = "base64:" + base64(Sign(private-key, payload))を計算する。
この設計の帰結
-
signer・role・reason・tsもペイロードに含まれるため、いずれかを変更すると署名は破壊されます。 tsa_urlとtsa_tokenはペイロード外なので、タイムスタンプは署名後に追加できます。- 先頭行
md-signature/v1はドメイン分離用です。git-hostingは SSH 認証用の鍵を再利用するため、この行によって SSH 認証データや他プロトコルの署名対象と区別します。
<!-- md-signature
v: 0.0.2
method: tofu
signer: bob@laptop
pubkey: ed25519:/FHNjmIYoaONpH7QAjDwWAgW7RO6MwOsXeuRFUiQgCU=
role: author
reason: Initial draft
ts: 2026-11-16T09:00:00Z
alg: ed25519
hash: sha256:f06c734545219e83074ab04481e4b4715054a8f1ac88367c90d2ce24bc76705c
sig: |
base64:L+agHbaU8iBuejrzPWgQpCrXjJoWmtyKYGho0iGOWzy/XNIsWF0CwRQTLf5azW0Gubg1x
bp5QDS+poEfmIodBA==
-->
md-signature/v1
alg=ed25519
hash=sha256:f06c734545219e83074ab04481e4b4715054a8f1ac88367c90d2ce24bc76705c
method=tofu
pubkey=ed25519:/FHNjmIYoaONpH7QAjDwWAgW7RO6MwOsXeuRFUiQgCU=
reason=Initial draft
role=author
signer=bob@laptop
ts=2026-11-16T09:00:00Z
v=0.0.2