第181回 検証鍵を段階的に替える:Pythonで確認するEd25519の二重署名遷移

第179回ではEd25519署名付きマニフェストを検証し、第180回ではリリース連番によって旧版を拒否しました。どちらも、検証側が正しい公開鍵を保持していることが前提です。

公開鍵を単に新しいファイルへ差し替えるだけでは、現在の信頼鍵が新しい鍵への遷移を承認したか確認できません。今回は、現在の秘密鍵と新しい秘密鍵で同じ遷移文書へ署名し、鍵世代を一つずつ進める検証CLIを作ります。

現在の鍵による署名は、現在の秘密鍵を使える主体が遷移を承認したことを示します。新しい鍵による署名は、新しい秘密鍵を使用できることを確認します。

ただし、旧秘密鍵が漏えいした後では、攻撃者が自分の新鍵を作り、旧鍵と新鍵の両方で署名できます。二重署名は、漏えいした鍵から自動的に信頼を回復する仕組みではありません。

掲載するCLIは現在の信頼状態を更新しません。検証済みの次状態を標準出力へ生成するところで止めます。配置前に内容を確認でき、失敗しても現在の状態は変わりません。

鍵の遷移で確認するもの

確認項目 確認できること 確認できないこと
現在の鍵による署名 現在の秘密鍵を使える主体が遷移へ署名したこと 旧秘密鍵が漏えいしていないこと
新しい鍵による署名 遷移作成時に新しい秘密鍵を使用できたこと 別の担当者による承認や安全な鍵保管
from_epochとto_epoch 鍵世代を一つずつ進めること 信頼状態ファイル自体の巻き戻し
公開鍵のSHA-256 PEM表現に依存しない鍵ID 鍵所有者の身元や業務上の権限

cryptography 50.0.2のEd25519 APIでは、秘密鍵のsign()で署名し、公開鍵のverify()で検証します。署名を検証できない場合はInvalidSignatureが発生します。

署名対象は、遷移オブジェクトをキー順、空白、ASCIIエスケープ、末尾改行まで固定したJSONです。RFC 8785などの汎用的なJSON正規化方式ではなく、このCLI専用の形式です。別実装と連携する場合は、同じバイト列を生成する必要があります。

今回の実行契約

項目 仕様
前提 Python 3.11以上、cryptography 50.0.2。デモ鍵の作成にはOpenSSL 3を使用
bootstrap 信頼できる経路で確認した初期公開鍵と世代から、状態JSONを標準出力へ生成する
prepare 旧・新秘密鍵で同じ遷移JSONへ署名し、エンベロープJSONを標準出力へ生成する
verify 現在状態、鍵世代、鍵ID、両署名を検証し、次状態の候補を標準出力へ生成する
入力サイズ 各パスから最大16,385バイトを読み、16,384バイトを超えた入力を拒否する。ファイル種別は検査しない
JSON入力 状態とエンベロープは、このCLIが生成する固定形式のASCII JSONに限る
秘密鍵 prepareはパスワードなしのEd25519 PKCS#8 PEMだけを受理する。デモ用の制限であり、本番の鍵保管方式ではない
成功 終了コード0。標準出力にはJSONだけを出す
検証拒否 CLI本体が拒否した場合は終了コード2。理由を1行JSONで標準エラー出力へ出す
入出力エラー CLI本体が検出したOSErrorは終了コード1。現在状態は変更しない
引数エラー argparseが終了コード2と使用方法を出す。1行JSONの契約には含めない
対象外 候補状態の本番配置、排他制御、秘密鍵保護、複数人承認、失効、漏えい後の復旧

prepareを使う承認環境と、verifyを使う検証環境は分けられます。検証環境へ渡すエンベロープには、公開鍵、鍵ID、世代、署名だけが入り、秘密鍵は入りません。

三つのサブコマンドを持つCLI

次のコードをkey_transition.pyとして保存します。PEMの読み込み後に鍵種別も確認するため、RSA鍵やX25519鍵は受理しません。読み込みAPIの例外仕様は鍵シリアライズの公式文書で確認できます。

import argparse
import base64
import binascii
import hashlib
import json
import sys
from pathlib import Path

from cryptography.exceptions import InvalidSignature, UnsupportedAlgorithm
from cryptography.hazmat.primitives import serialization
from cryptography.hazmat.primitives.asymmetric.ed25519 import (
    Ed25519PrivateKey,
    Ed25519PublicKey,
)

STATE_SCHEMA = 'manage-ai-trust-state-v1'
ENVELOPE_SCHEMA = 'manage-ai-key-transition-envelope-v1'
TRANSITION_SCHEMA = 'manage-ai-key-transition-v1'
MAX_INPUT_BYTES = 16_384
MAX_EPOCH = 2_147_483_647


class Rejected(Exception):
    pass


def canonical_json(value):
    text = json.dumps(
        value, ensure_ascii=True, sort_keys=True, separators=(',', ':')
    )
    return (text + '\n').encode('ascii')


def read_limited(path, label):
    with path.open('rb') as source:
        data = source.read(MAX_INPUT_BYTES + 1)
    if len(data) > MAX_INPUT_BYTES:
        raise Rejected(f'{label}_too_large')
    return data


def read_canonical_object(path, label):
    raw = read_limited(path, label)
    try:
        value = json.loads(raw.decode('ascii'))
    except (UnicodeDecodeError, json.JSONDecodeError, RecursionError) as exc:
        raise Rejected(f'{label}_invalid_json') from exc
    if type(value) is not dict or canonical_json(value) != raw:
        raise Rejected(f'{label}_not_canonical')
    return value


def exact_fields(value, names, label):
    if set(value) != names:
        raise Rejected(f'{label}_fields_invalid')


def epoch(value, label):
    if type(value) is not int or not (1 <= value <= MAX_EPOCH):
        raise Rejected(f'{label}_invalid')
    return value


def decode_base64(text, size, label):
    if type(text) is not str:
        raise Rejected(f'{label}_invalid')
    try:
        raw = base64.b64decode(text, validate=True)
    except (binascii.Error, ValueError) as exc:
        raise Rejected(f'{label}_invalid') from exc
    if base64.b64encode(raw).decode('ascii') != text:
        raise Rejected(f'{label}_invalid')
    if len(raw) != size:
        raise Rejected(f'{label}_length_invalid')
    return raw


def public_bytes(key):
    return key.public_bytes(
        encoding=serialization.Encoding.Raw,
        format=serialization.PublicFormat.Raw,
    )


def key_id(raw_public_key):
    return 'sha256:' + hashlib.sha256(raw_public_key).hexdigest()


def state_document(key_epoch, raw_public_key):
    return {
        'key_epoch': key_epoch,
        'key_id': key_id(raw_public_key),
        'public_key': base64.b64encode(raw_public_key).decode('ascii'),
        'schema': STATE_SCHEMA,
    }


def load_public_pem(path):
    try:
        key = serialization.load_pem_public_key(
            read_limited(path, 'public_key')
        )
    except (ValueError, TypeError, UnsupportedAlgorithm) as exc:
        raise Rejected('public_key_pem_invalid') from exc
    if not isinstance(key, Ed25519PublicKey):
        raise Rejected('public_key_not_ed25519')
    return key


def load_private_pem(path, label):
    try:
        key = serialization.load_pem_private_key(
            read_limited(path, label), password=None
        )
    except (ValueError, TypeError, UnsupportedAlgorithm) as exc:
        raise Rejected(f'{label}_pem_invalid_or_encrypted') from exc
    if not isinstance(key, Ed25519PrivateKey):
        raise Rejected(f'{label}_not_ed25519')
    return key


def parse_state(path):
    value = read_canonical_object(path, 'state')
    exact_fields(
        value, {'key_epoch', 'key_id', 'public_key', 'schema'}, 'state'
    )
    if value['schema'] != STATE_SCHEMA:
        raise Rejected('state_schema_invalid')

    current_epoch = epoch(value['key_epoch'], 'state_epoch')
    raw_public = decode_base64(
        value['public_key'], 32, 'state_public_key'
    )
    if value['key_id'] != key_id(raw_public):
        raise Rejected('state_key_id_mismatch')
    try:
        public_key = Ed25519PublicKey.from_public_bytes(raw_public)
    except (ValueError, UnsupportedAlgorithm) as exc:
        raise Rejected('state_public_key_invalid') from exc
    return current_epoch, value['key_id'], public_key


def parse_envelope(path):
    envelope = read_canonical_object(path, 'envelope')
    exact_fields(
        envelope,
        {'new_signature', 'old_signature', 'schema', 'transition'},
        'envelope',
    )
    if envelope['schema'] != ENVELOPE_SCHEMA:
        raise Rejected('envelope_schema_invalid')

    transition = envelope['transition']
    if type(transition) is not dict:
        raise Rejected('transition_invalid')
    exact_fields(
        transition,
        {
            'from_epoch',
            'new_key_id',
            'new_public_key',
            'old_key_id',
            'schema',
            'to_epoch',
        },
        'transition',
    )
    if transition['schema'] != TRANSITION_SCHEMA:
        raise Rejected('transition_schema_invalid')

    from_epoch = epoch(transition['from_epoch'], 'from_epoch')
    to_epoch = epoch(transition['to_epoch'], 'to_epoch')
    if from_epoch == MAX_EPOCH or to_epoch != from_epoch + 1:
        raise Rejected('transition_epoch_not_contiguous')
    if (
        type(transition['old_key_id']) is not str
        or type(transition['new_key_id']) is not str
    ):
        raise Rejected('transition_key_id_invalid')

    raw_new_public = decode_base64(
        transition['new_public_key'], 32, 'new_public_key'
    )
    if transition['new_key_id'] != key_id(raw_new_public):
        raise Rejected('new_key_id_mismatch')
    if transition['new_key_id'] == transition['old_key_id']:
        raise Rejected('new_key_same_as_old')
    try:
        new_public = Ed25519PublicKey.from_public_bytes(raw_new_public)
    except (ValueError, UnsupportedAlgorithm) as exc:
        raise Rejected('new_public_key_invalid') from exc

    old_signature = decode_base64(
        envelope['old_signature'], 64, 'old_signature'
    )
    new_signature = decode_base64(
        envelope['new_signature'], 64, 'new_signature'
    )
    return (
        transition,
        canonical_json(transition),
        from_epoch,
        to_epoch,
        new_public,
        raw_new_public,
        old_signature,
        new_signature,
    )


def command_bootstrap(args):
    selected_epoch = epoch(args.epoch, 'epoch')
    raw_public = public_bytes(load_public_pem(args.public_key))
    output = state_document(selected_epoch, raw_public)
    sys.stdout.write(canonical_json(output).decode('ascii'))


def command_prepare(args):
    from_epoch = epoch(args.from_epoch, 'from_epoch')
    if from_epoch == MAX_EPOCH:
        raise Rejected('from_epoch_too_large')

    old_private = load_private_pem(args.old_private, 'old_private')
    new_private = load_private_pem(args.new_private, 'new_private')
    raw_old_public = public_bytes(old_private.public_key())
    raw_new_public = public_bytes(new_private.public_key())
    if raw_old_public == raw_new_public:
        raise Rejected('new_key_same_as_old')

    transition = {
        'from_epoch': from_epoch,
        'new_key_id': key_id(raw_new_public),
        'new_public_key': base64.b64encode(raw_new_public).decode('ascii'),
        'old_key_id': key_id(raw_old_public),
        'schema': TRANSITION_SCHEMA,
        'to_epoch': from_epoch + 1,
    }
    signed_bytes = canonical_json(transition)
    envelope = {
        'new_signature': base64.b64encode(
            new_private.sign(signed_bytes)
        ).decode('ascii'),
        'old_signature': base64.b64encode(
            old_private.sign(signed_bytes)
        ).decode('ascii'),
        'schema': ENVELOPE_SCHEMA,
        'transition': transition,
    }
    sys.stdout.write(canonical_json(envelope).decode('ascii'))


def command_verify(args):
    current_epoch, current_key_id, current_public = parse_state(args.state)
    (
        transition,
        signed_bytes,
        from_epoch,
        to_epoch,
        new_public,
        raw_new_public,
        old_signature,
        new_signature,
    ) = parse_envelope(args.envelope)

    if from_epoch != current_epoch:
        raise Rejected('transition_from_epoch_mismatch')
    if transition['old_key_id'] != current_key_id:
        raise Rejected('transition_old_key_mismatch')
    try:
        current_public.verify(old_signature, signed_bytes)
    except InvalidSignature as exc:
        raise Rejected('old_signature_invalid') from exc
    try:
        new_public.verify(new_signature, signed_bytes)
    except InvalidSignature as exc:
        raise Rejected('new_signature_invalid') from exc

    output = state_document(to_epoch, raw_new_public)
    sys.stdout.write(canonical_json(output).decode('ascii'))


def build_parser():
    root = argparse.ArgumentParser()
    commands = root.add_subparsers(dest='command', required=True)

    bootstrap = commands.add_parser('bootstrap')
    bootstrap.add_argument('--public-key', required=True, type=Path)
    bootstrap.add_argument('--epoch', required=True, type=int)
    bootstrap.set_defaults(handler=command_bootstrap)

    prepare = commands.add_parser('prepare')
    prepare.add_argument('--old-private', required=True, type=Path)
    prepare.add_argument('--new-private', required=True, type=Path)
    prepare.add_argument('--from-epoch', required=True, type=int)
    prepare.set_defaults(handler=command_prepare)

    verify = commands.add_parser('verify')
    verify.add_argument('--state', required=True, type=Path)
    verify.add_argument('--envelope', required=True, type=Path)
    verify.set_defaults(handler=command_verify)
    return root


def main(argv=None):
    args = build_parser().parse_args(argv)
    try:
        args.handler(args)
    except Rejected as exc:
        error = {'reason': str(exc), 'status': 'rejected'}
        print(
            json.dumps(error, sort_keys=True, separators=(',', ':')),
            file=sys.stderr,
        )
        return 2
    except OSError as exc:
        error = {
            'detail': exc.strerror or type(exc).__name__,
            'reason': 'io_error',
            'status': 'error',
        }
        print(
            json.dumps(error, sort_keys=True, separators=(',', ':')),
            file=sys.stderr,
        )
        return 1
    return 0


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

デモ用の鍵を作る

新しい作業ディレクトリを作り、仮想環境へcryptography 50.0.2を導入します。umaskはディレクトリを作る前に設定します。バージョンと導入条件は公式インストール文書で確認できます。

umask 077
mkdir key-rotation-demo && cd key-rotation-demo
python3 -m venv .venv
. .venv/bin/activate
python -m pip install 'cryptography==50.0.2'

key_transition.pyをこのディレクトリへ保存してから、OpenSSLで2組のEd25519鍵を作ります。openssl genpkeyで秘密鍵を生成し、openssl pkey -puboutで公開部分を出力します。

openssl genpkey -algorithm ED25519 -out old-private.pem
openssl pkey -in old-private.pem -pubout -out old-public.pem
openssl genpkey -algorithm ED25519 -out new-private.pem

ここで作る秘密鍵は暗号化されていません。手順確認だけに使い、本番鍵として再利用しないでください。本番では、秘密鍵を同じ作業ディレクトリへ並べる運用自体を見直す必要があります。

初期の信頼状態を作る

初期公開鍵を信頼できるかどうかは、このCLIでは判断できません。入手元、担当者、鍵IDなどを別の信頼できる経路で照合してからbootstrapを実行します。

python key_transition.py bootstrap --public-key old-public.pem --epoch 1 > trust-state.json.part && mv trust-state.json.part trust-state.json

鍵IDは生成した鍵ごとに変わるため、世代と形式を確認します。

python - <<'PY'
import json
from pathlib import Path

state = json.loads(Path('trust-state.json').read_text(encoding='ascii'))
print(state['key_epoch'])
print(state['key_id'].startswith('sha256:') and len(state['key_id']) == 71)
PY

出力は次のとおりです。

1
True

鍵IDはPEMファイル全体ではなく、32バイトのEd25519公開鍵をSHA-256へ入力して作ります。同じ公開鍵なら、PEMの改行形式が変わっても鍵IDは変わりません。鍵IDは照合用の識別子であり、署名の代わりではありません。

旧鍵と新鍵で遷移文書へ署名する

現在の鍵世代が1なので、from_epochへ1を指定します。prepareは次の世代を2とし、遷移オブジェクトの固定バイト列へ旧鍵と新鍵で署名します。

python key_transition.py prepare --old-private old-private.pem --new-private new-private.pem --from-epoch 1 > transition-1-to-2.json.part && mv transition-1-to-2.json.part transition-1-to-2.json

署名対象はエンベロープ全体ではなく、内側のtransitionです。旧鍵ID、新鍵ID、新公開鍵、変更前後の世代を一つのバイト列として固定し、署名値自身は署名対象へ含めません。

実運用では、prepareを検証ホストで実行しません。承認環境でエンベロープを作り、検証ホストにはエンベロープだけを渡します。

現在状態と照合して次状態を生成する

verifyへ現在状態と遷移エンベロープを渡します。すべての検証に成功した場合だけ、次状態の候補が標準出力へ出ます。

python key_transition.py verify --state trust-state.json --envelope transition-1-to-2.json > trust-state.next.json.part && mv trust-state.next.json.part trust-state.next.json

元の状態と候補の世代、鍵IDを比べます。

python - <<'PY'
import json
from pathlib import Path

current = json.loads(Path('trust-state.json').read_text(encoding='ascii'))
next_state = json.loads(Path('trust-state.next.json').read_text(encoding='ascii'))
print(current['key_epoch'], next_state['key_epoch'])
print(current['key_id'] != next_state['key_id'])
PY

出力は次のとおりです。

1 2
True

この時点でもtrust-state.jsonは世代1のままです。候補を生成できたことと、本番の信頼状態として採用したことを分けて扱えます。

同じ遷移を再適用すると拒否される

候補状態を現在状態として、世代1から2への遷移をもう一度渡します。

python key_transition.py verify --state trust-state.next.json --envelope transition-1-to-2.json >/dev/null
printf 'exit=%s\n' $?

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

{"reason":"transition_from_epoch_mismatch","status":"rejected"}
exit=2

両署名が正しくても、現在状態が世代2なら、世代1から2への遷移は受理されません。世代2から4のような飛び越しもtransition_epoch_not_contiguousとして拒否します。

確認しておく拒否経路

入力 結果
世代1の旧鍵から世代2の新鍵へ正常遷移 終了コード0で世代2の候補状態を出力
世代2の状態へ同じ1→2遷移を再適用 transition_from_epoch_mismatch
旧署名の1バイトを変更してBase64へ再エンコード old_signature_invalid
新署名の1バイトを変更してBase64へ再エンコード new_signature_invalid
現在が世代1なのに2→3遷移を提示 transition_from_epoch_mismatch
現在状態とは異なる旧秘密鍵で遷移を作成 transition_old_key_mismatch
固定形式のJSONへ先頭空白を追加 envelope_not_canonical

一つの入力に複数の問題がある場合は、検証順で最初に見つかった理由だけが返ります。個別のエラー名を安全性の証明にせず、終了コード0と生成された候補状態の内容を完了条件にします。

候補状態の配置は別工程にする

このCLIは、標準出力のリダイレクト先や現在状態をロックしません。本番へ組み込む場合は、第180回で扱った受理状態と同じ排他区間で現在状態を読み直し、遷移を検証してから、同じディレクトリの一時ファイル、fsync、os.replace()を使って配置します。

遷移エンベロープも監査資料として残します。ただし、状態ファイルと履歴をまとめて古いコピーへ戻せる場合、ローカルファイルだけでは巻き戻しを検出できません。ローカル状態の外側に、信頼できるチェックポイントが必要です。

二重署名で防げない範囲

  • 旧秘密鍵の漏えい:旧鍵を使える攻撃者は、自分で新鍵を生成して両署名を作れます。復旧には、旧運用鍵とは独立して保護した復旧鍵や、侵害されていない鍵を必要とする複数者承認が必要です。
  • 初期鍵の取り違え:bootstrapは指定された公開鍵を初期状態にします。最初の公開鍵を信頼する根拠はCLIの外で確認します。
  • 二人承認:署名が二つあっても、旧鍵と新鍵を同じ担当者や同じ機器が管理していれば、二人による承認にはなりません。
  • 状態の巻き戻し:古い状態JSONと対応する遷移を一緒に戻された場合、このCLIは、現在渡された状態より新しい履歴を知ることができません。
  • 入力パスの保護:掲載コードはファイル種別、シンボリックリンク、所有者を検査しません。FIFOなどを渡すと読み取りが待ち続ける可能性もあります。入力は、信頼できない利用者が書き込めないディレクトリへ置きます。
  • 秘密鍵の保管:デモのprepareは暗号化されていない秘密鍵を読みます。本番の鍵生成、保管、バックアップ、廃棄を解決するものではありません。

実務へ組み込む前に、検証ホストから旧・新秘密鍵を取り除き、現在状態と遷移エンベロープだけでverifyが成功する構成を確認します。その後、候補状態の配置を既存の排他制御と原子的更新の中へ追加します。