第182回 単独鍵だけで成果物を承認しない:Pythonで検証する2-of-3 Ed25519承認

第179回では一つのEd25519鍵による成果物マニフェストの署名、第180回では受理済み連番による旧版拒否、第181回では現在鍵から新しい鍵へ移るための二重署名を扱いました。

第181回の二つの署名には、現在鍵による遷移承認と、新しい鍵を使用できることの確認という別々の役割がありました。通常のリリース承認で「登録した3鍵のうち、異なる2鍵以上」と判定する仕組みとは異なります。

今回は、許可済みの3本のEd25519公開鍵と閾値2をポリシーに記録し、同じ承認対象に付いた有効な署名を鍵IDごとに一度だけ数えるCLIを作ります。署名が閾値を満たした後で、期待する成果物ID、リリースID、連番、成果物のSHA-256も照合します。

これは複数の独立したEd25519署名をアプリケーション側で数える仕組みです。一つの署名へ集約する暗号学的な閾値署名ではありません。また、異なる鍵IDは異なる人を意味しません。鍵を独立した担当者や装置で管理することは運用側の条件です。

鍵遷移の二重署名と2-of-3承認を分ける

項目 第181回の鍵遷移 今回のリリース承認
目的 現在の信頼鍵から次の信頼鍵へ移る 一つの成果物を複数鍵で承認する
必要な署名 指定した現在鍵と新鍵の両方 ポリシーで許可した3鍵のうち異なる2鍵以上
同じ鍵の反復 役割を満たさない 二重計上せず、本稿の入力形式では重複として拒否する
状態更新 検証済みの次状態候補を作る 信頼状態や受理済み連番を更新しない

The Update Framework仕様1.0.36にも、役割ごとの署名閾値と、同じ鍵IDの署名を閾値へ二度数えない規則があります。本稿が採るのはこの数え方です。期限、委任、ルートメタデータ、スナップショットなどを実装していないため、このCLIをTUF実装とは扱いません。鍵IDもTUF形式ではなく、32バイトの生公開鍵に対するSHA-256として本稿独自に固定します。

判定を行う順番

  1. ポリシーJSONと承認JSONをサイズ上限付きで一度読み、UTF-8、重複キー、非標準数値、必須フィールドを検査する。
  2. 各公開鍵をBase64から戻し、32バイトであることと、再計算した鍵IDが記載値に一致することを確かめる。
  3. signedオブジェクトをキー順、空白なし、ASCIIエスケープ、末尾改行ありのバイト列へ直す。
  4. 許可鍵の署名を検証し、異なる有効鍵だけを数える。許可外鍵と不正署名は数えない。
  5. 有効署名が2件未満なら、成果物をハッシュ化せず終了する。
  6. 署名済みの成果物ID、リリースID、連番をコマンドラインの期待値と照合する。
  7. 成果物を1MiBずつ読み、SHA-256を署名済みの値と照合する。
  8. すべて一致した場合だけstatus=acceptedと終了コード0を返す。

cryptography 50.0.2のEd25519 APIでは、生の公開鍵は32バイト、sign()が返す署名は64バイトです。verify()は成功時に値を返さず、不正な署名ではInvalidSignatureを送出します。

PythonのJSONデコーダは既定では同名キーを最後の値で上書きし、JSON仕様外のNaNなども受理します。そこで、object_pairs_hookとparse_constantを使って明示的に拒否します。

今回の実行契約

項目 仕様
動作環境 Linux、Python 3.10以上、cryptography==50.0.2
信頼の起点 検証環境へ別経路で正しく配置したpolicy.json。このCLIはポリシー自体の署名や更新を扱わない
ポリシー BOMなしUTF-8、65,536バイト以下。1~16鍵と、1以上かつ鍵数以下の閾値を持つ
承認JSON BOMなしUTF-8、262,144バイト以下。署名は0~32件。同じ鍵IDの反復は入力エラー
鍵ID 32バイトのEd25519生公開鍵をSHA-256で処理した64桁の小文字16進数
署名対象 _type、成果物ID、リリースID、連番、SHA-256を持つsignedオブジェクトの正規化バイト列
承認条件 ポリシー内の異なる鍵による有効署名が閾値以上で、期待値と成果物ハッシュも一致する
成果物 開いた先が通常ファイルであること。サイズ上限は設けず、1MiB単位で読む
標準出力 検証結果を1行JSONで出す。受理拒否も判定結果として標準出力へ出す
標準エラー出力 ファイル、JSON、スキーマなどの入力エラーを1行JSONで出す。CLI引数の構文エラーはargparseの通常表示
対象外 署名作業、秘密鍵保管、ポリシー配布、期限、失効、受理状態更新、成果物の起動

2-of-3承認を検証するCLI

空の作業ディレクトリで仮想環境を作り、本稿で使う版を固定します。

python3 -m venv .venv
. .venv/bin/activate
python -m pip install 'cryptography==50.0.2'

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

#!/usr/bin/env python3
import argparse
import base64
import binascii
import hashlib
import json
import os
import re
import stat
import sys

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

POLICY_TYPE = 'manage-ai.release-policy.v1'
SIGNED_TYPE = 'manage-ai.release-approval.v1'
MAX_POLICY_BYTES = 65_536
MAX_APPROVAL_BYTES = 262_144
MAX_KEYS = 16
MAX_SIGNATURES = 32
TOKEN_RE = re.compile(r'[A-Za-z0-9][A-Za-z0-9._-]{0,127}')
SHA256_RE = re.compile(r'[0-9a-f]{64}')


class InputError(Exception):
    pass


def read_regular(path, limit):
    flags = os.O_RDONLY | getattr(os, 'O_CLOEXEC', 0)
    try:
        fd = os.open(path, flags)
    except OSError as exc:
        raise InputError(f'cannot open {path}: {exc.strerror}') from exc
    try:
        before = os.fstat(fd)
        if not stat.S_ISREG(before.st_mode):
            raise InputError(f'not a regular file: {path}')
        chunks = []
        total = 0
        while True:
            try:
                chunk = os.read(fd, min(65_536, limit + 1 - total))
            except OSError as exc:
                raise InputError(f'cannot read {path}: {exc.strerror}') from exc
            if not chunk:
                break
            chunks.append(chunk)
            total += len(chunk)
            if total > limit:
                raise InputError(f'file is larger than {limit} bytes: {path}')
        after = os.fstat(fd)
        if (before.st_size, before.st_mtime_ns) != (
            after.st_size,
            after.st_mtime_ns,
        ):
            raise InputError(f'file changed while it was being read: {path}')
        return b''.join(chunks)
    finally:
        os.close(fd)


def reject_duplicate_keys(pairs):
    result = {}
    for key, value in pairs:
        if key in result:
            raise InputError(f'duplicate JSON key: {key}')
        result[key] = value
    return result


def reject_constant(value):
    raise InputError(f'non-standard JSON number: {value}')


def load_json(path, limit):
    raw = read_regular(path, limit)
    try:
        text = raw.decode('utf-8')
    except UnicodeDecodeError as exc:
        raise InputError(f'not UTF-8: {path}') from exc
    try:
        return json.loads(
            text,
            object_pairs_hook=reject_duplicate_keys,
            parse_constant=reject_constant,
        )
    except json.JSONDecodeError as exc:
        raise InputError(
            f'invalid JSON in {path}: line {exc.lineno}, column {exc.colno}'
        ) from exc
    except RecursionError as exc:
        raise InputError(f'JSON nesting is too deep in {path}') from exc
    except ValueError as exc:
        raise InputError(f'unsupported JSON number in {path}') from exc


def require_exact_keys(value, expected, where):
    if type(value) is not dict:
        raise InputError(f'{where} must be an object')
    actual = set(value)
    if actual != expected:
        missing = sorted(expected - actual)
        extra = sorted(actual - expected)
        raise InputError(
            f'{where} fields differ; missing={missing}, extra={extra}'
        )


def decode_base64(value, where, expected_length):
    if type(value) is not str or not value:
        raise InputError(f'{where} must be a non-empty Base64 string')
    try:
        decoded = base64.b64decode(value, validate=True)
    except (binascii.Error, ValueError) as exc:
        raise InputError(f'invalid Base64 in {where}') from exc
    if len(decoded) != expected_length:
        raise InputError(
            f'{where} must decode to {expected_length} bytes'
        )
    return decoded


def parse_policy(value):
    require_exact_keys(value, {'_type', 'threshold', 'keys'}, 'policy')
    if value['_type'] != POLICY_TYPE:
        raise InputError('unsupported policy _type')
    threshold = value['threshold']
    keys = value['keys']
    if type(threshold) is not int or threshold < 1:
        raise InputError('policy threshold must be a positive integer')
    if type(keys) is not list or not 1 <= len(keys) <= MAX_KEYS:
        raise InputError(f'policy keys must contain 1 to {MAX_KEYS} entries')

    public_keys = {}
    for index, entry in enumerate(keys):
        where = f'policy.keys[{index}]'
        require_exact_keys(entry, {'key_id', 'public_key'}, where)
        key_id = entry['key_id']
        if type(key_id) is not str or not SHA256_RE.fullmatch(key_id):
            raise InputError(
                f'{where}.key_id must be 64 lowercase hexadecimal characters'
            )
        if key_id in public_keys:
            raise InputError(f'duplicate policy key_id: {key_id}')
        raw_key = decode_base64(
            entry['public_key'], f'{where}.public_key', 32
        )
        if key_id != hashlib.sha256(raw_key).hexdigest():
            raise InputError(f'key_id does not match public key at {where}')
        try:
            public_keys[key_id] = Ed25519PublicKey.from_public_bytes(raw_key)
        except (ValueError, UnsupportedAlgorithm) as exc:
            raise InputError(
                f'unusable Ed25519 public key at {where}'
            ) from exc

    if threshold > len(public_keys):
        raise InputError(
            'policy threshold exceeds the number of authorized keys'
        )
    return threshold, public_keys


def parse_approval(value):
    require_exact_keys(value, {'signed', 'signatures'}, 'approval')
    signed = value['signed']
    require_exact_keys(
        signed,
        {
            '_type',
            'artifact_id',
            'release_id',
            'release_sequence',
            'sha256',
        },
        'approval.signed',
    )
    if signed['_type'] != SIGNED_TYPE:
        raise InputError('unsupported signed _type')
    for field in ('artifact_id', 'release_id'):
        item = signed[field]
        if type(item) is not str or not TOKEN_RE.fullmatch(item):
            raise InputError(f'signed {field} has an invalid format')
    sequence = signed['release_sequence']
    if type(sequence) is not int or not 1 <= sequence <= 2**63 - 1:
        raise InputError(
            'signed release_sequence must be an integer from 1 to 2^63-1'
        )
    digest = signed['sha256']
    if type(digest) is not str or not SHA256_RE.fullmatch(digest):
        raise InputError(
            'signed sha256 must be 64 lowercase hexadecimal characters'
        )

    signatures = value['signatures']
    if type(signatures) is not list or len(signatures) > MAX_SIGNATURES:
        raise InputError(
            f'signatures must be a list with at most {MAX_SIGNATURES} entries'
        )
    parsed = []
    seen = set()
    for index, entry in enumerate(signatures):
        where = f'approval.signatures[{index}]'
        require_exact_keys(entry, {'key_id', 'signature'}, where)
        key_id = entry['key_id']
        if type(key_id) is not str or not SHA256_RE.fullmatch(key_id):
            raise InputError(
                f'{where}.key_id must be 64 lowercase hexadecimal characters'
            )
        if key_id in seen:
            raise InputError(f'duplicate signature key_id: {key_id}')
        seen.add(key_id)
        signature = decode_base64(
            entry['signature'], f'{where}.signature', 64
        )
        parsed.append((key_id, signature))
    return signed, parsed


def canonical_signed_bytes(signed):
    return (
        json.dumps(
            signed,
            ensure_ascii=True,
            allow_nan=False,
            sort_keys=True,
            separators=(',', ':'),
        ).encode('ascii')
        + b'\n'
    )


def hash_regular_file(path):
    flags = os.O_RDONLY | getattr(os, 'O_CLOEXEC', 0)
    try:
        fd = os.open(path, flags)
    except OSError as exc:
        raise InputError(f'cannot open {path}: {exc.strerror}') from exc
    try:
        before = os.fstat(fd)
        if not stat.S_ISREG(before.st_mode):
            raise InputError(f'not a regular file: {path}')
        digest = hashlib.sha256()
        while True:
            try:
                chunk = os.read(fd, 1024 * 1024)
            except OSError as exc:
                raise InputError(f'cannot read {path}: {exc.strerror}') from exc
            if not chunk:
                break
            digest.update(chunk)
        after = os.fstat(fd)
        if (before.st_size, before.st_mtime_ns) != (
            after.st_size,
            after.st_mtime_ns,
        ):
            raise InputError('artifact changed while it was being hashed')
        return digest.hexdigest(), after.st_size
    finally:
        os.close(fd)


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


def positive_sequence(value):
    try:
        number = int(value, 10)
    except ValueError as exc:
        raise argparse.ArgumentTypeError('must be an integer') from exc
    if not 1 <= number <= 2**63 - 1:
        raise argparse.ArgumentTypeError('must be from 1 to 2^63-1')
    return number


def build_parser():
    parser = argparse.ArgumentParser()
    parser.add_argument('policy')
    parser.add_argument('approval')
    parser.add_argument('artifact')
    parser.add_argument('--artifact-id', required=True)
    parser.add_argument('--release-id', required=True)
    parser.add_argument(
        '--release-sequence',
        required=True,
        type=positive_sequence,
    )
    return parser


def main(argv=None):
    args = build_parser().parse_args(argv)
    try:
        if not TOKEN_RE.fullmatch(args.artifact_id):
            raise InputError('--artifact-id has an invalid format')
        if not TOKEN_RE.fullmatch(args.release_id):
            raise InputError('--release-id has an invalid format')

        threshold, public_keys = parse_policy(
            load_json(args.policy, MAX_POLICY_BYTES)
        )
        signed, signatures = parse_approval(
            load_json(args.approval, MAX_APPROVAL_BYTES)
        )
        message = canonical_signed_bytes(signed)

        valid = []
        invalid = []
        ignored = []
        for key_id, signature in signatures:
            public_key = public_keys.get(key_id)
            if public_key is None:
                ignored.append(key_id)
                continue
            try:
                public_key.verify(signature, message)
            except InvalidSignature:
                invalid.append(key_id)
            else:
                valid.append(key_id)

        signature_report = {
            'ignored_key_ids': sorted(ignored),
            'invalid_key_ids': sorted(invalid),
            'threshold': threshold,
            'valid_key_ids': sorted(valid),
            'valid_signatures': len(valid),
        }
        if len(valid) < threshold:
            emit(
                sys.stdout,
                {
                    'status': 'rejected',
                    'reason': 'threshold_not_met',
                    **signature_report,
                },
            )
            return 3

        mismatches = []
        expected = (
            ('artifact_id', args.artifact_id),
            ('release_id', args.release_id),
            ('release_sequence', args.release_sequence),
        )
        for field, value in expected:
            if signed[field] != value:
                mismatches.append(field)
        if mismatches:
            emit(
                sys.stdout,
                {
                    'status': 'rejected',
                    'reason': 'expected_approval_mismatch',
                    'fields': mismatches,
                    **signature_report,
                },
            )
            return 4

        artifact_sha256, artifact_size = hash_regular_file(args.artifact)
        if artifact_sha256 != signed['sha256']:
            emit(
                sys.stdout,
                {
                    'status': 'rejected',
                    'reason': 'artifact_sha256_mismatch',
                    'actual_sha256': artifact_sha256,
                    'signed_sha256': signed['sha256'],
                    **signature_report,
                },
            )
            return 4

        emit(
            sys.stdout,
            {
                'status': 'accepted',
                'artifact_id': signed['artifact_id'],
                'artifact_sha256': artifact_sha256,
                'artifact_size': artifact_size,
                'release_id': signed['release_id'],
                'release_sequence': signed['release_sequence'],
                **signature_report,
            },
        )
        return 0
    except InputError as exc:
        emit(
            sys.stderr,
            {
                'status': 'error',
                'reason': 'input_error',
                'detail': str(exc),
            },
        )
        return 2


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

上書きしない動作確認データを作る

次の補助スクリプトは、実行前に存在しないディレクトリだけを作り、3本のテスト鍵、2-of-3ポリシー、正常・不足・破損・重複の承認JSON、正常・改変済みの成果物を生成します。秘密鍵はファイルへ保存しません。

ただし、3本の秘密鍵を同じプロセス内で生成して署名するため、担当者や保管場所の独立性は再現していません。これは検証ロジックだけを確認するデモです。本番鍵として使わないでください。

次をmake_quorum_demo.pyとして、verify_quorum.pyと同じディレクトリへ保存します。

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

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

from verify_quorum import POLICY_TYPE, SIGNED_TYPE, canonical_signed_bytes


def write_json(path, value):
    with path.open('x', encoding='utf-8', newline='\n') as handle:
        json.dump(
            value,
            handle,
            ensure_ascii=True,
            allow_nan=False,
            sort_keys=True,
            indent=2,
        )
        handle.write('\n')


def main():
    if len(sys.argv) != 2:
        print('usage: python make_quorum_demo.py NEW_DIRECTORY', file=sys.stderr)
        return 2

    root = Path(sys.argv[1])
    artifact = b'demo artifact for quorum verification\n'

    try:
        private_keys = [Ed25519PrivateKey.generate() for _ in range(3)]
        policy_keys = []
        key_ids = []
        for private_key in private_keys:
            raw_public = private_key.public_key().public_bytes(
                encoding=serialization.Encoding.Raw,
                format=serialization.PublicFormat.Raw,
            )
            key_id = hashlib.sha256(raw_public).hexdigest()
            key_ids.append(key_id)
            policy_keys.append(
                {
                    'key_id': key_id,
                    'public_key': base64.b64encode(raw_public).decode('ascii'),
                }
            )

        policy = {
            '_type': POLICY_TYPE,
            'threshold': 2,
            'keys': policy_keys,
        }
        signed = {
            '_type': SIGNED_TYPE,
            'artifact_id': 'invoice-classifier',
            'release_id': '2026-11-03.1',
            'release_sequence': 12,
            'sha256': hashlib.sha256(artifact).hexdigest(),
        }
        message = canonical_signed_bytes(signed)
        signatures = []
        for key_id, private_key in zip(key_ids, private_keys):
            signature = private_key.sign(message)
            signatures.append(
                {
                    'key_id': key_id,
                    'signature': base64.b64encode(signature).decode('ascii'),
                }
            )

        broken = bytearray(
            base64.b64decode(signatures[1]['signature'], validate=True)
        )
        broken[0] ^= 1
        invalid_signature = {
            'key_id': signatures[1]['key_id'],
            'signature': base64.b64encode(broken).decode('ascii'),
        }

        documents = {
            'policy.json': policy,
            'approval-two.json': {
                'signed': signed,
                'signatures': signatures[:2],
            },
            'approval-one.json': {
                'signed': signed,
                'signatures': signatures[:1],
            },
            'approval-invalid.json': {
                'signed': signed,
                'signatures': [signatures[0], invalid_signature],
            },
            'approval-duplicate.json': {
                'signed': signed,
                'signatures': [signatures[0], signatures[0]],
            },
        }

        root.mkdir(mode=0o700)
        with (root / 'artifact.bin').open('xb') as handle:
            handle.write(artifact)
        with (root / 'artifact-tampered.bin').open('xb') as handle:
            handle.write(artifact + b'changed\n')
        for name, document in documents.items():
            write_json(root / name, document)
    except OSError as exc:
        print(
            json.dumps(
                {
                    'status': 'error',
                    'reason': 'cannot_create_demo',
                    'detail': str(exc),
                },
                sort_keys=True,
                separators=(',', ':'),
            ),
            file=sys.stderr,
        )
        return 2

    print(
        json.dumps(
            {
                'status': 'created',
                'directory': str(root),
                'key_ids': key_ids,
            },
            sort_keys=True,
            separators=(',', ':'),
        )
    )
    return 0


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

2件の有効署名を確認する

まず、新しいdemo-quorumディレクトリを作ります。同名のディレクトリがあれば作成に失敗し、既存内容は上書きしません。

python make_quorum_demo.py demo-quorum

正常な承認JSONと成果物を検証します。

python verify_quorum.py demo-quorum/policy.json demo-quorum/approval-two.json demo-quorum/artifact.bin --artifact-id invoice-classifier --release-id 2026-11-03.1 --release-sequence 12
echo $?

成功時は、標準出力の1行JSONでstatusがaccepted、thresholdとvalid_signaturesがともに2となり、終了コードは0です。valid_key_idsは毎回生成するテスト鍵によって変わります。

不足、破損、重複、成果物改変を確認する

同じコマンドの承認ファイルまたは成果物だけを次の表のように替えます。

入力 結果 終了コード
approval-one.jsonとartifact.bin threshold_not_met。有効署名は1件 3
approval-invalid.jsonとartifact.bin 1件は有効、1件はinvalid_key_idsへ入り、閾値未達 3
approval-duplicate.jsonとartifact.bin 同じ鍵IDを二度記載しているため入力エラー。標準エラー出力へJSONを出す 2
approval-two.jsonとartifact-tampered.bin 署名は2件とも有効だが、成果物のSHA-256が不一致 4
approval-two.jsonで--release-id 2026-11-03.2 署名済みリリースIDが実行時の期待値と不一致 4

許可外の鍵IDはignored_key_ids、許可鍵だが検証できない署名はinvalid_key_idsへ出し、どちらも承認数へ入れません。二つの有効署名が別にあれば、追加の許可外署名や不正署名があっても閾値判定自体は成功します。余分な署名を一つでも許さない運用にする場合は、両リストが空でなければ拒否する条件を追加してください。

2-of-3でも残る制約

  • ポリシーの置換は防げません。 攻撃者がpolicy.jsonを自分の公開鍵へ差し替えられるなら、2-of-3判定も作り直せます。所有者、権限、配置元、期待ハッシュを別の信頼経路で管理します。
  • 異なる鍵は異なる承認者を証明しません。 一人が2本を保持していれば、一人で閾値を満たせます。鍵の管理者と保管装置を分け、その対応を鍵IDで記録する必要があります。
  • 署名対象のバイト列は完全一致が必要です。 署名環境でもcanonical_signed_bytes()と同じ規則を使います。見た目が同じJSONでも、署名対象のバイト列が違えば検証できません。
  • 旧版の再提示は別問題です。 このCLIは渡された--release-sequenceとの一致だけを見ます。最後に受理した連番を永続化して旧版を拒む処理は、第180回のような反ロールバック状態で行います。
  • 検証後の変更は固定しません。 読み取り中のサイズと更新時刻は比較しますが、検証終了後の変更を禁止しません。起動まで同じバイト列を保つ必要がある場合は、第178回のように封印済みのファイル記述子へつなぎます。
  • 失効、期限、委任はありません。 鍵をポリシーから安全に外す更新手順や、期限切れ承認の拒否は別途設計が必要です。ポリシーを単に編集するだけでは、誰が変更を承認したか確認できません。

本番へ持ち込む前の最小確認

  1. 3本の秘密鍵を検証環境へ置かず、互いに独立した管理主体または装置へ割り当てる。
  2. 公開鍵から再計算した鍵ID、管理者、用途を対応付け、保護した経路でポリシーを配置する。
  3. 各署名者が同じ正規化バイト列を確認して署名し、signedを変更せず署名エントリだけを集約する。
  4. 期待する成果物ID、リリースID、次の連番を明示してCLIを実行し、終了コード0とstatus=acceptedの両方を確認する。
  5. 受理済み連番の更新や成果物の起動は、この検証結果を入力とする別工程で行う。

2-of-3にする意味は、署名文字列を二つ並べることではありません。信頼済みポリシーに載った異なる鍵が、同じ対象バイト列へ有効な署名を行い、その数が閾値へ達したことを検証して初めて承認条件になります。