pqc_rails 0.1.0

data/docs/THREAT_MODEL.md

@@ -0,0 +1,146 @@
+# Threat Model
+
+pqc_railsが前提としている脅威モデルについて説明します。読者に応じて必要なセクションへ直接ジャンプしてください。
+
+- [意思決定者向け](#for-decision-makers)
+- [開発者向け](#for-developers)
+
+---
+
+## For Decision Makers
+
+### ハーベスト攻撃とは
+
+ハーベスト攻撃(Harvest Now, Decrypt Later)とは、攻撃者が現在の暗号化通信やデータを傍受・保存しておき、将来量子コンピュータが実用化された時点で解読する攻撃を指します。
+
+重要なのは、この攻撃はすでに実行可能だということです。量子コンピュータの実用化を待つ必要があるのは「解読」の段階だけで、「収集」は今この瞬間にも行われる可能性があります。
+
+### なぜ義務化を待ってはいけないか
+
+PQC対応を「将来義務化されるから備える」という発想で捉えると、対応の優先度は規制スケジュール任せになります。しかしハーベスト攻撃の性質上、対応が遅れた期間だけ「将来解読されうるデータ」の範囲が広がり続けます。この損失は義務化の期限とは無関係に、今日も積み上がっています。
+
+### どのデータが危険か
+
+すべてのデータが同じリスクを持つわけではありません。緊急度を判断する物差しとして、以下の3つの期間で考えるフレームワークがあります(Michele Moscaが提唱し、CRYPTRECガイドライン・金融庁報告書が採用)。
+
+- **X**: そのデータを保護し続ける必要がある期間(データの保護期間)
+- **Y**: 暗号方式をPQCへ移行するのに要する期間(移行期間)
+- **Z**: 暗号学的に意味のある量子コンピュータ(CRQC)が実現するまでの期間
+
+**X + Y > Z となる場合、そのデータはハーベスト攻撃の脅威に晒されます。** 移行が完了する前に生成されたデータは、生成時点からX年間保護され続ける必要がありますが、その保護期間が終わるより先にCRQCが実現すれば、収集済みの暗号文が解読される可能性があるためです。
+
+例えば、暗号移行に10年(Y)、生成データの保護期間が20年(X)である場合、実質30年間は旧来の暗号方式による保護を維持することになります。その30年のうちにCRQC(Z)が実現すれば、脅威に晒されることになります。
+
+| データの性質 | Xの目安 | 緊急度 |
+|---|---|---|
+| 医療記録、法務文書、知的財産に関する通信など、10年20年単位で価値を持つデータ | 大きい | 高 |
+| 数年で無価値化する短期データ | 小さい | 低 |
+
+長期保存データを扱うシステムほど、対応の緊急度は高くなります。Z(CRQCの実現時期)は予測が困難なため、Xが大きいデータについては、Y(移行に要する期間)を短縮すること、すなわちクリプトグラフィック・アジリティ(暗号アルゴリズムを迅速に切り替えられる性質)を高めておくことが有効な対策になります。
+
+### 現在の対応状況
+
+国防・国家機密レベルのデータについては、NSAのCNSA 2.0のように段階的な移行スケジュールがすでに存在します。一方、民間の一般的なWebサービスやRailsアプリケーションが扱うデータについては、対応がまだこれからの段階にあります。
+
+### 規制動向(参考)
+
+「いつまでに対応すべきか」の参考として、各国・各機関が示している具体的な年限を挙げます。pqc_railsやその利用企業がこれらの規制対象に直接該当するとは限りませんが、業界全体の移行圧力がどの速度で強まっているかの目安になります。
+
+| 主体 | 年限 | 内容 |
+|---|---|---|
+| フランスANSSI | 2027年〜 | 量子耐性のないセキュリティ製品の認証を停止する方針を表明(欧州初のPQC認証義務化) |
+| 米大統領令14412 (2026-06-22署名) | — | "Securing the Nation Against Advanced Cryptographic Attacks"。連邦システムのPQC移行を義務化 |
+| 米大統領令14413 (2026-06-22署名) | 2026年12月中旬めど | "Ushering in the Next Frontier of Quantum Innovation"。180日以内に国家量子戦略の改定を指示 |
+| 米国防総省 | 2031年まで | "Post-Quantum Cryptography Strategy"。完全PQC移行を義務付け |
+| Microsoft Quantum Safe Program | 2029年まで | 自社製品・サービス群のPQC移行目標年を前倒し |
+
+参考: 国家量子戦略(改定版)は2026年12月中旬に公表予定です(本ドキュメント執筆時点では未公表)。
+
+### CRQC実現時期の観測材料
+
+「量子コンピュータがいつ暗号解読に使えるようになるか」について、決定的な予測は存在しません。以下は2026年7月時点で確認された、実現時期の前後を示唆する動き(ハードウェアの進展、業界の資金調達、基礎研究)の一部です。
+
+- Google Quantum AIが強化学習による計算中リアルタイム較正で、超伝導チップ「Willow」の論理エラー率を約20%削減しました(Nature誌、2026年7月)。ただし暗号学的に意味のある量子コンピュータ(CRQC)に必要な桁違いの低エラー率にはまだ遠い、という留保が研究側からも示されています
+- 量子ハードウェア企業への資金調達が継続しています(IQMのNasdaq上場、Qolabの5,420万ドルSeries B、Oratomicの3億ドルSeries A等)
+- Oratomic(中性原子方式)は「約1万〜2万量子ビットでフォールトトレラント量子計算が可能」と主張しており、関連する資源見積もり論文ではECC-256(secp256k1)解読に約2万6000量子ビットで約10日、RSA-2048解読に約10万2000量子ビットで約3ヶ月という試算を示しています。ただしこれは当事者による見積もりであり、査読済み論文でもNIST/CRYPTRECの公式見解でもない点は割り引いて評価する必要があります
+- **256ビット楕円曲線離散対数問題(ECDLP-256)の解読に必要な論理量子ビット数の見積もりが、2026年に入り継続的に下方修正されています**。ECDLP-256は`HybridKem`が古典側で使うX25519の安全性根拠そのものです。
+  - Google Quantum AI(2026年3月発表、secp256k1/ECDSA対象): 約1,175論理量子ビット。詳細な回路設計はゼロ知識証明で秘匿する「責任ある開示」の形を取りました
+  - EUROCRYPT 2026採択のChevignard等(査読済み): 1,098論理量子ビット
+  - 2026年7月15日arXiv投稿のHan Luo等(査読未了): 835論理量子ビット
+  - いずれも理論的な量子回路設計・資源見積もりの改善であり、実機でこの規模のエラー訂正済み論理量子ビットが実現された例は現時点で存在しません。しかし見積もりが数ヶ月単位で切り下げられ続けている傾向自体は注視が必要です
+  - `HybridKem`はX25519とML-KEMを併用するハイブリッド構成であるため、上記のようにECDLP-256側の見積もりが前進しX25519が将来解読された場合でも、ML-KEM側(NISTがShorのアルゴリズムに対して安全と評価するアルゴリズム)が共有鍵の安全性を独立に担保します
+
+これらの動きはいずれも「CRQCの実現が近づいている」ことの直接証拠ではなく、業界の投資・研究ペースを示す間接的な材料として捉えるべきです。過度に危機感を煽る根拠にも、逆に「まだ先の話」と対応を先送りする根拠にも使うべきではありません。
+
+---
+
+## For Developers
+
+### pqc_railsが想定する攻撃シナリオ
+
+1. **通信傍受**: TLS通信路上で暗号化されたセッションデータ・Cookieが第三者に傍受され、保存されます
+2. **保存データの窃取**: データベースに保存された暗号化カラム(ActiveRecord::Encryption等)が、バックアップ流出やDB侵害を通じて第三者の手に渡ります
+3. **将来の解読**: 上記1・2で収集された暗号文が、量子コンピュータの実用化後にRSA/ECCベースの鍵交換・署名を解読され、平文化されます
+
+pqc_railsは主に2のシナリオ、すなわち保存データに対するPQC対応(KEM-DEM構成による暗号化)を対象にしています。
+
+### 技術的な対応範囲
+
+- **鍵交換**: ML-KEM(NIST FIPS 203、512/768/1024の3レベルに対応)です。`PqcRails::Kem`がliboqs経由で提供し、`PqcRails::HybridKem`が古典アルゴリズムとの併用を担います
+- **署名**: ML-DSA(NIST FIPS 204、44/65/87の3レベルに対応)です。`PqcRails::Sig`としてliboqs経由で提供していますが、現時点ではスタンドアロンAPIの提供にとどまり、セッションCookieやActiveRecord::Encryptionへの統合(署名によるデータ完全性検証)には組み込まれていません
+- **構成**: `HybridKem`(X25519によるECDH + ML-KEMのKEM-DEM構成)です。両者の共有鍵とciphertextをHKDF-SHA256で結合し、ML-KEM側に未知の脆弱性が見つかった場合でも古典側の安全性でフォールバックできるようにしています。データ本体の暗号化はAES-256-GCM(`EnvelopeCipher`)が担います。この「連結してからHKDFにかける」コンバイナは自己流ではなく、[RFC 9954](https://www.rfc-editor.org/rfc/rfc9954)(TLS 1.3ハイブリッド鍵共有)が採用する構成と同じで、NIST SP 800-56Cが承認済み手法として挙げている単純連結に基づきます(2026-07-16、RFC本文を確認して検証済み)。`X25519 + ML-KEM-768`という組み合わせ自体も、ブラウザ・CDN(Chrome、Cloudflare等)に加えて、Microsoftが2026年7月14日の月例更新でWindows 11/Windows Server 2025のTLSスタック(Schannel)に`X25519_MLKEM768`ハイブリッドグループを追加したことで、OSレベルの実装でも標準的な組み合わせとして採用されています([出典](https://www.techtimes.com/articles/320559/20260715/post-quantum-cryptography-comes-windows-tls-three-ml-kem-groups-now-configurable.htm))
+
+### 実測値: セッションCookieサイズの増加
+
+`HybridKem`のciphertextをCookieに含むため、`PqcCookieStore`はRails標準(AES-256-GCM)よりCookieサイズが大きくなります。開発機での実測値(単純なセッション内容)は次の通りです。
+
+| 内容 | pqc_rails(ML-KEM-768、デフォルト) | pqc_rails(ML-KEM-512) | Rails標準 |
+|---|---|---|---|
+| 空セッション | 約1,770 bytes | 約1,300 bytes | 約170 bytes |
+| `user_id` + CSRFトークン程度 | 約1,850 bytes | 約1,400 bytes | 約260 bytes |
+
+固定オーバーヘッドの大半はML-KEM-768のciphertext(1,088byte)がBase64エンコードされた分です。単一Cookieの上限(多くのブラウザで4,096byte)には収まりますが、他のCookie(analytics・A/Bテスト用等)と合算されるリクエストヘッダ全体の上限(多くのサーバ/プロキシで8KB前後)には効いてくる可能性があります。よりサイズを抑えたい場合は`pq_alg_name: :ml_kem_512`を指定してください(NISTセキュリティレベルは768の「レベル3」から512の「レベル1」に下がります)。ActiveRecord::Encryption側(DBカラム)についても同様の増加が生じますが、こちらは未計測です。
+
+### 対応していない範囲(スコープ外)
+
+- **TLS層自体のPQC対応**: pqc_railsはアプリケーション層(セッションCookie・DBカラム)の暗号化のみを扱います。TLS 1.3ハンドシェイクのPQC化は対象外で、Webサーバ・ロードバランサ側の設定に依存します。Rubyエコシステム側でも標準ライブラリ全体をPQC-onlyモードで動作させる議論([Ruby Feature #22068](https://bugs.ruby-lang.org/issues/22068)、前提となる`ruby/openssl#894`はマージ済み)が進んでいますが、これはTLS/net-httpレイヤーの話であり、pqc_railsが対象とするアプリケーションデータの暗号化とはレイヤーが異なります
+- **PKI・証明書管理基盤としての機能**: 鍵の発行・失効・証明書ライフサイクル管理・監査ログの提供は対象外です。pqc_railsはRailsアプリ内のセッション・DBカラムの暗号化に特化したライブラリであり、Keyfactor等のエンタープライズPKI基盤の代替ではありません
+- **量子ネイティブな暗号方式**: QKD(量子鍵配送)、ワンショット署名など、量子コンピュータ自体のリソースを前提とする暗号方式は対象外です。pqc_railsが提供するのは古典コンピュータ上で動作し量子コンピュータへの耐性を持つ暗号(PQC)であり、両者は根本的に異なる技術カテゴリです
+- **鍵管理基盤(HSM/KMS等)との連携**: 鍵はデフォルトではRails credentialsまたは環境変数(`KeySource`経由)から読み込みます。`#current_keypair` / `#previous_keypairs` を実装したオブジェクトへの差し替えは可能ですが(将来のHSM/PKCS#11連携を見据えた拡張ポイント)、具体的なHSMやクラウドKMSとの統合実装自体は現時点で提供していません
+
+### コンプライアンス・マッピング
+
+「NIST標準にどう対応しているか」を、監査・調達担当者向けに簡潔にまとめます。
+
+| pqc_railsの実装 | 対応するNIST標準 | 備考 |
+|---|---|---|
+| `PqcRails::Kem` / `HybridKem`の鍵交換(KEM) | FIPS 203 (ML-KEM) | 512/768/1024の3レベルに対応。X25519とのハイブリッド構成(`HybridKem`)で運用します |
+| `PqcRails::Sig`の署名 | FIPS 204 (ML-DSA) | 44/65/87の3レベルに対応。現時点ではスタンドアロンAPIのみで、セッション/DB統合には未組み込みです |
+| `EnvelopeCipher`のデータ本体暗号化 | FIPS 197 (AES) / SP 800-38D (GCM) | AES-256-GCMです。NISTはAES-256をGroverのアルゴリズムに対する耐性の観点から量子コンピュータに対しても安全と位置づけています(鍵長が十分であるため) |
+
+KEM-DEM構成全体としては、鍵交換をFIPS 203準拠のML-KEMが担い、データ本体をNIST承認済みの対称暗号(AES-256-GCM)が担う、という構成になります。SLH-DSA(FIPS 205)への対応は現時点で行っていません。
+
+### FIPS 203/204のshall要件との対応(監査結果)
+
+FIPS 203 §3.3(ML-KEM実装への要求事項)とFIPS 204 §3.6(追加の要求事項)に列挙されているshall要件を、pqc_railsの実装(liboqsへのFFIバインディング層)と突き合わせて監査しました(2026-07-16)。
+
+| 要件 | 対応状況 |
+|---|---|
+| K-PKEをスタンドアロンで使わない | 満たしています(トップレベルのML-KEM APIのみ使用) |
+| derandomized版など内部関数への制御されたアクセス | 満たしています(標準APIのみをFFI経由で呼び出し可能にしています) |
+| 共有鍵の以降利用が承認済み手法(NIST SP 800-56C) | 満たしています(`HybridKem`はHKDF-SHA256で導出) |
+| 乱数生成器の強度がパラメータセットの要求以上 | liboqsの内部RNGに委譲しており、pqc_rails自身では検証していません(既知の限界) |
+| Encaps/Decaps・sign/verifyの入力長チェック | 満たしています(公開鍵・秘密鍵・暗号文・署名すべての長さをliboqs呼び出し前に検証します) |
+| 中間値の破棄 | Rubyレイヤーでの明示的なメモリワイプは未実装です。GCおよびFFIのfree()はゼロクリアを保証しないため、既知の限界として扱っています |
+| 浮動小数点演算を使わない | 該当しません(pqc_railsは暗号計算そのものを実装しておらず、liboqsのC実装に委譲しています) |
+
+**乱数生成器の強度・中間値の破棄**については、pqc_rails自身のコードでは検証しきれない範囲(liboqsのC実装内部)であるため、「満たしている」と断定せず、現時点での既知の限界として明記します。
+
+### 参照仕様
+
+- NIST FIPS 203 (ML-KEM)
+- NIST FIPS 204 (ML-DSA)
+- [CRYPTREC暗号技術ガイドライン(耐量子計算機暗号)2024年度版](https://www.cryptrec.go.jp/report/cryptrec-gl-2007-2024.pdf) — X+Y>Zフレームワーク、クリプトグラフィック・アジリティの定義の出典
+- [金融庁「預金取扱金融機関の耐量子計算機暗号への対応に関する検討会 報告書」(2024年11月)](https://www.fsa.go.jp/singi/pqc/houkokusyo.pdf) — X+Y>Zの具体例、クリプト・インベントリの構成例の出典
+- [国家量子戦略(改定版)](https://www.whitehouse.gov/presidential-actions/2026/06/ushering-in-the-next-frontier-of-quantum-innovation/) — 米大統領令14413に基づき2026年12月中旬公表予定です。本ドキュメント執筆時点(2026年7月)では未公表のプレースホルダー参照です
+- [ISO/IEC 18033-2:2006/Amd 2:2026](https://www.iso.org/standard/86890.html) (Classic McEliece)

data/lib/pqc_rails/active_record/context.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "active_record"
+require_relative "../cipher"
+require_relative "key_provider"
+
+module PqcRails
+  module ActiveRecord
+    # ActiveRecord::Encryptionのデフォルトcontextに、PqcRails::Cipherと
+    # PqcRails::ActiveRecord::KeyProviderを設定する。
+    #
+    # 注意: ActiveRecord::Encryption.config.custom_contexts はwith_encryption_context用の
+    # スレッドローカルな一時上書きスタックで、永続的な差し替えには使えない。
+    # 永続的な差し替えの正しい入口は ActiveRecord::Encryption.configure(...)。
+    module Context
+      module_function
+
+      def install!(pq_alg_name: PqcRails::Cipher::DEFAULT_PQ_ALG_NAME,
+                   primary_key: existing_config_value(:primary_key),
+                   deterministic_key: existing_config_value(:deterministic_key),
+                   key_derivation_salt: existing_config_value(:key_derivation_salt))
+        ::ActiveRecord::Encryption.configure(
+          key_provider: PqcRails::ActiveRecord::KeyProvider.new,
+          cipher: PqcRails::Cipher.new(pq_alg_name: pq_alg_name),
+          primary_key: primary_key,
+          deterministic_key: deterministic_key,
+          key_derivation_salt: key_derivation_salt
+        )
+      end
+
+      # ActiveRecord::Encryption.configure(...)は呼ぶたびにprimary_key/deterministic_key/
+      # key_derivation_saltを常に上書きする(未指定ならnilで巻き戻す)ため、install!を呼ぶ前に
+      # bin/rails db:encryption:init等で既に設定されていた値を、明示的な指定が無い限り
+      # 引き継ぐ。config側の値は未設定だとErrors::Configurationを送出しうるので握りつぶす。
+      def existing_config_value(name)
+        ::ActiveRecord::Encryption.config.public_send(name)
+      rescue ::ActiveRecord::Encryption::Errors::Configuration
+        nil
+      end
+    end
+  end
+end

data/lib/pqc_rails/active_record/key_provider.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "digest"
+require_relative "../key_source"
+
+module PqcRails
+  module ActiveRecord
+    # ActiveRecord::Encryption::KeyProvider互換。HybridKemの鍵ペアを返す実装。
+    #
+    # 既存のActiveRecord::Encryption::KeyProvider(Key#secretが単一の不透明な文字列)は
+    # 公開鍵/秘密鍵という「鍵ペア」の概念を持たないため、ML-KEMを使う余地が無い。
+    # そのためKeyProvider自体を独自実装し、`key.secret`がPqcRails::HybridKem::Keypair
+    # (公開鍵・秘密鍵のペア)を返すようにしている。
+    #
+    # 鍵のソース(環境変数→Rails credentials→decode)はKeySourceに一本化されており、
+    # セッション用の鍵とは異なるENV変数名/credentialsキーを渡すことで用途ごとに鍵を分離する。
+    #
+    # 鍵ローテーションは#decryption_keysが現行鍵に続けて旧鍵世代を返すことで対応する
+    # (ActiveRecord::Encryption::Cipher互換の#decryptは配列の各鍵を順に試すため、
+    # PqcRails::Cipher#decryptは変更不要)。旧鍵はPQC_RECORD_PREVIOUS_KEYS(ENV)または
+    # pqc_record_previous_keys(credentials)から読み込む。
+    class KeyProvider
+      ENV_VAR = "PQC_RECORD_KEY"
+      PREVIOUS_ENV_VAR = "PQC_RECORD_PREVIOUS_KEYS"
+      CREDENTIALS_KEY = :pqc_record_key
+      PREVIOUS_CREDENTIALS_KEY = :pqc_record_previous_keys
+
+      Key = Struct.new(:secret) do
+        def id
+          Digest::SHA1.hexdigest(secret.public_key).first(4)
+        end
+
+        def public_tags
+          @public_tags ||= ::ActiveRecord::Encryption::Properties.new
+        end
+      end
+
+      def initialize(key_source: default_key_source)
+        @key_source = key_source
+      end
+
+      def encryption_key
+        @encryption_key ||= build_key(@key_source.current_keypair)
+      end
+
+      def decryption_keys(_encrypted_message)
+        [encryption_key] + @key_source.previous_keypairs.map { |keypair| build_key(keypair) }
+      end
+
+      private
+
+      def default_key_source
+        PqcRails::KeySource::EnvCredentials.new(
+          env_var: ENV_VAR, previous_env_var: PREVIOUS_ENV_VAR,
+          credentials_key: CREDENTIALS_KEY, previous_credentials_key: PREVIOUS_CREDENTIALS_KEY,
+          label: "record"
+        )
+      end
+
+      def build_key(keypair)
+        Key.new(keypair).tap do |key|
+          key.public_tags.encrypted_data_key_id = key.id if ::ActiveRecord::Encryption.config.store_key_references
+        end
+      end
+    end
+  end
+end

data/lib/pqc_rails/algorithms.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module PqcRails
+  # NIST標準化アルゴリズムのシンボル名(:ml_kem_512等)とliboqs側のアルゴリズム名文字列
+  # ("ML-KEM-512"等)を対応づけるレジストリ。
+  #
+  # Kem/Sigはliboqsの生の文字列を直接渡すこともできるが(liboqsが対応する任意のアルゴリズムを
+  # 使える柔軟性は維持する)、このレジストリを経由してシンボルで指定すれば、
+  # liboqs側の命名に依存しない安定したAPIになる。
+  # 将来 ActiveRecord::Encryption と統合する際、設定ファイルやモデルにliboqsの生文字列を
+  # 書かせるのではなく、このシンボルを書かせることを想定している。
+  #
+  # 使い方:
+  #   PqcRails::Kem.new(:ml_kem_512)
+  #   PqcRails::Sig.new(:ml_dsa_44)
+  module Algorithms
+    class UnknownAlgorithmError < PqcRails::Error; end
+
+    Algorithm = Struct.new(:name, :liboqs_name, :family, :security_level, :status, keyword_init: true)
+
+    KEMS = {
+      ml_kem_512: Algorithm.new(
+        name: :ml_kem_512, liboqs_name: "ML-KEM-512", family: :kem, security_level: 1, status: :recommended
+      ),
+      ml_kem_768: Algorithm.new(
+        name: :ml_kem_768, liboqs_name: "ML-KEM-768", family: :kem, security_level: 3, status: :recommended
+      ),
+      ml_kem_1024: Algorithm.new(
+        name: :ml_kem_1024, liboqs_name: "ML-KEM-1024", family: :kem, security_level: 5, status: :recommended
+      )
+    }.freeze
+
+    SIGS = {
+      ml_dsa_44: Algorithm.new(
+        name: :ml_dsa_44, liboqs_name: "ML-DSA-44", family: :sig, security_level: 2, status: :recommended
+      ),
+      ml_dsa_65: Algorithm.new(
+        name: :ml_dsa_65, liboqs_name: "ML-DSA-65", family: :sig, security_level: 3, status: :recommended
+      ),
+      ml_dsa_87: Algorithm.new(
+        name: :ml_dsa_87, liboqs_name: "ML-DSA-87", family: :sig, security_level: 5, status: :recommended
+      )
+    }.freeze
+
+    module_function
+
+    def find_kem(name)
+      KEMS.fetch(name.to_sym)
+    rescue KeyError
+      raise UnknownAlgorithmError, "unknown KEM algorithm: #{name.inspect}. Known: #{KEMS.keys.join(', ')}"
+    end
+
+    def find_sig(name)
+      SIGS.fetch(name.to_sym)
+    rescue KeyError
+      raise UnknownAlgorithmError, "unknown SIG algorithm: #{name.inspect}. Known: #{SIGS.keys.join(', ')}"
+    end
+
+    # liboqsに渡すべきアルゴリズム名文字列を解決する。
+    # Stringが渡された場合はliboqsの生の名前としてそのまま通す(後方互換・将来の未登録アルゴリズム用)。
+    # Symbolが渡された場合はレジストリ経由でliboqs名に変換する。
+    def resolve_kem_name(name)
+      return name if name.is_a?(String)
+
+      find_kem(name).liboqs_name
+    end
+
+    def resolve_sig_name(name)
+      return name if name.is_a?(String)
+
+      find_sig(name).liboqs_name
+    end
+  end
+end

data/lib/pqc_rails/blob_packing.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module PqcRails
+  # 2つのバイト列を [4byte長][本体][4byte長][本体] で1本のバイト列にまとめる、その逆を行う。
+  # HybridKemの鍵/ciphertextパック(古典+PQ)と、KeyManagerの鍵シリアライズ(公開鍵+秘密鍵)で
+  # 同じ処理が必要になるため共通化している。
+  module BlobPacking
+    module_function
+
+    def pack(first, second)
+      [first.bytesize].pack("N") + first + [second.bytesize].pack("N") + second
+    end
+
+    def unpack(blob)
+      first_length = blob[0, 4].unpack1("N")
+      first = blob[4, first_length]
+
+      second_offset = 4 + first_length
+      second_length = blob[second_offset, 4].unpack1("N")
+      second = blob[(second_offset + 4), second_length]
+
+      [first, second]
+    end
+  end
+end

data/lib/pqc_rails/cipher.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "active_record"
+require_relative "hybrid_kem"
+require_relative "envelope_cipher"
+require_relative "session/encryptor"
+
+module PqcRails
+  # ActiveRecord::Encryption::Cipher互換のインターフェースを持つ独立したクラス。
+  # ActiveRecord::Encryption.configure(cipher: PqcRails::Cipher.new, key_provider: ...)で
+  # デフォルトのAES-256-GCM単体実装を完全に置き換える。
+  #
+  # ActiveRecord::Encryptionの`key:`は「鍵そのもの」をそのまま渡してくる設計
+  # (KeyProvider#encryption_key.secretの値がそのまま渡る)。本実装ではKeyProvider側で
+  # `key.secret`がPqcRails::HybridKem::Keypair(公開鍵・秘密鍵のペア)を返すように
+  # 揃えてあるので、ここではそのKeypairを直接受け取れる。
+  #
+  # 内部的にはPhase 2と同じKEM-DEM構成(HybridKem+EnvelopeCipher)。
+  # Session::Encryptorを再利用しないのは、ARはCipher層に外から`key:`を渡す設計のため
+  # 鍵の持ち方が異なるから(Session::Encryptorは自分でKeypairを保持する)。
+  class Cipher
+    DEFAULT_PQ_ALG_NAME = PqcRails::Session::Encryptor::DEFAULT_PQ_ALG_NAME
+
+    def initialize(pq_alg_name: DEFAULT_PQ_ALG_NAME)
+      @pq_alg_name = pq_alg_name
+    end
+
+    def encrypt(clear_text, key:, deterministic: false)
+      raise ArgumentError, "PqcRails::Cipher does not support deterministic encryption" if deterministic
+
+      HybridKem.open(@pq_alg_name) do |hybrid|
+        encap = hybrid.encapsulate(key.public_key)
+        envelope = EnvelopeCipher.new(encap.shared_secret).encrypt(clear_text)
+
+        ::ActiveRecord::Encryption::Message.new(payload: envelope).tap do |message|
+          message.headers[:kem_ct] = encap.ciphertext
+        end
+      end
+    end
+
+    def decrypt(encrypted_message, key:)
+      keypairs = key.is_a?(::Array) ? key : [key]
+      last_error = nil
+
+      HybridKem.open(@pq_alg_name) do |hybrid|
+        keypairs.each do |keypair|
+          return decrypt_with(hybrid, encrypted_message, keypair)
+        rescue OpenSSL::Cipher::CipherError, PqcRails::Error, ArgumentError, TypeError => e
+          last_error = e
+        end
+      end
+
+      raise ::ActiveRecord::Encryption::Errors::Decryption, last_error&.message
+    end
+
+    def key_length
+      EnvelopeCipher::KEY_LENGTH
+    end
+
+    def iv_length
+      EnvelopeCipher::IV_LENGTH
+    end
+
+    private
+
+    def decrypt_with(hybrid, encrypted_message, keypair)
+      kem_ciphertext = encrypted_message.headers[:kem_ct]
+      raise PqcRails::Error, "message is missing the kem_ct header" if kem_ciphertext.nil?
+
+      shared_secret = hybrid.decapsulate(kem_ciphertext, keypair.secret_key)
+      EnvelopeCipher.new(shared_secret).decrypt(encrypted_message.payload)
+    end
+  end
+end

data/lib/pqc_rails/configuration.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module PqcRails
+  # gem全体の設定。Railsアプリ側からは以下のように使う想定:
+  #
+  #   # config/initializers/pqc_rails.rb
+  #   PqcRails.configure do |config|
+  #     config.liboqs_path = "/usr/local/lib/liboqs.dylib"
+  #   end
+  class Configuration
+    # liboqsの共有ライブラリへのパス。
+    # 未設定の場合、環境変数 LIBOQS_PATH、それも無ければOS標準の場所を仮定する。
+    attr_accessor :liboqs_path
+
+    def initialize
+      @liboqs_path = ENV["LIBOQS_PATH"] || default_liboqs_path
+    end
+
+    private
+
+    # OS別のliboqsデフォルトパス。
+    # あくまで「よくあるインストール場所」の当て推量であり、
+    # 本番運用では明示的に liboqs_path を設定することを強く推奨する。
+    def default_liboqs_path
+      case RbConfig::CONFIG["host_os"]
+      when /darwin/
+        "/usr/local/lib/liboqs.dylib"
+      when /linux/
+        "/usr/local/lib/liboqs.so"
+      else
+        raise PqcRails::Error,
+              "liboqs_path is not set and no default is known for this OS (#{RbConfig::CONFIG['host_os']}). " \
+              "Set PqcRails.configure { |c| c.liboqs_path = '...' } explicitly."
+      end
+    end
+  end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+  end
+end

data/lib/pqc_rails/dh_kem.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "openssl"
+require_relative "length_validation"
+
+module PqcRails
+  # 古典的なECDH(X25519)を「KEM」のAPI形状(generate_keypair/encapsulate/decapsulate)で
+  # 包んだクラス。RFC 9180(HPKE)のDHKEMと同じ考え方:
+  #
+  #   encapsulate: 一時鍵ペアを生成し、一時秘密鍵と相手の公開鍵からECDHで共有鍵を導出する。
+  #                ciphertextは一時鍵の公開鍵そのもの。
+  #   decapsulate: 自分の秘密鍵とciphertext(相手の一時公開鍵)からECDHで同じ共有鍵を導出する。
+  #
+  # これにより PqcRails::Kem (liboqs) と同じインターフェースで古典鍵を扱えるようになり、
+  # HybridKem側で両者を対称に組み合わせられる。
+  #
+  # 使い方:
+  #   dh_kem = PqcRails::DhKem.new
+  #   keypair = dh_kem.generate_keypair
+  #   encap   = dh_kem.encapsulate(keypair.public_key)
+  #   shared  = dh_kem.decapsulate(encap.ciphertext, keypair.secret_key)
+  #   shared == encap.shared_secret # => true
+  class DhKem
+    include LengthValidation
+
+    Keypair = Struct.new(:public_key, :secret_key)
+    Encapsulation = Struct.new(:ciphertext, :shared_secret)
+
+    KEY_LENGTH = 32
+
+    attr_reader :curve
+
+    def initialize(curve = "X25519")
+      @curve = curve
+    end
+
+    def length_public_key    = KEY_LENGTH
+    def length_secret_key    = KEY_LENGTH
+    def length_ciphertext    = KEY_LENGTH
+    def length_shared_secret = KEY_LENGTH
+
+    def generate_keypair
+      key = OpenSSL::PKey.generate_key(@curve)
+      Keypair.new(key.raw_public_key, key.raw_private_key)
+    end
+
+    def encapsulate(public_key)
+      validate_length!(public_key, length_public_key, "public_key")
+
+      peer_key  = OpenSSL::PKey.new_raw_public_key(@curve, public_key)
+      ephemeral = OpenSSL::PKey.generate_key(@curve)
+
+      Encapsulation.new(ephemeral.raw_public_key, ephemeral.derive(peer_key))
+    end
+
+    def decapsulate(ciphertext, secret_key)
+      validate_length!(ciphertext, length_ciphertext, "ciphertext")
+      validate_length!(secret_key, length_secret_key, "secret_key")
+
+      own_key       = OpenSSL::PKey.new_raw_private_key(@curve, secret_key)
+      ephemeral_pub = OpenSSL::PKey.new_raw_public_key(@curve, ciphertext)
+
+      own_key.derive(ephemeral_pub)
+    end
+  end
+end

data/lib/pqc_rails/envelope_cipher.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "openssl"
+require_relative "length_validation"
+
+module PqcRails
+  # AES-256-GCMによるエンベロープ暗号化。HybridKem等で導出した32バイトの共有鍵を使って
+  # 実際のデータ(平文)を暗号化/復号する。「鍵交換」と「データ暗号化」を分離するのは、
+  # 後でActiveRecord::Encryption統合(Phase 3)で「鍵→暗号化結果」のインターフェースとして
+  # そのまま使えるようにするため。
+  #
+  # 暗号文のフォーマット: IV(12byte) + 認証タグ(16byte) + 暗号文本体
+  # この3つを1本のバイト列にまとめて返すことで、DBカラム等に1カラムでそのまま保存できる。
+  #
+  # 使い方:
+  #   cipher = PqcRails::EnvelopeCipher.new(key) # 32バイトの鍵
+  #   encrypted = cipher.encrypt("secret")
+  #   cipher.decrypt(encrypted) # => "secret"
+  class EnvelopeCipher
+    include LengthValidation
+
+    CIPHER_NAME = "aes-256-gcm"
+    KEY_LENGTH = 32
+    IV_LENGTH = 12
+    TAG_LENGTH = 16
+
+    def initialize(key)
+      validate_length!(key, KEY_LENGTH, "key")
+      @key = key
+    end
+
+    def encrypt(plaintext, associated_data: nil)
+      cipher = OpenSSL::Cipher.new(CIPHER_NAME)
+      cipher.encrypt
+      cipher.key = @key
+      iv = cipher.random_iv
+      cipher.auth_data = associated_data if associated_data
+
+      ciphertext = cipher.update(plaintext) + cipher.final
+
+      iv + cipher.auth_tag + ciphertext
+    end
+
+    def decrypt(encrypted, associated_data: nil)
+      iv         = encrypted[0, IV_LENGTH]
+      tag        = encrypted[IV_LENGTH, TAG_LENGTH]
+      ciphertext = encrypted[(IV_LENGTH + TAG_LENGTH)..]
+
+      cipher = OpenSSL::Cipher.new(CIPHER_NAME)
+      cipher.decrypt
+      cipher.key = @key
+      cipher.iv = iv
+      cipher.auth_tag = tag
+      cipher.auth_data = associated_data if associated_data
+
+      cipher.update(ciphertext) + cipher.final
+    end
+  end
+end

data/lib/pqc_rails/ffi/kem.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "ffi"
+
+module PqcRails
+  module Ffi
+    # liboqsのGeneric KEM APIへの低レベルFFIバインディング。
+    module Kem
+      extend FFI::Library
+
+      ffi_lib PqcRails.configuration.liboqs_path
+
+      class Struct < FFI::Struct
+        layout(
+          :method_name,          :pointer,
+          :alg_version,          :pointer,
+          :claimed_nist_level,   :uint8,
+          :ind_cca,               :bool,
+          :length_public_key,    :size_t,
+          :length_secret_key,    :size_t,
+          :length_ciphertext,    :size_t,
+          :length_shared_secret, :size_t,
+          :length_keypair_seed,  :size_t,
+          :length_encaps_seed,   :size_t,
+          :keypair_derand,       :pointer,
+          :keypair,               :pointer,
+          :encaps_derand,        :pointer,
+          :encaps,                :pointer,
+          :decaps,                :pointer
+        )
+      end
+
+      attach_function :OQS_KEM_new, [:string], :pointer
+      attach_function :OQS_KEM_free, [:pointer], :void
+      attach_function :OQS_KEM_keypair, [:pointer, :pointer, :pointer], :int
+      attach_function :OQS_KEM_encaps, [:pointer, :pointer, :pointer, :pointer], :int
+      attach_function :OQS_KEM_decaps, [:pointer, :pointer, :pointer, :pointer], :int
+    end
+  end
+end