ドキュメント

検証手順と結果

検証者はチェーンの各ブロックを順に検査し、ブロックごとにステータスを決定します。文書全体が検証済みとなるのは、すべてのブロックが valid の場合に限られます。

検査の手順と判定

ブロックごとの手順

  1. v がちょうど1つあり、その値が対応するバージョンでなければ、ほかのすべての検査より先に unsupported · unsupported-version
  2. ブロックを解析する。構文エラー、必須フィールドの欠落、未知のフィールドがあれば malformed
  3. スライス(scope 指定時はセクション)のダイジェストを計算し、hash と比較する。不一致なら invalid · hash-mismatch
  4. ペイロードを構築し、method で候補鍵を解決する。ネットワーク起因の失敗は invalid と区別して unresolved
  5. 各候補鍵で sig を検証する。どの鍵でも成立しなければ invalid · bad-signature
  6. expires を過ぎていれば invalid · expired
  7. resources、revocation_url、tsa_token があれば、それぞれ検査する。

method: tsa のブロックは手順 4 以降を、pubkey を持つ dns・git-hosting のブロックは手順 4 と 5 を、それぞれ専用の手順で置き換えます(「長期保存」を参照)。

文書が verified となる条件は、チェーンにブロックが1つ以上あり、すべてが valid で、最後のブロックの後に未署名の内容がなく、合意が順序違反(violated)でないことです。require が満たされていなければ verified but pending となり、検証者はこれを完了として提示してはなりません。

合意ステータス

none
要件なし
complete
すべて充足
pending
不足あり(不足する連署を列挙)
violated
order strict の順序違反(違反した署名を列挙)

ステータス

status 意味 主な code
valid すべての検査に合格した。 null
invalid 改ざん、期限切れ、撤回など。 hash-mismatch bad-signature expired revoked key-changed scope-missing resource-mismatch resource-missing
malformed ブロックとして解釈できない。 malformed unknown-field
unresolved 判定を確定できない。鍵・撤回リスト・リソースの取得失敗、信頼できない撤回リスト、未公開の埋め込み鍵、証明書チェーンを検証できない <code>tsa</code> ブロックなど。 network not-found offline key-not-published
unsupported 未対応のバージョン・アルゴリズム・方式。有効とは報告しない。 unsupported-version unsupported-alg unsupported-hash unsupported-method

mdsig verify の終了コード

0 すべての署名が有効
1 検証失敗:ハッシュ不一致、不正な署名、形式不正、未対応、署名なし、末尾の未署名内容、合意の順序違反(violated)など
2 使い方の誤り:未知のフラグ、引数の欠落、無効なフィールド値
3 ネットワークまたは公開鍵の解決のエラー、または --offline で未検査の署名がある(終了コード 1 となる失敗がない場合)
4 ファイル I/O またはパーミッションのエラー
5 すべての署名は有効だが、require の連署が不足(pending)

複数ファイルの場合は最も重大なコードを返します(1 > 4 > 3 > 5 > 0)。

仕様書 §5.4 検証手順CLI 仕様 §4 終了コード

JSON 出力の読み方

mdsig verify --json は、言語設定にかかわらず英語のキーと値で結果を出力します。TypeScript の toJsonResult、Go の mdsig.ToJSON、検証サーバの /v1/verify も同じ形です。

mdsig verify --json contract.md
{
  "files": [
    {
      "file": "contract.md",
      "ok": true,
      "error": null,
      "warnings": [],
      "agreement": { "status": "complete", "required": [ … ], "missing": [], "violations": [] },
      "signatures": [
        {
          "index": 1,
          "line": 12,
          "status": "valid",
          "code": null,
          "fields": { "v": "0.0.2", "method": "git-hosting", "signer": "github.com/alice", … },
          "hash_ok": true,
          "key_source": "https://github.com/alice.keys (SHA256:…)",
          "tsa": { "status": "ok", "verified": true, "gen_time": "2026-11-16T09:46:02Z", … },
          …
        }
      ]
    }
  ]
}

判定に使用する値

  • ok:そのファイル単独で終了コードが 0 または 5 となる場合に true。合意が violated の場合、および --offline で未検査のブロックがある場合は false。
  • agreement.status:ok が true でも pending なら連署が不足しています。完了の判定にはこの値も確認します。
  • signatures[].status と code:ブロックごとの判定。key_source は鍵の取得元を示します。
  • tsa.verified:TSA の署名と証明書チェーンを検証できた場合のみ true となり、そのときに限り gen_time が値を持ちます。

ライブラリの結果(VerifyResult)は同じ情報を持ちます。キーの表記は TypeScript がキャメルケース、JSON がスネークケースです。

CLI 仕様 §5 JSON 出力