第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で重複を検出し、非有限数と入力サイズも制限します。
ポリシーと承認対象を結び付ける
- ポリシーJSONをキー順、空白なし、UTF-8で正規化し、SHA-256を計算する。
- その値が、別経路で設定した
--expected-policy-sha256と一致することを確認する。 - 署名対象JSONへポリシーID、ポリシーSHA-256、対象ファイルのSHA-256を記録する。
- 承認者は署名対象JSONの正規化バイト列へ署名する。
- 検証側はすべての掲載署名を検証し、必要な役割が揃ってから対象ファイルを照合する。
正規化は本稿の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の両方が同じ対象を承認したかを機械的に判定できます。
一方、役割名だけでは担当者の独立性を証明できません。コードによる役割判定に、秘密鍵の保管者、ポリシーの配布経路、失効手順を組み合わせる必要があります。