第180回 署名済みの旧版へ戻さない:Pythonで作るリリース連番の反ロールバック検証

第179回では、成果物のSHA-256を記録したマニフェストへEd25519で署名し、実行環境で署名と成果物を検証しました。

ただし、有効な署名があっても、それが最新のリリースとは限りません。以前は正規だったマニフェスト、署名、成果物をまとめて再提示されると、署名検証とハッシュ照合には成功します。

今回は署名対象へ単調に増えるrelease_sequenceを追加し、実行環境が最後に受理した連番とマニフェストのSHA-256を保存します。過去の連番、同じ連番を使った別マニフェスト、連番の飛び越しを拒否する小さなゲートを作ります。

この実装は成果物を起動しません。署名、成果物、受理順を検証し、受理状態を更新するところまでを担当します。

署名だけでは旧版を判定できない

候補 判定 理由
署名が無効 拒否 承認鍵による署名を確認できない
連番が受理済み連番より小さい 拒否 旧版への巻き戻し
連番が同じで、マニフェストのSHA-256も同じ already_accepted 同じ候補の再確認
連番が同じで、マニフェストのSHA-256が異なる 拒否 一つの連番に異なる内容が割り当てられている
連番が受理済み連番の次 受理 署名と成果物の検証後に状態を更新する
連番が2以上進んでいる 拒否 途中のリリースを確認していない

The Update Framework仕様でも、新しいメタデータのバージョンを信頼済みメタデータと比較し、信頼済み状態を永続化します。ただし、本稿は鍵のローテーション、期限、複数署名、リポジトリメタデータなどを備えたTUFの実装ではありません。

今回の実行契約

項目 仕様
動作環境 Linux、Python 3.11以上、OpenSSL 3系、第179回と同じcryptography 50.0.2
マニフェスト 末尾改行を含む4096バイト以下の正規化ASCII JSON
署名 マニフェストの全バイトに対する64バイトのEd25519署名
成果物 署名済みのサイズとSHA-256が一致する通常ファイル
受理状態 実行アカウントが所有するモード0700の専用ディレクトリへ保存する
連番 1から開始し、リリースごとに1だけ増やす
初回 状態が未作成の場合だけ、運用側で確認した連番を--bootstrap-sequenceへ明示する
同時実行 fcntl.flock()で状態の読み取りと更新を直列化する
状態更新 同じディレクトリの一時ファイルを同期後、os.replace()で置き換える
運用上の前提 状態ディレクトリとその親を、配布物を書き込むアカウントから変更できないようにする。この条件はコードでは確認しない
対象外 成果物の起動、インストール、最新版の探索、期限判定、状態ファイル自体の巻き戻し対策

今回は連番を必ず1ずつ進めます。途中の版を省略して最新版だけを受理したい配布方式には、そのまま適用できません。

1.連番を含むマニフェストを作る

動作確認用の成果物とマニフェストを作ります。秘密鍵を生成するコマンドは隔離したテスト用ディレクトリだけで実行してください。本番の秘密鍵は承認環境に置き、検証環境へコピーしません。

umask 077
printf 'release 1\n' > report-cli.bin
python3 - <<'PY'
import hashlib
import json
from pathlib import Path

artifact = Path('report-cli.bin').read_bytes()
manifest = {
    'schema_version': 1,
    'artifact_id': 'report-cli',
    'release_sequence': 1,
    'release_id': '2026-10-30.1',
    'sha256': hashlib.sha256(artifact).hexdigest(),
    'size': len(artifact),
}
data = json.dumps(
    manifest,
    ensure_ascii=True,
    sort_keys=True,
    separators=(',', ':'),
    allow_nan=False,
).encode('ascii') + b'\n'
Path('release-1.manifest.json').write_bytes(data)
PY
openssl genpkey -algorithm ED25519 -out test-private.pem
openssl pkey -in test-private.pem -pubout -out test-public.pem
openssl pkeyutl -sign -rawin -inkey test-private.pem -in release-1.manifest.json -out release-1.manifest.sig

生成されるマニフェストは次の1行です。キー順、空白、末尾改行も署名対象なので、署名後に整形し直してはいけません。

{"artifact_id":"report-cli","release_id":"2026-10-30.1","release_sequence":1,"schema_version":1,"sha256":"a99bfb6fcb5c1d11e839cf728730924be5e6755121a66270aa7701e0dd9ffbf2","size":10}

OpenSSL 3系でEd25519を署名する場合、pkeyutlの-rawinを指定し、ダイジェスト名は指定しません。検証側では、Ed25519PublicKey.verify()が不一致時にInvalidSignatureを送出します。

2.署名、成果物、受理順をまとめて検証する

次のコードをanti_rollback_gate.pyとして保存します。

#!/usr/bin/env python3
import argparse
import fcntl
import hashlib
import json
import os
import re
import stat
import sys
import tempfile
from pathlib import Path

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

INVALID, POLICY, OPERATIONAL = 3, 4, 5
MANIFEST_KEYS = {
    "schema_version", "artifact_id", "release_sequence",
    "release_id", "sha256", "size",
}
STATE_KEYS = {
    "schema_version", "artifact_id",
    "highest_sequence", "manifest_sha256",
}
ID_RE = re.compile(r"[a-z0-9][a-z0-9._-]{0,63}")
RELEASE_RE = re.compile(r"[A-Za-z0-9][A-Za-z0-9._-]{0,63}")
HASH_RE = re.compile(r"[0-9a-f]{64}")


class GateError(Exception):
    def __init__(self, reason, code=INVALID, **details):
        super().__init__(reason)
        self.reason = reason
        self.code = code
        self.details = details


def fail(reason, code=INVALID, **details):
    raise GateError(reason, code, **details)


def encode_json(value):
    return (
        json.dumps(
            value,
            ensure_ascii=True,
            sort_keys=True,
            separators=(",", ":"),
            allow_nan=False,
        ).encode("ascii")
        + b"\n"
    )


def parse_json(data, label, code=INVALID):
    def pairs_hook(pairs):
        result = {}
        for key, value in pairs:
            if key in result:
                fail(f"{label}_duplicate_key", code)
            result[key] = value
        return result

    try:
        text = data.decode("ascii")
        value = json.loads(
            text,
            object_pairs_hook=pairs_hook,
            parse_constant=lambda _value: fail(
                f"{label}_non_finite", code
            ),
        )
        if not isinstance(value, dict) or encode_json(value) != data:
            fail(f"{label}_not_canonical", code)
    except (UnicodeDecodeError, ValueError, RecursionError):
        fail(f"{label}_invalid_json", code)
    return value


def read_small(path, maximum, label, code=INVALID, private=False):
    flags = os.O_RDONLY | os.O_CLOEXEC | os.O_NOFOLLOW
    fd = os.open(path, flags)
    try:
        info = os.fstat(fd)
        if not stat.S_ISREG(info.st_mode):
            fail(f"{label}_not_regular", code)
        if private and (
            info.st_uid != os.geteuid()
            or stat.S_IMODE(info.st_mode) & 0o077
            or info.st_nlink != 1
        ):
            fail(f"{label}_not_private", code)

        data = bytearray()
        while len(data) <= maximum:
            chunk = os.read(
                fd, min(65536, maximum + 1 - len(data))
            )
            if not chunk:
                break
            data.extend(chunk)
        if len(data) > maximum:
            fail(f"{label}_too_large", code)
        return bytes(data)
    finally:
        os.close(fd)


def validate_manifest(data):
    value = parse_json(data, "manifest")
    if set(value) != MANIFEST_KEYS:
        fail("manifest_schema_invalid")
    if (
        value["schema_version"] != 1
        or type(value["schema_version"]) is not int
    ):
        fail("manifest_schema_invalid")
    if (
        not isinstance(value["artifact_id"], str)
        or not ID_RE.fullmatch(value["artifact_id"])
    ):
        fail("artifact_id_invalid")

    sequence = value["release_sequence"]
    if type(sequence) is not int or not 1 <= sequence <= 2**63 - 1:
        fail("release_sequence_invalid")
    if (
        not isinstance(value["release_id"], str)
        or not RELEASE_RE.fullmatch(value["release_id"])
    ):
        fail("release_id_invalid")
    if (
        not isinstance(value["sha256"], str)
        or not HASH_RE.fullmatch(value["sha256"])
    ):
        fail("artifact_sha256_invalid")
    if (
        type(value["size"]) is not int
        or not 0 <= value["size"] <= 2**63 - 1
    ):
        fail("artifact_size_invalid")
    return value


def validate_state(data):
    value = parse_json(data, "state", OPERATIONAL)
    if set(value) != STATE_KEYS:
        fail("state_schema_invalid", OPERATIONAL)
    if (
        value["schema_version"] != 1
        or type(value["schema_version"]) is not int
    ):
        fail("state_schema_invalid", OPERATIONAL)
    if (
        not isinstance(value["artifact_id"], str)
        or not ID_RE.fullmatch(value["artifact_id"])
    ):
        fail("state_artifact_id_invalid", OPERATIONAL)

    sequence = value["highest_sequence"]
    if type(sequence) is not int or not 1 <= sequence <= 2**63 - 1:
        fail("state_sequence_invalid", OPERATIONAL)
    if (
        not isinstance(value["manifest_sha256"], str)
        or not HASH_RE.fullmatch(value["manifest_sha256"])
    ):
        fail("state_hash_invalid", OPERATIONAL)
    return value


def verify_signature(public_data, signature, manifest_data):
    if len(signature) != 64:
        fail("signature_length_invalid")
    try:
        public_key = load_pem_public_key(public_data)
    except (ValueError, TypeError, UnsupportedAlgorithm):
        fail("public_key_invalid")
    if not isinstance(public_key, Ed25519PublicKey):
        fail("public_key_not_ed25519")
    try:
        public_key.verify(signature, manifest_data)
    except InvalidSignature:
        fail("signature_invalid")


def hash_artifact(path, expected_size):
    flags = os.O_RDONLY | os.O_CLOEXEC | os.O_NOFOLLOW
    fd = os.open(path, flags)
    try:
        before = os.fstat(fd)
        if (
            not stat.S_ISREG(before.st_mode)
            or before.st_size != expected_size
        ):
            fail("artifact_size_or_type_invalid")

        digest = hashlib.sha256()
        total = 0
        while True:
            chunk = os.read(fd, 1024 * 1024)
            if not chunk:
                break
            digest.update(chunk)
            total += len(chunk)

        after = os.fstat(fd)
        watched = (
            "st_dev", "st_ino", "st_size",
            "st_mtime_ns", "st_ctime_ns",
        )
        if total != expected_size or any(
            getattr(before, name) != getattr(after, name)
            for name in watched
        ):
            fail("artifact_changed_while_reading")
        return digest.hexdigest()
    finally:
        os.close(fd)


def open_state_dir(path):
    resolved = path.resolve(strict=True)
    info = resolved.stat()
    if (
        not stat.S_ISDIR(info.st_mode)
        or info.st_uid != os.geteuid()
        or stat.S_IMODE(info.st_mode) != 0o700
    ):
        fail("state_directory_not_private", OPERATIONAL)
    return resolved


def load_state(state_path):
    try:
        data = read_small(
            state_path,
            4096,
            "state",
            OPERATIONAL,
            private=True,
        )
    except FileNotFoundError:
        return None
    return validate_state(data)


def replace_state(state_dir, value):
    fd, temp_name = tempfile.mkstemp(
        prefix=".accepted-state.",
        dir=state_dir,
    )
    try:
        os.fchmod(fd, 0o600)
        with os.fdopen(fd, "wb") as stream:
            fd = -1
            stream.write(encode_json(value))
            stream.flush()
            os.fsync(stream.fileno())

        os.replace(
            temp_name,
            state_dir / "accepted-state.json",
        )
        temp_name = None

        dir_fd = os.open(
            state_dir,
            os.O_RDONLY | os.O_DIRECTORY | os.O_CLOEXEC,
        )
        try:
            os.fsync(dir_fd)
        finally:
            os.close(dir_fd)
    finally:
        if fd >= 0:
            os.close(fd)
        if temp_name is not None:
            try:
                os.unlink(temp_name)
            except FileNotFoundError:
                pass


def update_state(state_dir, manifest, manifest_hash, bootstrap):
    state_path = state_dir / "accepted-state.json"
    sequence = manifest["release_sequence"]
    state = load_state(state_path)

    if state is None:
        if bootstrap is None:
            fail("state_missing_bootstrap_required", POLICY)
        if bootstrap != sequence:
            fail("bootstrap_sequence_mismatch", POLICY)
    else:
        if bootstrap is not None:
            fail("bootstrap_not_allowed_with_existing_state", POLICY)
        if state["artifact_id"] != manifest["artifact_id"]:
            fail("state_artifact_id_mismatch", OPERATIONAL)

        highest = state["highest_sequence"]
        if sequence < highest:
            fail(
                "rollback_detected",
                POLICY,
                candidate_sequence=sequence,
                highest_sequence=highest,
            )
        if sequence == highest:
            if state["manifest_sha256"] == manifest_hash:
                return "already_accepted"
            fail(
                "release_sequence_conflict",
                POLICY,
                candidate_sequence=sequence,
            )
        if sequence != highest + 1:
            fail(
                "release_sequence_gap",
                POLICY,
                candidate_sequence=sequence,
                expected_sequence=highest + 1,
            )

    replace_state(
        state_dir,
        {
            "schema_version": 1,
            "artifact_id": manifest["artifact_id"],
            "highest_sequence": sequence,
            "manifest_sha256": manifest_hash,
        },
    )
    return "accepted"


def sequence_arg(text):
    try:
        value = int(text, 10)
    except ValueError as exc:
        raise argparse.ArgumentTypeError(
            "integer required"
        ) from exc
    if not 1 <= value <= 2**63 - 1:
        raise argparse.ArgumentTypeError("out of range")
    return value


def emit(value, stream):
    print(
        encode_json(value).decode("ascii"),
        end="",
        file=stream,
    )


def run(args):
    manifest_data = read_small(
        args.manifest, 4096, "manifest"
    )
    signature = read_small(
        args.signature, 64, "signature"
    )
    public_data = read_small(
        args.public_key, 8192, "public_key"
    )

    verify_signature(public_data, signature, manifest_data)
    manifest = validate_manifest(manifest_data)
    if manifest["artifact_id"] != args.expected_artifact_id:
        fail("unexpected_artifact_id")

    artifact_hash = hash_artifact(
        args.artifact, manifest["size"]
    )
    if artifact_hash != manifest["sha256"]:
        fail("artifact_sha256_mismatch")
    manifest_hash = hashlib.sha256(manifest_data).hexdigest()

    state_dir = open_state_dir(args.state_dir)
    lock_fd = os.open(
        state_dir / "accepted-state.lock",
        os.O_RDWR | os.O_CREAT | os.O_CLOEXEC | os.O_NOFOLLOW,
        0o600,
    )
    try:
        lock_info = os.fstat(lock_fd)
        if (
            not stat.S_ISREG(lock_info.st_mode)
            or lock_info.st_uid != os.geteuid()
            or stat.S_IMODE(lock_info.st_mode) & 0o077
            or lock_info.st_nlink != 1
        ):
            fail("lock_not_private", OPERATIONAL)
        os.fchmod(lock_fd, 0o600)

        fcntl.flock(lock_fd, fcntl.LOCK_EX)
        status = update_state(
            state_dir,
            manifest,
            manifest_hash,
            args.bootstrap_sequence,
        )
    finally:
        os.close(lock_fd)

    emit(
        {
            "artifact_id": manifest["artifact_id"],
            "release_id": manifest["release_id"],
            "release_sequence": manifest["release_sequence"],
            "status": status,
        },
        sys.stdout,
    )
    return 0


def main():
    parser = argparse.ArgumentParser()
    parser.add_argument("--manifest", required=True, type=Path)
    parser.add_argument("--signature", required=True, type=Path)
    parser.add_argument("--public-key", required=True, type=Path)
    parser.add_argument("--artifact", required=True, type=Path)
    parser.add_argument("--expected-artifact-id", required=True)
    parser.add_argument("--state-dir", required=True, type=Path)
    parser.add_argument(
        "--bootstrap-sequence",
        type=sequence_arg,
    )
    args = parser.parse_args()

    try:
        return run(args)
    except GateError as exc:
        output = {
            "status": "rejected",
            "reason": exc.reason,
        }
        output.update(exc.details)
        emit(output, sys.stderr)
        return exc.code
    except (OSError, RuntimeError, ValueError) as exc:
        emit(
            {
                "status": "error",
                "reason": "operational_error",
                "error_type": type(exc).__name__,
            },
            sys.stderr,
        )
        return OPERATIONAL
    except KeyboardInterrupt:
        emit(
            {"status": "error", "reason": "interrupted"},
            sys.stderr,
        )
        return 130


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

3.最初の連番を明示して受理する

受理状態を置くディレクトリは、実行アカウントが所有するモード0700で作ります。初回だけ、別の信頼できる配布情報と照合した連番を--bootstrap-sequenceへ指定します。

次の配置は動作確認用です。本番では、成果物の配置担当が状態ディレクトリやその親を書き換えられないよう、アカウントと配置場所を分けます。

install -d -m 700 state
python3 anti_rollback_gate.py --manifest release-1.manifest.json --signature release-1.manifest.sig --public-key test-public.pem --artifact report-cli.bin --expected-artifact-id report-cli --state-dir state --bootstrap-sequence 1

署名、形式、成果物、初回連番を確認できると、標準出力へ次の1行を出し、終了コード0になります。

{"artifact_id":"report-cli","release_id":"2026-10-30.1","release_sequence":1,"status":"accepted"}

同じ候補を再確認するときは、初回専用の--bootstrap-sequenceを外します。

python3 anti_rollback_gate.py --manifest release-1.manifest.json --signature release-1.manifest.sig --public-key test-public.pem --artifact report-cli.bin --expected-artifact-id report-cli --state-dir state

状態ファイルを書き換えず、終了コード0でalready_acceptedを返します。

{"artifact_id":"report-cli","release_id":"2026-10-30.1","release_sequence":1,"status":"already_accepted"}

already_acceptedは、成果物を再インストールしてよいという意味ではありません。後続処理はstatusを読み、初回受理と再確認を区別します。インストールを後段に置く場合は、受理状態とは別に後段処理の進捗を記録し、出力の受け取り失敗やインストール失敗から再開できるようにします。

初期状態が消えたときに候補の連番を自動で--bootstrap-sequenceへ渡してはいけません。それでは状態を削除して旧版から初期化できてしまいます。状態がない場合は通常運用を停止し、期待する連番を別の記録から確認します。

4.次の版を受理してから旧版を拒否する

連番2の動作確認用成果物を作り、同じ承認鍵でマニフェストへ署名します。

printf 'release 2\n' > report-cli-v2.bin
python3 - <<'PY'
import hashlib
import json
from pathlib import Path

artifact = Path('report-cli-v2.bin').read_bytes()
manifest = {
    'schema_version': 1,
    'artifact_id': 'report-cli',
    'release_sequence': 2,
    'release_id': '2026-10-30.2',
    'sha256': hashlib.sha256(artifact).hexdigest(),
    'size': len(artifact),
}
data = json.dumps(
    manifest,
    ensure_ascii=True,
    sort_keys=True,
    separators=(',', ':'),
    allow_nan=False,
).encode('ascii') + b'\n'
Path('release-2.manifest.json').write_bytes(data)
PY
openssl pkeyutl -sign -rawin -inkey test-private.pem -in release-2.manifest.json -out release-2.manifest.sig
python3 anti_rollback_gate.py --manifest release-2.manifest.json --signature release-2.manifest.sig --public-key test-public.pem --artifact report-cli-v2.bin --expected-artifact-id report-cli --state-dir state

連番2の受理後に、連番1を--bootstrap-sequenceなしで再確認すると、署名と成果物のハッシュが正しくても標準エラー出力へ次のJSONを出し、終了コード4になります。

python3 anti_rollback_gate.py --manifest release-1.manifest.json --signature release-1.manifest.sig --public-key test-public.pem --artifact report-cli.bin --expected-artifact-id report-cli --state-dir state
{"candidate_sequence":1,"highest_sequence":2,"reason":"rollback_detected","status":"rejected"}

拒否時には受理状態を更新しません。同じ連番2へ異なるマニフェストを割り当てた場合はrelease_sequence_conflict、連番2を受理する前に連番3を渡した場合はrelease_sequence_gapになります。状態作成後に--bootstrap-sequenceを再指定した場合も拒否します。

状態を途中の内容にしない更新順

  1. マニフェストの署名と形式を検証する
  2. 開いた成果物のサイズとSHA-256を検証する
  3. 固定名のロックファイルへ排他ロックを取る
  4. ロック取得後に受理状態を読み直して連番を判定する
  5. 新しい状態を同じディレクトリの一時ファイルへ書き、fsync()する
  6. os.replace()で状態ファイルを置き換え、ディレクトリもfsync()する

os.replace()は、同じファイルシステム上で成功した場合に原子的な置換になります。ただし、ファイルをfsync()しただけではディレクトリエントリの永続化までは保証されないため、Linuxのfsync(2)に従ってディレクトリも同期します。

fcntl.flock()は協調するプロセス間の排他制御です。ロックを無視して状態ファイルを直接書き換える権限まで取り上げるものではありません。

終了コードと出力

終了コード 意味
0 acceptedまたはalready_accepted
2 argparseによる引数エラー。出力はJSONではない
3 署名、マニフェスト、成果物などの検証失敗
4 初回連番不足、不正な初期化指定、巻き戻し、連番衝突、飛び番
5 状態ディレクトリ、状態ファイル、入出力などの運用エラー
130 キーボード割り込み

この実装で残る制約

  • 状態ファイル自体の巻き戻しは防げません。古いディスクスナップショットへ戻したり、同じ実行アカウントや管理者権限で状態を書き換えたりすれば、過去の連番を再び受理できます。強い攻撃者を対象にする場合は、端末外の監査記録やハードウェアで保護された単調カウンターなど、状態を同時に戻せない仕組みが別に必要です。
  • 公開鍵の置換を防ぐ仕組みではありません。公開鍵は検証プロセスから書き換えられない場所へ配置し、変更手順を別に管理します。
  • 現行版の反復提示は検出しません。同じマニフェストはalready_acceptedになります。新しい版の存在を隠し続けるフリーズを検出するには、信頼できる期限や最新版情報が必要です。
  • 受理状態の更新と後段処理は一つのトランザクションではありません。状態更新後に出力の受け取りやインストールが失敗すると、再実行はalready_acceptedになります。後段処理には別の進捗記録が必要です。
  • 置換後のエラーでは状態が更新済みの場合があります。os.replace()の後にディレクトリのfsync()が失敗した場合、終了コードは5でも、現在のファイルシステム上では新しい状態が見えることがあります。再実行時は出力だけでなく保存済み状態も確認します。
  • 検証後の成果物を固定しません。コードは開いたファイル記述子をハッシュ化しますが、終了後に元ファイルを変更できます。起動まで同じバイト列を使う場合は、第178回の封印済みmemfdなどと組み合わせます。
  • 署名鍵の漏えいには対処しません。攻撃者が承認鍵を使える場合、次の連番を持つ別の成果物へ正規の署名を作れます。
  • 排他ロックはローカルファイルシステムを前提にします。NFSやSMBではロックと永続化の意味が異なるため、この実装の対象外です。

導入時に固定する項目

  1. artifact_idごとに専用の状態ディレクトリを用意する
  2. 連番の発行担当を決め、一度使った連番を再利用しない
  3. 初回連番を署名済みマニフェストとは別の導入記録でも確認する
  4. 公開鍵、受理状態、その親ディレクトリを、配布物を書き込むアカウントから変更できないようにする
  5. 旧版、同一連番の別内容、飛び番、壊れた状態ファイル、不正な再初期化を検証環境で試す

署名が示すのは「誰の鍵で承認されたバイト列か」です。今回の受理状態が示すのは「この端末が以前に受理した版より古くないか」です。二つを分けて検証することで、署名済みの旧版をそのまま再利用する巻き戻しを停止できます。