第184回 署名が正しくても期限切れなら通さない:Pythonで検証するEd25519承認の有効期間

第183回では、reviewerとoperatorの署名を役割別に検証しました。ただし、正しい署名がそろっていても、承認の期限を決めなければ過去の文書を後日再利用できます。

今回は、承認ID、成果物のSHA-256、開始時刻not_before、終了時刻expires_atを同じペイロードへ入れて署名します。検証時は、署名と成果物を照合したうえで、検証側が取得した現在時刻を確認します。

有効期間はnot_before <= checked_at < expires_atです。開始時刻は含み、終了時刻は含みません。

期間判定に焦点を絞るため、掲載例の許可鍵は1本です。第183回の役割別承認へ組み込む場合は、必要な署名と役割を検証し、同じペイロードに対して今回の期間判定を行います。

署名の正しさだけでは期限を判断できない

状態 署名検証 今回の判定
開始時刻より前 成功し得る approval_not_yet_validで拒否
開始時刻ちょうど 成功 ほかの条件も満たせば受理
終了時刻より前 成功 ほかの条件も満たせば受理
終了時刻以後 成功し得る approval_expiredで拒否
署名後に期間を変更した 失敗 拒否
期間が検証側の上限を超える 成功し得る approval_window_too_longで拒否

cryptography 50.0.2のEd25519 APIでは、sign()が64バイトの署名を返し、verify()は検証できない署名にInvalidSignatureを発生させます。期限は署名APIが判断するものではないため、署名対象と検証規則に含める必要があります。

現在時刻は検証側で取得する

署名者が文書へ署名時刻を書くだけでは、現在も有効かどうかは判断できません。この実装では、有効期間を署名で固定し、現在時刻は検証プロセスがdatetime.now(timezone.utc)から取得します。

Python 3.11のdatetime文書に沿い、比較する値はすべてUTCのawareなdatetimeにします。

入力形式はRFC 3339の日時形式より狭いYYYY-MM-DDTHH:MM:SSZだけです。小数秒、UTC以外のオフセット、うるう秒は受け付けません。

実行契約

項目 仕様
動作環境 Python 3.11以上、cryptography 50.0.2。コマンド例はPOSIXシェル向け
公開鍵 Ed25519の生公開鍵32バイト
承認文書 BOMなしUTF-8のJSON、8,192バイト以下、重複キーなし
署名対象 payloadをキー順、空白なし、ASCIIエスケープで直列化したバイト列
成果物 通常ファイル、100MiB以下。読み取った全バイトのSHA-256を照合
日時 入出力はUTCの秒形式。現在時刻は取得値の精度で半開区間を判定
期間上限 既定値3,600秒。CLIで指定できる最大値は86,400秒
成功 標準出力へ1行JSON、終了コード0
検証拒否 標準エラー出力へ1行JSON、終了コード1
引数誤り argparseのメッセージ、終了コード2
I/Oまたは実行環境のエラー 標準エラー出力へ1行JSON、終了コード3

--max-window-secondsも検証ポリシーです。実運用では、利用者が自由に変更できない起動設定に固定します。

期限付き承認を検証するCLI

次の内容をapproval_window.pyとして保存します。make-demoは再現確認専用です。秘密鍵はメモリ内で生成し、ファイルへ保存しません。

#!/usr/bin/env python3
from __future__ import annotations

import argparse
import base64
import binascii
import hashlib
import json
import os
import re
import stat
import sys
from datetime import datetime, timedelta, timezone
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,
)

SCHEMA = 'manage-ai.approval-window.v1'
MAX_APPROVAL_BYTES = 8_192
MAX_ARTIFACT_BYTES = 100 * 1024 * 1024
ID_RE = re.compile(r'[A-Za-z0-9][A-Za-z0-9._-]{0,63}')
SHA256_RE = re.compile(r'[0-9a-f]{64}')
UTC_RE = re.compile(
    r'[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z'
)
B64URL_RE = re.compile(r'[A-Za-z0-9_-]+')


class Reject(Exception):
    def __init__(self, code: str):
        super().__init__(code)
        self.code = code


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


def no_duplicate_keys(pairs):
    result = {}
    for key, value in pairs:
        if key in result:
            raise Reject('duplicate_json_key')
        result[key] = value
    return result


def read_limited(path: Path, limit: int, too_large_code: str) -> bytes:
    with path.open('rb') as source:
        data = source.read(limit + 1)
    if len(data) > limit:
        raise Reject(too_large_code)
    return data


def load_approval(path: Path) -> dict:
    raw = read_limited(path, MAX_APPROVAL_BYTES, 'approval_too_large')
    try:
        text = raw.decode('utf-8')
    except UnicodeDecodeError as exc:
        raise Reject('approval_not_utf8') from exc
    try:
        value = json.loads(text, object_pairs_hook=no_duplicate_keys)
    except (ValueError, RecursionError) as exc:
        raise Reject('approval_not_json') from exc
    if type(value) is not dict:
        raise Reject('approval_not_object')
    return value


def canonical_payload(payload: dict) -> bytes:
    return json.dumps(
        payload,
        ensure_ascii=True,
        sort_keys=True,
        separators=(',', ':'),
    ).encode('ascii')


def parse_utc_seconds(value: object, field: str) -> datetime:
    if type(value) is not str or UTC_RE.fullmatch(value) is None:
        raise Reject(f'invalid_{field}')
    try:
        parsed = datetime.strptime(value, '%Y-%m-%dT%H:%M:%SZ')
    except ValueError as exc:
        raise Reject(f'invalid_{field}') from exc
    return parsed.replace(tzinfo=timezone.utc)


def utc_text(value: datetime) -> str:
    return value.astimezone(timezone.utc).strftime('%Y-%m-%dT%H:%M:%SZ')


def decode_signature(value: object) -> bytes:
    if type(value) is not str or B64URL_RE.fullmatch(value) is None:
        raise Reject('invalid_signature_encoding')
    padding = '=' * (-len(value) % 4)
    try:
        decoded = base64.b64decode(
            (value + padding).encode('ascii'),
            altchars=b'-_',
            validate=True,
        )
    except (ValueError, binascii.Error) as exc:
        raise Reject('invalid_signature_encoding') from exc
    if len(decoded) != 64:
        raise Reject('invalid_signature_length')
    return decoded


def sha256_file(path: Path) -> str:
    digest = hashlib.sha256()
    total = 0
    with path.open('rb') as source:
        file_stat = os.fstat(source.fileno())
        if not stat.S_ISREG(file_stat.st_mode):
            raise Reject('artifact_not_regular_file')
        if file_stat.st_size > MAX_ARTIFACT_BYTES:
            raise Reject('artifact_too_large')
        while chunk := source.read(1024 * 1024):
            total += len(chunk)
            if total > MAX_ARTIFACT_BYTES:
                raise Reject('artifact_too_large')
            digest.update(chunk)
    return digest.hexdigest()


def window_seconds(value: str) -> int:
    try:
        seconds = int(value)
    except ValueError as exc:
        raise argparse.ArgumentTypeError('must be an integer') from exc
    if not 1 <= seconds <= 86_400:
        raise argparse.ArgumentTypeError('must be between 1 and 86400')
    return seconds


def approval_id_arg(value: str) -> str:
    if ID_RE.fullmatch(value) is None:
        raise argparse.ArgumentTypeError(
            'must match [A-Za-z0-9][A-Za-z0-9._-]{0,63}'
        )
    return value


def verify(args) -> dict:
    document = load_approval(args.approval)
    if set(document) != {'payload', 'signature'}:
        raise Reject('invalid_envelope_fields')
    payload = document['payload']
    expected_fields = {
        'schema',
        'approval_id',
        'artifact_sha256',
        'not_before',
        'expires_at',
    }
    if type(payload) is not dict or set(payload) != expected_fields:
        raise Reject('invalid_payload_fields')
    if payload['schema'] != SCHEMA:
        raise Reject('unsupported_schema')

    approval_id = payload['approval_id']
    if type(approval_id) is not str or ID_RE.fullmatch(approval_id) is None:
        raise Reject('invalid_approval_id')

    artifact_sha256 = payload['artifact_sha256']
    if (
        type(artifact_sha256) is not str
        or SHA256_RE.fullmatch(artifact_sha256) is None
    ):
        raise Reject('invalid_artifact_sha256')

    not_before = parse_utc_seconds(payload['not_before'], 'not_before')
    expires_at = parse_utc_seconds(payload['expires_at'], 'expires_at')
    if not_before >= expires_at:
        raise Reject('invalid_approval_window')
    if expires_at - not_before > timedelta(seconds=args.max_window_seconds):
        raise Reject('approval_window_too_long')

    public_key_bytes = read_limited(
        args.public_key,
        32,
        'public_key_length',
    )
    if len(public_key_bytes) != 32:
        raise Reject('public_key_length')
    signature = decode_signature(document['signature'])
    try:
        Ed25519PublicKey.from_public_bytes(public_key_bytes).verify(
            signature,
            canonical_payload(payload),
        )
    except InvalidSignature as exc:
        raise Reject('invalid_signature') from exc
    except ValueError as exc:
        raise Reject('invalid_public_key') from exc

    if approval_id != args.expected_approval_id:
        raise Reject('approval_id_mismatch')
    actual_sha256 = sha256_file(args.artifact)
    if actual_sha256 != artifact_sha256:
        raise Reject('artifact_hash_mismatch')

    checked_at = datetime.now(timezone.utc)
    if checked_at < not_before:
        raise Reject('approval_not_yet_valid')
    if checked_at >= expires_at:
        raise Reject('approval_expired')

    return {
        'approval_id': approval_id,
        'artifact_sha256': actual_sha256,
        'checked_at': utc_text(checked_at),
        'expires_at': payload['expires_at'],
        'status': 'accepted',
    }


def write_new(path: Path, data: bytes) -> None:
    with path.open('xb') as destination:
        destination.write(data)


def make_demo(output_dir: Path) -> dict:
    output_dir.mkdir(mode=0o700)
    artifact = b'demo artifact for article 184\n'
    artifact_sha256 = hashlib.sha256(artifact).hexdigest()
    private_key = Ed25519PrivateKey.generate()
    public_key = private_key.public_key().public_bytes(
        encoding=serialization.Encoding.Raw,
        format=serialization.PublicFormat.Raw,
    )
    now = datetime.now(timezone.utc).replace(microsecond=0)
    windows = {
        'valid.json': (
            now - timedelta(minutes=5),
            now + timedelta(minutes=55),
        ),
        'future.json': (
            now + timedelta(hours=1),
            now + timedelta(minutes=65),
        ),
        'expired.json': (
            now - timedelta(minutes=65),
            now - timedelta(hours=1),
        ),
    }

    write_new(output_dir / 'artifact.bin', artifact)
    write_new(output_dir / 'approver.pub', public_key)
    for filename, (not_before, expires_at) in windows.items():
        payload = {
            'schema': SCHEMA,
            'approval_id': 'release-184-demo',
            'artifact_sha256': artifact_sha256,
            'not_before': utc_text(not_before),
            'expires_at': utc_text(expires_at),
        }
        signature = private_key.sign(canonical_payload(payload))
        document = {
            'payload': payload,
            'signature': base64.urlsafe_b64encode(signature)
            .rstrip(b'=')
            .decode('ascii'),
        }
        raw = json.dumps(
            document,
            ensure_ascii=True,
            sort_keys=True,
            separators=(',', ':'),
        ).encode('ascii') + b'\n'
        write_new(output_dir / filename, raw)

    return {
        'approval_id': 'release-184-demo',
        'artifact_sha256': artifact_sha256,
        'directory': str(output_dir),
        'status': 'demo_created',
    }


def build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser()
    subparsers = parser.add_subparsers(dest='command', required=True)

    demo = subparsers.add_parser('make-demo')
    demo.add_argument('output_dir', type=Path)

    verify_parser = subparsers.add_parser('verify')
    verify_parser.add_argument('--public-key', required=True, type=Path)
    verify_parser.add_argument('--approval', required=True, type=Path)
    verify_parser.add_argument('--artifact', required=True, type=Path)
    verify_parser.add_argument(
        '--expected-approval-id',
        required=True,
        type=approval_id_arg,
    )
    verify_parser.add_argument(
        '--max-window-seconds',
        type=window_seconds,
        default=3600,
    )
    return parser


def main() -> int:
    args = build_parser().parse_args()
    try:
        if args.command == 'make-demo':
            emit(sys.stdout, make_demo(args.output_dir))
        else:
            emit(sys.stdout, verify(args))
        return 0
    except Reject as exc:
        emit(sys.stderr, {'error': exc.code, 'status': 'rejected'})
        return 1
    except (OSError, UnsupportedAlgorithm) as exc:
        emit(
            sys.stderr,
            {'error': type(exc).__name__, 'status': 'error'},
        )
        return 3


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

1.依存関係を用意する

空の作業ディレクトリへファイルを保存し、次の順に実行します。demo_184には存在しないパスを指定してください。既存のディレクトリやファイルは上書きしません。

python3.11 -m venv .venv
. .venv/bin/activate
python -m pip install cryptography==50.0.2
python approval_window.py make-demo demo_184

最後のコマンドは、成果物、32バイトの公開鍵、有効期間内・開始前・期限切れの3文書を作ります。固定したデモ成果物から計算される出力は次のとおりです。

{"approval_id":"release-184-demo","artifact_sha256":"7dc97b51bf0e8d8e2167420544bab70bf862bdfe120a65be07efc1541e8548ee","directory":"demo_184","status":"demo_created"}

秘密鍵はファイルへ保存しないため、生成後はこのデモ文書を再署名できません。このコマンドは実運用の署名処理には使いません。

2.有効期間内の文書を検証する

valid.jsonは、生成時刻の5分前から55分後まで有効です。生成後55分を迎える前に実行します。

python approval_window.py verify --public-key demo_184/approver.pub --approval demo_184/valid.json --artifact demo_184/artifact.bin --expected-approval-id release-184-demo

成功すると、statusがacceptedの1行JSONが標準出力へ出て、終了コードは0になります。出力には承認ID、成果物のSHA-256、検証時刻、終了時刻が含まれます。

現在時刻は成果物の読み取り後に取得します。そのため、ハッシュ計算中に終了時刻へ達した文書は受理されません。

3.開始前と期限切れを拒否する

python approval_window.py verify --public-key demo_184/approver.pub --approval demo_184/future.json --artifact demo_184/artifact.bin --expected-approval-id release-184-demo
printf 'exit=%s\n' $?

python approval_window.py verify --public-key demo_184/approver.pub --approval demo_184/expired.json --artifact demo_184/artifact.bin --expected-approval-id release-184-demo
printf 'exit=%s\n' $?

生成直後のfuture.jsonは開始前として拒否されます。

{"error":"approval_not_yet_valid","status":"rejected"}
exit=1

expired.jsonは署名が正しくても期限切れです。

{"error":"approval_expired","status":"rejected"}
exit=1

4.異なる成果物を拒否する

デモ成果物を変更し、署名済みのSHA-256と一致しないことを確認します。前の確認を終えてから実行してください。

printf 'changed\n' >> demo_184/artifact.bin
python approval_window.py verify --public-key demo_184/approver.pub --approval demo_184/valid.json --artifact demo_184/artifact.bin --expected-approval-id release-184-demo
printf 'exit=%s\n' $?
{"error":"artifact_hash_mismatch","status":"rejected"}
exit=1

やり直す場合は、変更済みのディレクトリを再利用せず、make-demoへ別の新規ディレクトリ名を渡します。

検証の順番

  1. 承認文書のサイズ、UTF-8、JSON、重複キー、フィールドを確認する
  2. 日時形式、期間の前後関係、最大期間を確認する
  3. 公開鍵と署名を読み、正規化したpayloadの署名を検証する
  4. 署名済みの承認IDを、CLIで指定した期待値と照合する
  5. 成果物を読み、署名済みのSHA-256と照合する
  6. 現在のUTCを取得し、半開区間へ含まれるか判定する
  7. すべて成功した場合だけ受理結果を出す

形式や期間上限は署名検証より先に調べます。このため、改変された文書が必ずinvalid_signatureになるとは限りません。どの拒否理由でも後続処理へ進めないことが重要です。

この実装だけでは解決しないこと

  • システム時計:時計を過去へ戻せる主体は、期限切れ文書を期間内に見せられます。時刻同期、時計変更の監視、権限分離が別に必要です。
  • 有効期間内の再利用:同じ文書は期間内なら何度でも成功します。一度だけの処理には、消費済み承認IDや受理済み連番を永続化する仕組みが必要です。
  • 完了した処理の取り消し:期限切れは新しい実行を拒否する条件です。期限前に完了した送信、更新、課金などを元へ戻しません。
  • 役割分離:掲載例は1鍵だけを検証します。異なる役割や複数署名は別のポリシーとして検証します。
  • 鍵の信頼:公開鍵の初期配置、秘密鍵の保護、失効、鍵更新は対象外です。
  • 検証後の成果物変更:このCLIは読み取り後の変更を防ぎません。後続処理では、検証したものと同じ固定済みバイト列を使う必要があります。

最初は承認対象を1種類に絞り、業務上必要な最短の期間上限を決めます。署名、役割、成果物ハッシュ、期限を一つの受理処理で確認し、一つでも拒否されたら後続処理を止めます。