第183回 鍵数だけで職務分離とみなさない:Pythonで検証する役割別Ed25519承認

第182回では、許可した3本のEd25519鍵から、異なる2鍵以上の有効な署名を数えました。しかし、2本ともレビュー担当用の鍵なら、実行担当の承認まで得たことにはなりません。

今回は、公開鍵をreviewerとoperatorへ割り当て、同じ対象に両役割の有効な署名があるかを検証します。同じ鍵の重複、許可外鍵、不正署名、ポリシーや承認対象の取り違えは拒否します。

ただし、役割名は人の身元を証明しません。一人が両方の秘密鍵を管理していれば、コード上の条件は満たせます。秘密鍵を別の担当者や装置で管理することは、実装とは別の運用条件です。

鍵数と役割数は別に判定する

署名の組み合わせ 異なる鍵が2本 今回の役割条件
reviewer鍵+operator鍵 満たす 満たす
reviewer鍵+別のreviewer鍵 満たす operatorがないため拒否
同じreviewer鍵を2回掲載 満たさない 重複署名者として拒否
許可外鍵+operator鍵 許可鍵の条件を満たさない 許可外鍵があるため文書全体を拒否

ポリシーでは、32バイトの生公開鍵に対するSHA-256を鍵IDにします。同じ公開鍵を異なる役割へ二重登録しても、鍵IDが一致するため拒否されます。ただし、同じ人が別々の鍵を持つことまでは検出できません。

今回の実行契約

項目 仕様
動作環境 Python 3.11以上、cryptography 50.0.2。実行例はPOSIXシェル向け
ポリシー 16,384バイト以下。必要役割は2~8件、許可鍵は最大32件
署名対象JSON 8,192バイト以下。ポリシーID、ポリシーの正規化SHA-256、対象ファイルのSHA-256を保持する
承認文書 32,768バイト以下。署名は1~32件
署名 署名対象JSONを本稿の規則で正規化したUTF-8バイト列へEd25519で署名する
対象ファイル 内容を解釈せず、生のバイト列をSHA-256で照合する。検証中に変更されないことが前提
成功時 標準出力へ1行JSONを出し、終了コード0
検証失敗 標準エラー出力へ1行JSONを出し、終了コード1
引数誤り argparseのメッセージを出し、終了コード2

cryptography 50.0.2のEd25519 APIでは、生公開鍵は32バイト、署名は64バイトです。verify()は検証成功時にNoneを返し、不一致ならInvalidSignatureを送出します。

Python 3.11のjsonドキュメントにあるとおり、標準のデコーダーは重複したキーを自動では拒否しません。この実装ではobject_pairs_hookで重複を検出し、非有限数と入力サイズも制限します。

ポリシーと承認対象を結び付ける

  1. ポリシーJSONをキー順、空白なし、UTF-8で正規化し、SHA-256を計算する。
  2. その値が、別経路で設定した--expected-policy-sha256と一致することを確認する。
  3. 署名対象JSONへポリシーID、ポリシーSHA-256、対象ファイルのSHA-256を記録する。
  4. 承認者は署名対象JSONの正規化バイト列へ署名する。
  5. 検証側はすべての掲載署名を検証し、必要な役割が揃ってから対象ファイルを照合する。

正規化は本稿のPythonコードで定義するローカルな契約であり、汎用的なJSON正規化規格ではありません。オブジェクトのキー順や空白が変わっても、同じ値なら同じ正規化結果になります。一方、対象ファイルは生のバイト列をハッシュ化するため、末尾改行を含む1バイトの違いも不一致になります。

1.役割別承認を検証するCLI

次をverify_role_approval.pyとして保存します。

#!/usr/bin/env python3
import argparse
import base64
import binascii
import hashlib
import json
import re
import sys
from pathlib import Path

from cryptography.exceptions import InvalidSignature, UnsupportedAlgorithm
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey

MAX_POLICY_BYTES = 16_384
MAX_TARGET_BYTES = 8_192
MAX_APPROVALS_BYTES = 32_768
POLICY_SCHEMA = "manage-ai-role-policy-v1"
TARGET_SCHEMA = "manage-ai-role-approval-target-v1"
APPROVALS_SCHEMA = "manage-ai-role-approvals-v1"
HEX64_RE = re.compile(r"[0-9a-f]{64}\Z")
POLICY_ID_RE = re.compile(r"[A-Za-z0-9][A-Za-z0-9._-]{0,63}\Z")
ROLE_RE = re.compile(r"[a-z][a-z0-9_-]{0,31}\Z")


class ApprovalError(Exception):
    pass


def duplicate_safe_object(pairs):
    result = {}
    for key, value in pairs:
        if key in result:
            raise ApprovalError(f"duplicate JSON key: {key}")
        result[key] = value
    return result


def reject_constant(value):
    raise ApprovalError(f"non-finite number is not allowed: {value}")


def read_json(path, limit, label):
    try:
        with path.open("rb") as stream:
            data = stream.read(limit + 1)
    except OSError as exc:
        detail = exc.strerror or str(exc)
        raise ApprovalError(
            f"{label}: cannot read file: {detail}"
        ) from exc
    if len(data) > limit:
        raise ApprovalError(f"{label}: file exceeds {limit} bytes")
    if data.startswith(b"\xef\xbb\xbf"):
        raise ApprovalError(f"{label}: UTF-8 BOM is not allowed")
    try:
        text = data.decode("utf-8")
    except UnicodeDecodeError as exc:
        raise ApprovalError(
            f"{label}: file is not valid UTF-8"
        ) from exc
    try:
        return json.loads(
            text,
            object_pairs_hook=duplicate_safe_object,
            parse_constant=reject_constant,
        )
    except ApprovalError:
        raise
    except (ValueError, RecursionError) as exc:
        raise ApprovalError(f"{label}: invalid JSON: {exc}") from exc


def require_exact_fields(value, fields, label):
    if not isinstance(value, dict):
        raise ApprovalError(f"{label}: must be a JSON object")
    actual = set(value)
    missing = sorted(fields - actual)
    extra = sorted(actual - fields)
    if missing or extra:
        details = []
        if missing:
            details.append("missing=" + ",".join(missing))
        if extra:
            details.append("unexpected=" + ",".join(extra))
        raise ApprovalError(
            f"{label}: wrong fields ({'; '.join(details)})"
        )


def require_string(value, pattern, label):
    if not isinstance(value, str) or pattern.fullmatch(value) is None:
        raise ApprovalError(f"{label}: invalid string")
    return value


def require_hex64(value, label):
    if not isinstance(value, str) or HEX64_RE.fullmatch(value) is None:
        raise ApprovalError(
            f"{label}: must be 64 lowercase hexadecimal characters"
        )
    return value


def decode_base64(value, length, label):
    if not isinstance(value, str):
        raise ApprovalError(f"{label}: must be a base64 string")
    try:
        raw = base64.b64decode(value, validate=True)
    except (binascii.Error, ValueError) as exc:
        raise ApprovalError(f"{label}: invalid base64") from exc
    if base64.b64encode(raw).decode("ascii") != value:
        raise ApprovalError(
            f"{label}: base64 is not in canonical form"
        )
    if len(raw) != length:
        raise ApprovalError(
            f"{label}: decoded length must be {length} bytes"
        )
    return raw


def canonical_bytes(value):
    return json.dumps(
        value,
        ensure_ascii=False,
        allow_nan=False,
        sort_keys=True,
        separators=(",", ":"),
    ).encode("utf-8")


def validate_policy(policy):
    require_exact_fields(
        policy,
        {"schema", "policy_id", "required_roles", "keys"},
        "policy",
    )
    if policy["schema"] != POLICY_SCHEMA:
        raise ApprovalError("policy.schema: unsupported value")
    policy_id = require_string(
        policy["policy_id"], POLICY_ID_RE, "policy.policy_id"
    )

    roles = policy["required_roles"]
    if not isinstance(roles, list) or not 2 <= len(roles) <= 8:
        raise ApprovalError(
            "policy.required_roles: must contain 2 to 8 roles"
        )
    checked_roles = [
        require_string(role, ROLE_RE, f"policy.required_roles[{index}]")
        for index, role in enumerate(roles)
    ]
    if len(set(checked_roles)) != len(checked_roles):
        raise ApprovalError("policy.required_roles: duplicate role")

    entries = policy["keys"]
    if (
        not isinstance(entries, list)
        or not len(checked_roles) <= len(entries) <= 32
    ):
        raise ApprovalError(
            "policy.keys: count must be between the number of roles and 32"
        )

    keys = {}
    represented_roles = set()
    for index, entry in enumerate(entries):
        label = f"policy.keys[{index}]"
        require_exact_fields(
            entry, {"key_id", "role", "public_key_b64"}, label
        )
        key_id = require_hex64(entry["key_id"], f"{label}.key_id")
        role = require_string(entry["role"], ROLE_RE, f"{label}.role")
        if role not in checked_roles:
            raise ApprovalError(
                f"{label}.role: role is not required by this policy"
            )
        raw_key = decode_base64(
            entry["public_key_b64"], 32, f"{label}.public_key_b64"
        )
        if key_id != hashlib.sha256(raw_key).hexdigest():
            raise ApprovalError(
                f"{label}.key_id: does not match the public key"
            )
        if key_id in keys:
            raise ApprovalError(f"{label}.key_id: duplicate key")
        try:
            public_key = Ed25519PublicKey.from_public_bytes(raw_key)
        except (ValueError, UnsupportedAlgorithm) as exc:
            raise ApprovalError(
                f"{label}.public_key_b64: unusable Ed25519 key"
            ) from exc
        keys[key_id] = (role, public_key)
        represented_roles.add(role)

    missing_roles = sorted(set(checked_roles) - represented_roles)
    if missing_roles:
        raise ApprovalError(
            "policy.keys: no key registered for roles: "
            + ",".join(missing_roles)
        )
    return policy_id, checked_roles, keys


def validate_target(target):
    require_exact_fields(
        target,
        {"schema", "policy_id", "policy_sha256", "subject_sha256"},
        "target",
    )
    if target["schema"] != TARGET_SCHEMA:
        raise ApprovalError("target.schema: unsupported value")
    require_string(target["policy_id"], POLICY_ID_RE, "target.policy_id")
    require_hex64(target["policy_sha256"], "target.policy_sha256")
    require_hex64(target["subject_sha256"], "target.subject_sha256")


def validate_approvals(
    approvals, target_sha256, target_bytes, keys, required_roles
):
    require_exact_fields(
        approvals, {"schema", "target_sha256", "signatures"}, "approvals"
    )
    if approvals["schema"] != APPROVALS_SCHEMA:
        raise ApprovalError("approvals.schema: unsupported value")
    require_hex64(approvals["target_sha256"], "approvals.target_sha256")
    if approvals["target_sha256"] != target_sha256:
        raise ApprovalError(
            "approvals.target_sha256: does not match target"
        )

    signatures = approvals["signatures"]
    if not isinstance(signatures, list) or not 1 <= len(signatures) <= 32:
        raise ApprovalError(
            "approvals.signatures: must contain 1 to 32 entries"
        )

    seen_key_ids = set()
    valid_key_ids = []
    approved_roles = set()
    for index, entry in enumerate(signatures):
        label = f"approvals.signatures[{index}]"
        require_exact_fields(entry, {"key_id", "signature_b64"}, label)
        key_id = require_hex64(entry["key_id"], f"{label}.key_id")
        if key_id in seen_key_ids:
            raise ApprovalError(f"{label}.key_id: duplicate signer")
        seen_key_ids.add(key_id)
        if key_id not in keys:
            raise ApprovalError(
                f"{label}.key_id: key is not allowed by policy"
            )
        signature = decode_base64(
            entry["signature_b64"], 64, f"{label}.signature_b64"
        )
        role, public_key = keys[key_id]
        try:
            public_key.verify(signature, target_bytes)
        except InvalidSignature as exc:
            raise ApprovalError(
                f"{label}.signature_b64: invalid signature"
            ) from exc
        valid_key_ids.append(key_id)
        approved_roles.add(role)

    missing_roles = sorted(set(required_roles) - approved_roles)
    if missing_roles:
        raise ApprovalError(
            "required approval roles are missing: "
            + ",".join(missing_roles)
        )
    return sorted(valid_key_ids), sorted(approved_roles)


def sha256_file(path):
    digest = hashlib.sha256()
    try:
        with path.open("rb") as stream:
            while chunk := stream.read(1024 * 1024):
                digest.update(chunk)
    except OSError as exc:
        detail = exc.strerror or str(exc)
        raise ApprovalError(
            f"subject: cannot read file: {detail}"
        ) from exc
    return digest.hexdigest()


def verify(args):
    policy = read_json(args.policy, MAX_POLICY_BYTES, "policy")
    policy_id, required_roles, keys = validate_policy(policy)
    policy_sha256 = hashlib.sha256(canonical_bytes(policy)).hexdigest()
    if policy_sha256 != args.expected_policy_sha256:
        raise ApprovalError(
            "policy: canonical SHA-256 does not match expected value"
        )

    target = read_json(args.target, MAX_TARGET_BYTES, "target")
    validate_target(target)
    if target["policy_id"] != policy_id:
        raise ApprovalError("target.policy_id: does not match policy")
    if target["policy_sha256"] != policy_sha256:
        raise ApprovalError(
            "target.policy_sha256: does not match policy"
        )

    target_bytes = canonical_bytes(target)
    target_sha256 = hashlib.sha256(target_bytes).hexdigest()
    approvals = read_json(
        args.approvals, MAX_APPROVALS_BYTES, "approvals"
    )
    valid_key_ids, approved_roles = validate_approvals(
        approvals, target_sha256, target_bytes, keys, required_roles
    )

    subject_sha256 = sha256_file(args.subject)
    if subject_sha256 != target["subject_sha256"]:
        raise ApprovalError(
            "subject: SHA-256 does not match signed target"
        )

    return {
        "approved": True,
        "policy_id": policy_id,
        "policy_sha256": policy_sha256,
        "satisfied_roles": approved_roles,
        "subject_sha256": subject_sha256,
        "target_sha256": target_sha256,
        "valid_key_ids": valid_key_ids,
    }


def sha256_argument(value):
    if HEX64_RE.fullmatch(value) is None:
        raise argparse.ArgumentTypeError(
            "must be 64 lowercase hexadecimal characters"
        )
    return value


def parse_args():
    parser = argparse.ArgumentParser(
        description="Verify role-separated Ed25519 approvals."
    )
    parser.add_argument("--policy", required=True, type=Path)
    parser.add_argument("--target", required=True, type=Path)
    parser.add_argument("--approvals", required=True, type=Path)
    parser.add_argument("--subject", required=True, type=Path)
    parser.add_argument(
        "--expected-policy-sha256",
        required=True,
        type=sha256_argument,
    )
    return parser.parse_args()


def emit(value, stream):
    print(
        json.dumps(
            value,
            ensure_ascii=True,
            sort_keys=True,
            separators=(",", ":"),
        ),
        file=stream,
    )


def main():
    args = parse_args()
    try:
        result = verify(args)
    except ApprovalError as exc:
        emit({"approved": False, "error": str(exc)}, sys.stderr)
        return 1
    emit(result, sys.stdout)
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

2.上書きしない再現用入力を作る

次のmake_role_demo.pyは、新しい出力ディレクトリにだけデモ入力を作ります。reviewer鍵2本とoperator鍵1本を同じプロセス内で生成しますが、秘密鍵は保存しません。動作確認専用であり、独立した担当者による鍵管理の見本ではありません。

#!/usr/bin/env python3
import argparse
import base64
import hashlib
import json
from pathlib import Path

from cryptography.hazmat.primitives import serialization
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey

POLICY_SCHEMA = "manage-ai-role-policy-v1"
TARGET_SCHEMA = "manage-ai-role-approval-target-v1"
APPROVALS_SCHEMA = "manage-ai-role-approvals-v1"


def canonical_bytes(value):
    return json.dumps(
        value,
        ensure_ascii=False,
        allow_nan=False,
        sort_keys=True,
        separators=(",", ":"),
    ).encode("utf-8")


def pretty_bytes(value):
    return (
        json.dumps(
            value,
            ensure_ascii=False,
            allow_nan=False,
            sort_keys=True,
            indent=2,
        )
        + "\n"
    ).encode("utf-8")


def parse_args():
    parser = argparse.ArgumentParser(
        description="Create disposable inputs for the role approval demo."
    )
    parser.add_argument("--output", required=True, type=Path)
    return parser.parse_args()


def main():
    args = parse_args()
    try:
        args.output.mkdir(mode=0o700)
    except FileExistsError:
        raise SystemExit("output directory already exists")
    except OSError as exc:
        raise SystemExit(
            f"cannot create output directory: {exc}"
        ) from exc

    records = []
    for role in ("reviewer", "reviewer", "operator"):
        private_key = Ed25519PrivateKey.generate()
        raw_public_key = private_key.public_key().public_bytes(
            encoding=serialization.Encoding.Raw,
            format=serialization.PublicFormat.Raw,
        )
        key_id = hashlib.sha256(raw_public_key).hexdigest()
        records.append(
            {
                "role": role,
                "private_key": private_key,
                "entry": {
                    "key_id": key_id,
                    "role": role,
                    "public_key_b64": base64.b64encode(
                        raw_public_key
                    ).decode("ascii"),
                },
            }
        )

    policy = {
        "schema": POLICY_SCHEMA,
        "policy_id": "release-roles-v1",
        "required_roles": ["operator", "reviewer"],
        "keys": sorted(
            (record["entry"] for record in records),
            key=lambda entry: entry["key_id"],
        ),
    }
    policy_sha256 = hashlib.sha256(
        canonical_bytes(policy)
    ).hexdigest()

    subject = {
        "schema": "manage-ai-demo-subject-v1",
        "artifact_id": "demo-artifact",
        "release_id": "2026-11-05.1",
        "release_sequence": 183,
    }
    subject_bytes = pretty_bytes(subject)
    other_subject = dict(subject)
    other_subject["release_id"] = "2026-11-05.2"

    target = {
        "schema": TARGET_SCHEMA,
        "policy_id": policy["policy_id"],
        "policy_sha256": policy_sha256,
        "subject_sha256": hashlib.sha256(subject_bytes).hexdigest(),
    }
    target_bytes = canonical_bytes(target)
    target_sha256 = hashlib.sha256(target_bytes).hexdigest()

    def make_approvals(selected_records):
        signatures = []
        for record in selected_records:
            signature = record["private_key"].sign(target_bytes)
            signatures.append(
                {
                    "key_id": record["entry"]["key_id"],
                    "signature_b64": base64.b64encode(
                        signature
                    ).decode("ascii"),
                }
            )
        return {
            "schema": APPROVALS_SCHEMA,
            "target_sha256": target_sha256,
            "signatures": sorted(
                signatures, key=lambda item: item["key_id"]
            ),
        }

    reviewers = [
        record for record in records if record["role"] == "reviewer"
    ]
    operator = next(
        record for record in records if record["role"] == "operator"
    )

    documents = {
        "policy.json": policy,
        "target.json": target,
        "approvals-ok.json": make_approvals(
            [reviewers[0], operator]
        ),
        "approvals-reviewers-only.json": make_approvals(reviewers),
    }
    for name, document in documents.items():
        (args.output / name).write_bytes(pretty_bytes(document))
    (args.output / "subject.json").write_bytes(subject_bytes)
    (args.output / "subject-other.json").write_bytes(
        pretty_bytes(other_subject)
    )

    print(
        json.dumps(
            {
                "expected_policy_sha256": policy_sha256,
                "output_directory": str(args.output),
            },
            sort_keys=True,
            separators=(",", ":"),
        )
    )
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

3.reviewerとoperatorの承認を確認する

新しい仮想環境で使用バージョンを固定します。role-approval-venvとrole-demoには、実行前に存在しない名前を使ってください。

python3 -m venv role-approval-venv
. role-approval-venv/bin/activate
python -m pip install 'cryptography==50.0.2'
DEMO_INFO=$(python make_role_demo.py --output role-demo)
printf '%s\n' "$DEMO_INFO"
POLICY_SHA256=$(printf '%s\n' "$DEMO_INFO" | python -c 'import json, sys; print(json.load(sys.stdin)["expected_policy_sha256"])')
python verify_role_approval.py --policy role-demo/policy.json --target role-demo/target.json --approvals role-demo/approvals-ok.json --subject role-demo/subject.json --expected-policy-sha256 "$POLICY_SHA256"

鍵は実行時に生成されるため、ポリシーハッシュ、対象ハッシュ、鍵IDは実行ごとに変わります。成功時の1行JSONは次の形式です。山括弧内は実行時の値です。

{"approved":true,"policy_id":"release-roles-v1","policy_sha256":"<64桁の値>","satisfied_roles":["operator","reviewer"],"subject_sha256":"<64桁の値>","target_sha256":"<64桁の値>","valid_key_ids":["<鍵ID>","<鍵ID>"]}

approved=trueは、指定したポリシーと署名対象に対して必要役割の署名を確認し、対象ファイルのSHA-256も一致したという意味です。対象ファイルの業務内容が正しいことまでは判定しません。

4.reviewer鍵が2本あってもoperatorなしなら拒否する

次は、異なるreviewer鍵2本による有効な署名です。

python verify_role_approval.py --policy role-demo/policy.json --target role-demo/target.json --approvals role-demo/approvals-reviewers-only.json --subject role-demo/subject.json --expected-policy-sha256 "$POLICY_SHA256"
echo $?

標準エラー出力と終了コードは次のとおりです。

{"approved":false,"error":"required approval roles are missing: operator"}
1

2本とも有効な署名ですが、満たす役割はreviewerだけです。鍵の本数を役割数へ読み替えず、operatorが不足している時点で停止します。

5.署名後に対象を差し替えると拒否する

デモ生成器は、内容が異なるsubject-other.jsonも作ります。承認文書は元のsubject.jsonへ結び付いているため、次の実行は失敗します。

python verify_role_approval.py --policy role-demo/policy.json --target role-demo/target.json --approvals role-demo/approvals-ok.json --subject role-demo/subject-other.json --expected-policy-sha256 "$POLICY_SHA256"
echo $?
{"approved":false,"error":"subject: SHA-256 does not match signed target"}
1

実運用で別に必要な条件

条件 理由
期待ポリシーハッシュを別経路で配置する ポリシー、署名対象、期待ハッシュを同じ主体がまとめて置換できるなら、攻撃者自身の鍵と役割へ差し替えられる
役割ごとの秘密鍵を独立して管理する 異なる鍵IDだけでは、異なる人や装置による承認を証明できない
ポリシー変更時に新しいIDとハッシュを配布する 鍵の追加、削除、役割変更を既存ポリシーと区別するため
検証した対象を利用時まで固定する このCLIは検証後のファイルを封印せず、起動や配置も行わないため、検証後の差し替えは防げない
対象の業務内容を別途検証する 今回確認するのは対象ファイルのバイト列と承認役割であり、連番、期限、成果物ハッシュ、業務上の妥当性ではない
失効と期限を別に設計する 登録鍵の失効、承認期限、ポリシーの反ロールバックは今回の入力形式に含まれない

デモでは生成器が期待ポリシーハッシュまで表示するため、信頼経路の独立性はありません。実運用では、レビュー済みの設定や読み取り専用の配布経路など、ポリシーJSONとは別の信頼できる場所から期待値を渡します。

まとめ

異なる鍵が2本あることと、異なる職務の承認があることは同じではありません。公開鍵へ一つの役割を割り当て、ポリシーの正規化ハッシュを署名対象へ含めれば、reviewerとoperatorの両方が同じ対象を承認したかを機械的に判定できます。

一方、役割名だけでは担当者の独立性を証明できません。コードによる役割判定に、秘密鍵の保管者、ポリシーの配布経路、失効手順を組み合わせる必要があります。