pqc_rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 250cd3e1bab5ae8124f2cc0d6441a47eb345eae6335018afd753106e4bdb8dac
+  data.tar.gz: 82a5414aeb14643970385b6bcb7304a0705d7a0a1398dd2a43c244ea12a20b8f
+SHA512:
+  metadata.gz: bb87fe83e203d59c9b467bc0b1fb3ec03f6133910817a992bf6bfc8de4f41faaa3c8a4a9f5b24749033e7d5bd452d781f38ad53f53a7c85450e2dd9b2b3bcfa8
+  data.tar.gz: 631e9d0db9810ca52adc069b6c876b4d7f044c74eb3f3d1f4272a16a468224644a64c1d135bdbbbf88347021c78793a39e895845cfe786628ef861769fe3ccf3

data/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-07-22
+
+### Added
+
+- FFI bindings to [liboqs](https://github.com/open-quantum-safe/liboqs) for NIST-standardized
+  post-quantum algorithms: ML-KEM (FIPS 203, levels 512/768/1024) and ML-DSA (FIPS 204, levels
+  44/65/87), exposed as `PqcRails::Kem` and `PqcRails::Sig`.
+- `PqcRails::Algorithms` registry resolving symbols (e.g. `:ml_kem_768`) to liboqs algorithm
+  names, while still allowing raw liboqs strings for algorithms outside the registry (e.g.
+  Classic McEliece, HQC).
+- `PqcRails::HybridKem`: a KEM-DEM hybrid public-key encryption scheme combining X25519 (classical
+  ECDH) with a post-quantum KEM via HKDF-SHA256, backed by `PqcRails::EnvelopeCipher`
+  (AES-256-GCM).
+- `PqcRails::Session::PqcCookieStore`: a drop-in replacement for Rails' `cookie_store` that
+  encrypts session data with `HybridKem` instead of the standard AES-256-GCM signed/encrypted
+  cookie jar.
+- `PqcRails::ActiveRecord::Context` and `PqcRails::Cipher` / `PqcRails::ActiveRecord::KeyProvider`:
+  a full `ActiveRecord::Encryption` integration, replacing Rails' default cipher and key provider
+  with the `HybridKem`-based implementation.
+- Multi-generation key rotation for both the session store and `ActiveRecord::Encryption`:
+  `previous_keypairs` support lets old keys keep decrypting existing data/sessions while new
+  writes use the current key.
+- `pqc_rails:install` generator, scaffolding the initializer and writing session/record keys to
+  Rails credentials.
+- `docs/MIGRATION.md`: dual-stack migration guide (adopting `pqc_rails` alongside existing
+  encrypted data), key rotation procedure, key-loss recovery guidance, and rollback steps.
+- `docs/THREAT_MODEL.md` and `docs/CRYPTO_INVENTORY.md`: threat model and crypto-inventory
+  documentation for decision-makers and developers.
+- CI workflow building liboqs from source and running the test suite on push/PR.
+
+[Unreleased]: https://github.com/mabutast/pqc_rails/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/mabutast/pqc_rails/releases/tag/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,104 @@
+Business Source License 1.1
+
+License text copyright (c) 2024 MariaDB plc, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB plc.
+
+-----------------------------------------------------------------------------
+
+Parameters
+
+Licensor:             Haruyuki Onodera
+
+Licensed Work:        pqc_rails
+                      The Licensed Work is (c) 2026 Haruyuki Onodera
+
+Additional Use Grant: You may make production use of the Licensed Work,
+                      provided that such use is not a Commercial Use.
+                      "Commercial Use" means use of the Licensed Work, or
+                      any derivative work, in connection with a product or
+                      service (i) for which a fee is charged, or (ii) which
+                      is provided by or on behalf of a for-profit entity as
+                      part of its business operations.
+
+Change Date:          2030-07-16 (July 16th, 2030)
+
+Change License:       Apache License, Version 2.0
+
+-----------------------------------------------------------------------------
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+MariaDB hereby grants you permission to use this License's text to license
+your works, and to refer to it using the trademark "Business Source License",
+as long as you comply with the Covenants of Licensor below.
+
+-----------------------------------------------------------------------------
+
+Covenants of Licensor
+
+In consideration of the right to use this License's text and the "Business
+Source License" name and trademark, Licensor covenants to MariaDB, and to all
+other recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version,
+   or a license that is compatible with GPL Version 2.0 or a later version,
+   where "compatible" means that software provided under the Change License can
+   be included in a program with software provided under GPL Version 2.0 or a
+   later version. Licensor may specify additional Change Licenses without
+   limitation.
+
+2. To either: (a) specify an additional grant of rights to use that does not
+   impose any additional restriction on the right granted in this License, as
+   the Additional Use Grant; or (b) insert the text "None".
+
+3. To specify a Change Date.
+
+4. Not to modify this License in any other way.
+
+-----------------------------------------------------------------------------
+
+Notice
+
+The Business Source License (this document, or the "License") is not an Open
+Source license. However, the Licensed Work will eventually be made available
+under an Open Source License, as stated in this License.

data/README.md

@@ -0,0 +1,306 @@
+# PqcRails
+
+[![Gem Version](https://badge.fury.io/rb/pqc_rails.svg)](https://badge.fury.io/rb/pqc_rails)
+[![Test](https://github.com/mabutast/pqc_rails/actions/workflows/test.yml/badge.svg)](https://github.com/mabutast/pqc_rails/actions/workflows/test.yml)
+
+**pqc_rails** は、既存の Ruby on Rails アプリケーションに耐量子暗号（PQC: Post-Quantum Cryptography）を組み込むための gem です。[liboqs](https://github.com/open-quantum-safe/liboqs) への FFI バインディングを通じて、NIST 標準化アルゴリズムを Ruby ネイティブに呼び出します。
+
+ジェネレータを実行した後、2 行の設定を追加するだけで Rails アプリのセッションと DB を PQC 化できます。
+
+```bash
+rails generate pqc_rails:install
+```
+
+```ruby
+# config/application.rb
+config.session_store :pqc_cookie_store
+
+# config/initializers/pqc_rails.rb
+PqcRails::ActiveRecord::Context.install!
+```
+
+## PQC 対応が必要な理由
+
+PQC 対応の義務化を待つ理由はありません。今この瞬間も、ハーベスト攻撃（Harvest Now, Decrypt Later：暗号化通信を今傍受し、将来の量子コンピュータで解読する攻撃）によってデータは蓄積され続けています。
+
+過去に漏れたデータは取り返せませんが、これから先の通信は今日から守ることができます。`pqc_rails` は、既存の Rails アプリケーションに耐量子暗号を組み込み、この現在進行形のリスクに対処します。
+
+詳しい脅威モデルはこちら → [docs/THREAT_MODEL.md](docs/THREAT_MODEL.md)
+
+自組織のクリプト・インベントリに `pqc_rails` の利用箇所を記載する際の記入例はこちら → [docs/CRYPTO_INVENTORY.md](docs/CRYPTO_INVENTORY.md)
+
+## 現在の対応状況
+
+| 機能                          | 状態                                             |
+| ----------------------------- | ------------------------------------------------ |
+| KEM（鍵カプセル化機構）       | ✅ 対応済み（ML-KEM-512/768/1024 で動作確認）     |
+| DSA（署名アルゴリズム）       | ✅ 対応済み（ML-DSA-44/65/87 で動作確認）         |
+| セッション暗号化              | ✅ 対応済み（`PqcCookieStore`）                   |
+| ActiveRecord::Encryption 連携 | ✅ 対応済み（`PqcRails::Cipher` + `KeyProvider`） |
+| 鍵ローテーション              | ✅ 対応済み（セッション・DB 双方で旧鍵世代を併用可能。詳細は [docs/MIGRATION.md](docs/MIGRATION.md#鍵ローテーションpqc_rails鍵世代間)） |
+
+KEM と DSA に加え、セッション Cookie と ActiveRecord::Encryption の両方を ML-KEM ベースのハイブリッド暗号（KEM-DEM 構成）で保護します。liboqs がサポートする他のアルゴリズムも、アルゴリズム名を文字列で指定するだけで利用できます（liboqs 側のビルド設定に依存します）。
+
+## スコープ
+
+- **対象はアプリケーション層の暗号化**（セッション Cookie・DB カラム）です。TLS 通信路そのものの PQC 化（Web サーバ・ロードバランサ側の設定）は対象外です。Ruby / RubyGems エコシステム側でも標準ライブラリ全体を PQC 対応させる議論（[Ruby Feature #22068](https://bugs.ruby-lang.org/issues/22068)）が進んでいますが、これは輸送路の話であり、`pqc_rails` が担うアプリケーションデータの暗号化とはレイヤーが異なります。
+- **PKI・証明書管理基盤の代替ではありません**。鍵の発行・ライフサイクル管理・監査ログといった機能は提供しません。`pqc_rails` が担うのは Rails アプリ内のセッション・DB カラムの暗号化のみです。
+- **量子コンピュータそのものを使う暗号方式（QKD、量子署名など）は対象外です**。`pqc_rails` が提供するのは、古典コンピュータ上で動作し量子コンピュータに対して耐性を持つ暗号（PQC: Post-Quantum Cryptography）です。
+- **JWT/トークン署名は対象外です**。`PqcRails::Sig`（ML-DSA）はスタンドアロンの署名プリミティブとして提供していますが、セッション・DB統合と違いJWT等のトークンフォーマットへの統合は行っていません。この用途には [jwt-pq](https://rubygems.org/gems/jwt-pq) のような専用 gem を検討してください（`pqc_rails` とは別々の liboqs を読み込むため、併用しても競合しません）。
+
+より詳しい対応範囲・スコープ外は [docs/THREAT_MODEL.md](docs/THREAT_MODEL.md#for-developers) を参照してください。
+
+## 想定するユースケース
+
+長期保存が必要なデータを扱う Rails アプリケーション全般が対象ですが、特に以下のような用途では緊急度が高くなります。
+
+- 医療記録・法務文書など、10年20年単位で機密性が求められるデータを扱うアプリケーション
+- 金融・暗号資産関連のセッション管理や取引履歴を扱うアプリケーション（秘密鍵・取引データの窃取が量子コンピュータ実用化後に致命的な損失に直結するため）
+
+## 必要要件
+
+- Ruby >= 3.2.0
+- Rails >= 7.1
+- RubyGems / Bundler >= 4.0.16 を推奨（rubygems.org は X25519MLKEM768 + ML-DSA-65 によるハイブリッド TLS を提供しており、4.0.16 未満では `Gem::Request` / `Bundler::Fetcher` のクライアント証明書鍵種別が RSA に決め打ちされる不具合の影響を受けます）
+- [liboqs](https://github.com/open-quantum-safe/liboqs)（C ライブラリ）がビルド・インストール済みであること
+  - 本 gem は liboqs を同梱しません。事前に共有ライブラリ（`liboqs.dylib` / `liboqs.so`）をビルドし、システムに配置してください。
+
+## ⚠️ liboqs の成熟度について
+
+本 gem は [liboqs](https://github.com/open-quantum-safe/liboqs) を基盤としています。liboqs は [Open Quantum Safe (OQS)](https://openquantumsafe.org/) プロジェクトによって開発されている、NIST の耐量子暗号標準化プロジェクトに基づくアルゴリズム実装です。
+
+liboqs 自身の公式ドキュメントでは、以下の点が明記されています：
+
+- liboqs は研究・プロトタイピングを目的としており、**本番環境や機密データの保護に依存することは現時点では推奨されていません**
+- セキュリティバグを避けるための最善の努力はされていますが、本番投入に必要な水準の監査・分析はまだ実施されていません
+
+`pqc_rails` は liboqs を「正しく安全に呼び出す」ことに責任を持ちますが、liboqs 自体の暗号実装の正しさ・安全性を保証するものではありません。本番環境への導入を検討される際は、上記の liboqs の現状を踏まえ、利用するシステムの重要度に応じたリスク評価を行ってください。
+
+NIST 標準化アルゴリズム自体（ML-KEM, ML-DSA など）は確定した仕様ですが、その「実装」の成熟度は今後も liboqs 側の改善とともに変わっていく可能性があります。
+
+## インストール
+
+Gemfile に以下を追記:
+
+```ruby
+gem "pqc_rails"
+```
+
+その後:
+
+```bash
+bundle install
+rails generate pqc_rails:install
+```
+
+ジェネレータが `config/initializers/pqc_rails.rb` を生成し、セッション用・DB 用の鍵を Rails credentials に書き込みます。
+
+## 設定
+
+### liboqs ライブラリパス
+
+liboqs の共有ライブラリへのパスを指定します。未設定の場合、環境変数 `LIBOQS_PATH`、それも無ければ OS ごとの一般的な場所（macOS: `/usr/local/lib/liboqs.dylib`、Linux: `/usr/local/lib/liboqs.so`）を仮定します。
+
+```ruby
+# config/initializers/pqc_rails.rb
+PqcRails.configure do |config|
+  config.liboqs_path = "/usr/local/lib/liboqs.dylib"
+end
+```
+
+### セッション暗号化
+
+```ruby
+# config/application.rb
+config.session_store :pqc_cookie_store
+```
+
+Rails の `cookie_store` を ML-KEM ベースの PQC ストアで完全に置き換えます。既存のセッションは切り替え時に無効化されます（全ユーザーが再ログインになります）。
+
+鍵は Rails credentials の `pqc_session_key` から読み込みます。環境変数 `PQC_SESSION_KEY` で上書き可能です。
+
+#### Cookie サイズについて
+
+`HybridKem` の ciphertext を含むため、Cookie は Rails 標準（AES-256-GCM）より大きくなります。実測値（開発機、単純なセッション内容での計測）は次の通りです。
+
+| 内容                          | pqc_rails（ML-KEM-768、デフォルト） | Rails 標準 |
+| ----------------------------- | ------------------------------------ | ---------- |
+| 空セッション                   | 約1,770 bytes                        | 約170 bytes |
+| `user_id` + CSRF トークン程度 | 約1,850 bytes                        | 約260 bytes |
+
+単一 Cookie の上限（多くのブラウザで4,096 bytes）には収まりますが、他の Cookie（analytics・A/B テスト用等）と合算されるリクエストヘッダ全体の上限（多くのサーバ/プロキシで8KB前後）には注意してください。
+
+より小さいサイズが必要な場合、`pq_alg_name: :ml_kem_512` を指定するとサイズを抑えられます（NIST セキュリティレベルは768の「レベル3」から512の「レベル1」に下がります）。
+
+```ruby
+config.session_store :pqc_cookie_store, pq_alg_name: :ml_kem_512
+```
+
+### ActiveRecord::Encryption
+
+```ruby
+# config/initializers/pqc_rails.rb
+PqcRails::ActiveRecord::Context.install!
+```
+
+```ruby
+# モデル
+class User < ApplicationRecord
+  encrypts :email, :phone_number
+end
+```
+
+`ActiveRecord::Encryption` の Cipher と KeyProvider を ML-KEM ベースの実装に置き換えます。新規導入の場合はそのまま利用できます。既存の ActiveRecord::Encryption（Rails デフォルト）で暗号化済みのデータがある場合、切り替え後はデフォルトでは復号できなくなります。一括での再暗号化が難しい場合は、Rails 標準の `previous:` スキーム機構を使って段階移行できます → [docs/MIGRATION.md](docs/MIGRATION.md)
+
+鍵は Rails credentials の `pqc_record_key` から読み込みます。環境変数 `PQC_RECORD_KEY` で上書き可能です。セッション用の鍵とは別管理です。
+
+## 使い方
+
+### アルゴリズムの指定方法
+
+`PqcRails::Kem` / `PqcRails::Sig` は、liboqs の生のアルゴリズム名文字列（`"ML-KEM-512"` 等）に加えて、シンボル（`:ml_kem_512` 等）でも指定できます。シンボルは `PqcRails::Algorithms` レジストリ経由で liboqs 名に解決されます。
+
+```ruby
+PqcRails::Kem.new(:ml_kem_512)   # シンボル指定（推奨）
+PqcRails::Kem.new("ML-KEM-512")  # liboqs の生の名前を直接指定
+```
+
+現在レジストリに登録済みのアルゴリズム：
+
+| 種別 | シンボル                                       | NIST セキュリティレベル |
+| ---- | ---------------------------------------------- | ----------------------- |
+| KEM  | `:ml_kem_512` / `:ml_kem_768` / `:ml_kem_1024` | 1 / 3 / 5               |
+| SIG  | `:ml_dsa_44` / `:ml_dsa_65` / `:ml_dsa_87`     | 2 / 3 / 5               |
+
+未登録のシンボルを渡すと `PqcRails::Algorithms::UnknownAlgorithmError`（`PqcRails::Error` のサブクラス）が発生します。
+
+このレジストリ経由の解決方式により、アプリケーションコードは liboqs の生の名前や個々のアルゴリズムの実装詳細に直接依存しません。将来 NIST 標準の追加・非推奨化や liboqs 側の命名変更があっても、レジストリ側の対応表を更新するだけで済みます。これはクリプトグラフィック・アジリティ（暗号アルゴリズムを迅速に切り替えられる性質）の実装例で、金融庁「預金取扱金融機関の耐量子計算機暗号への対応に関する検討会 報告書」が具体的な実現方法として挙げる「メインルーチンでは抽象化した暗号機能の呼び出しに留め、具体的なアルゴリズム・パラメータによる処理を分離しておく」という設計パターンに沿っています。
+
+#### レジストリ未登録のアルゴリズムを使う（例: Classic McEliece）
+
+シンボルレジストリに無いアルゴリズムでも、liboqs 側でビルドされていれば liboqs の生の名前を文字列で渡すことで利用できます。例えば符号ベース暗号の Classic McEliece（[ISO/IEC 18033-2:2006/Amd 2:2026](https://www.iso.org/standard/86890.html) として標準化済み）は次のように使えます。
+
+```ruby
+PqcRails::Kem.open("Classic-McEliece-348864") do |kem|
+  keypair = kem.generate_keypair
+  keypair.public_key.bytesize # => 261120（約255KB。ML-KEM-512の800バイトと比べ大幅に大きい）
+end
+```
+
+公開鍵サイズが大きい（348864 パラメータセットで約255KB）ため TLS ハンドシェイクのような頻繁な鍵交換には向きませんが、鍵交換の頻度が低い長期保存データの暗号化では ML-KEM が万一破られた場合のバックアップとして選択肢になります。異なる数学的困難性（符号の復号問題）に安全性の根拠を置くため、ML-KEM（格子問題）とは異なるリスクプロファイルを持ちます。
+
+同様に、NIST が ML-KEM のバックアップとして選定した符号ベースKEM「HQC」も liboqs 0.16.0 以降ではデフォルトで有効化されており、生の名前（`"HQC-1"` / `"HQC-3"` / `"HQC-5"`）を渡すことで利用できます。ただしHQCはまだNIST標準化作業中（FIPS番号未確定）のため、シンボルレジストリには未登録です。
+
+```ruby
+PqcRails::Kem.open("HQC-1") do |kem|
+  keypair = kem.generate_keypair
+  keypair.public_key.bytesize # => 2241
+end
+```
+
+### 鍵交換（KEM）の基本フロー
+
+```ruby
+PqcRails::Kem.open("ML-KEM-512") do |kem|
+  # 受信側: 鍵ペアを生成
+  keypair = kem.generate_keypair
+
+  # 送信側: 受信側の公開鍵から共有秘密と ciphertext を生成
+  encapsulation = kem.encapsulate(keypair.public_key)
+
+  # 受信側: ciphertext と自分の秘密鍵から共有秘密を復元
+  shared_secret = kem.decapsulate(encapsulation.ciphertext, keypair.secret_key)
+
+  shared_secret == encapsulation.shared_secret # => true
+end
+```
+
+`PqcRails::Kem.open` はブロックを抜けると自動的にネイティブメモリを解放します。手動でリソースを管理したい場合は `new` / `free` を直接使うこともできます。
+
+```ruby
+kem = PqcRails::Kem.new("ML-KEM-512")
+# ...
+kem.free
+```
+
+#### 鍵長の参照
+
+```ruby
+kem = PqcRails::Kem.new("ML-KEM-512")
+kem.length_public_key    # => 800
+kem.length_secret_key    # => 1632
+kem.length_ciphertext    # => 768
+kem.length_shared_secret # => 32
+```
+
+### 署名（DSA）の基本フロー
+
+```ruby
+PqcRails::Sig.open("ML-DSA-44") do |sig|
+  # 署名者: 鍵ペアを生成
+  keypair = sig.generate_keypair
+
+  # 署名者: メッセージに署名
+  signature = sig.sign("hello world", keypair.secret_key)
+
+  # 検証者: 署名を検証
+  sig.verify("hello world", signature, keypair.public_key) # => true
+end
+```
+
+`verify` は、署名が無効な場合に例外を発生させず `false` を返します（liboqs の `OQS_SIG_verify` の挙動に準拠）。
+
+```ruby
+sig.verify("tampered message", signature, keypair.public_key) # => false
+```
+
+`PqcRails::Sig` も `PqcRails::Kem` と同様、`open` によるブロック形式と `new` / `free` による手動管理の両方をサポートしています。
+
+#### 鍵長・署名長の参照
+
+```ruby
+sig = PqcRails::Sig.new("ML-DSA-44")
+sig.length_public_key # => 1312
+sig.length_secret_key # => 2560
+sig.length_signature  # => 2420（最大長。実際の署名はこれより短いことがあります）
+```
+
+## エラーハンドリング
+
+- 未知のアルゴリズム名や、liboqs が有効化していないアルゴリズムを指定すると `PqcRails::Error` が発生します。
+- `encapsulate` / `decapsulate` / `sign` に渡すバイト列の長さが不正な場合は `ArgumentError` が発生します。
+- `free` 済みのインスタンスに対する操作は `PqcRails::Error` が発生します。
+- `PqcRails::Sig#verify` は、署名が無効な場合でも例外を発生させず `false` を返します（KEM とは異なる設計です）。
+- `ActiveRecord::Encryption` で復号に失敗した場合は `ActiveRecord::Encryption::Errors::Decryption` が発生します。
+- セッション Cookie が不正・改竄されている場合は空のセッションとして扱います（クラッシュしません）。
+
+## 動作確認済み環境
+
+- Ruby 3.2 / 3.3 / 3.4
+- Rails 7.1 / 8.1
+- liboqs 0.15.0 / 0.16.0
+
+[CI](.github/workflows/test.yml) では Ruby 3.4 + Rails 8.1 + liboqs 0.15.0 の組み合わせを push・PR のたびに継続的に検証しています。liboqs 0.16.0、および他の Ruby/Rails バージョンの組み合わせは手動で動作確認済みです（CIのマトリクス化は今後の対応予定）。
+
+## 開発
+
+```bash
+bin/setup
+bundle exec rspec
+```
+
+## ライセンス
+
+[Business Source License 1.1 (BSL)](LICENSE.txt) を採用しています。
+
+- ソースコードは公開し、開発・検証・非商用利用は無料です
+- 商用利用（対価を得る用途、または営利企業が事業活動の一環として使う用途）には別途ライセンス契約が必要です
+- 各バージョンのリリースから4年後、自動的にオープンソースライセンス（Apache License 2.0）に移行します
+
+詳細な条件は [LICENSE.txt](LICENSE.txt) を参照してください。商用利用に関するお問い合わせは contact@rubyquantum.dev までご連絡ください。
+
+商用利用の判定基準（Additional Use Grant の文言）は、正式な法律レビューを経る前の暫定版です。実際に商用ライセンス契約を結ぶ段階までに見直す可能性があります。
+
+## コントリビューション
+
+Issue・Pull Request は [GitHub](https://github.com/mabutast/pqc_rails) で受け付けています。

data/Rakefile

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+task default: %i[]

data/docs/CRYPTO_INVENTORY.md

@@ -0,0 +1,47 @@
+# クリプト・インベントリ テンプレート
+
+クリプト・インベントリとは、組織内で利用している暗号モジュールや暗号方式の一覧です。PQCへの移行を計画する際、まず「どこで・何のために・どの暗号方式を使っているか」を把握することが出発点になります。金融庁「預金取扱金融機関の耐量子計算機暗号への対応に関する検討会 報告書」(2024年11月)は、この構築を移行準備の柱の一つとして挙げています。
+
+このドキュメントは、`pqc_rails` を導入したアプリケーションが、自組織のクリプト・インベントリに `pqc_rails` の利用箇所をどう記載すればよいかの記入例です。実際の値はアプリケーションの設定(鍵管理方法、DB暗号化対象カラム等)によって変わるため、記入例を出発点に、自組織の実際の設定に置き換えて利用してください。
+
+## 記入項目と pqc_rails の記入例
+
+| 項目 | 内容 |
+| --- | --- |
+| **スコープ** | 自組織開発のシステム、または自組織外から提供されたgem・製品(`pqc_rails` はこちらに該当) |
+| **暗号利用場面** | セッションCookieの暗号化(`PqcCookieStore` 経由)。ActiveRecordモデルの特定カラムの暗号化(`encrypts` 宣言経由) |
+| **暗号用途** | セッション: ユーザーとの通信内容(セッションデータ)の保護。DBカラム: お客様情報を安全に保存するため |
+| **暗号実装箇所** | 自組織外から提供された製品(gem `pqc_rails`)。内部では [liboqs](https://github.com/open-quantum-safe/liboqs) へのFFIバインディングを経由 |
+| **利用アルゴリズム** | 鍵交換: ML-KEM(NIST FIPS 203) + X25519のハイブリッド構成(`HybridKem`)。データ本体: AES-256-GCM(`EnvelopeCipher`)。デフォルトパラメータセットは ML-KEM-768 |
+| **利用している暗号鍵長** | ML-KEM-768: 公開鍵1184バイト / 秘密鍵2400バイト / 暗号文1088バイト / 共有鍵32バイト。AES-256-GCM: 256ビット鍵 |
+| **暗号鍵の更新頻度** | 現時点では鍵ローテーション(複数世代の鍵の切り替え)は未対応です。単一世代の鍵を使い続ける構成のため、鍵を更新する場合は再暗号化が必要になります |
+| **暗号鍵管理方法** | Rails credentials(`pqc_session_key` / `pqc_record_key`)、または環境変数(`PQC_SESSION_KEY` / `PQC_RECORD_KEY`)。セッション用とDB用で鍵は分離されています。HSM・クラウドKMSとの統合は現時点で未対応です |
+| **長期保護データとの接点有無** | セッションCookieは通常ログインセッション程度の短期間ですが、DBカラムに保存するデータの保護期間はアプリケーションの用途に依存します。医療記録・法務文書・金融取引データ等、長期保護が必要なデータをこの経路で扱う場合は、[THREAT_MODEL.md](THREAT_MODEL.md#どのデータが危険か) のX+Y>Zフレームワークで緊急度を評価してください |
+
+## 収集方法
+
+`pqc_rails` の利用箇所そのものは、以下の方法で機械的に洗い出せます。
+
+- `config/application.rb` の `config.session_store :pqc_cookie_store` の有無(セッション暗号化の利用有無)
+- `config/initializers/pqc_rails.rb` の `PqcRails::ActiveRecord::Context.install!` の有無(DBカラム暗号化の利用有無)
+- 各モデルの `encrypts :カラム名` 宣言(暗号化対象カラムの特定)
+
+これらはコード解析ツール(`grep -rn "encrypts \|pqc_cookie_store\|Context.install"` 等)で機械的に検出可能です。
+
+## 自組織用の記入欄(空欄テンプレート)
+
+| 項目 | 記入欄 |
+| --- | --- |
+| スコープ | |
+| 暗号利用場面 | |
+| 暗号用途 | |
+| 暗号実装箇所 | |
+| 利用アルゴリズム | |
+| 利用している暗号鍵長 | |
+| 暗号鍵の更新頻度 | |
+| 暗号鍵管理方法 | |
+| 長期保護データとの接点有無 | |
+
+## 参考
+
+- [金融庁「預金取扱金融機関の耐量子計算機暗号への対応に関する検討会 報告書」](https://www.fsa.go.jp/singi/pqc/houkokusyo.pdf)(表5.1「クリプト・インベントリの構成例」を参考に項目を選定)

data/docs/MIGRATION.md

@@ -0,0 +1,107 @@
+# 既存データの移行（Dual-Stack）
+
+`PqcRails::ActiveRecord::Context.install!` は `ActiveRecord::Encryption` のグローバル設定（cipher・key_provider）を置き換えます。既に Rails 標準の `ActiveRecord::Encryption`（AES-256-GCM + 導出鍵）で暗号化済みのデータがある場合、切り替え後はデフォルトでは復号できません。
+
+一括で全レコードを再暗号化できない場合は、Rails 標準の `previous:` スキーム機構を使って段階移行できます。新しい書き込みは `pqc_rails` で暗号化しつつ、既存データは旧方式のまま読み出せる状態にする方法です。
+
+## 設定
+
+```ruby
+class User < ApplicationRecord
+  encrypts :email, previous: [
+    {
+      cipher: ActiveRecord::Encryption::Cipher.new,
+      key_provider: ActiveRecord::Encryption::DerivedSecretKeyProvider.new(OLD_PRIMARY_KEY)
+    }
+  ]
+end
+```
+
+- `OLD_PRIMARY_KEY` は、`pqc_rails` 導入前に使っていた `Rails.application.credentials.active_record_encryption.primary_key`（または `config.active_record.encryption.primary_key`）の値です。credentials から削除する前に控えておいてください。
+- `cipher:` に Rails 標準の `ActiveRecord::Encryption::Cipher.new` を明示的に指定するのが要点です。`previous:` は `key_provider:` だけでなく `cipher:` も含めた実行コンテキストをまるごと差し替えるため、暗号化アルゴリズム自体が異なる pqc_rails 導入前後のデータを同じ属性宣言で両方読めるようになります。
+
+## 動作
+
+| 操作 | 挙動 |
+| --- | --- |
+| 新規レコードの書き込み | 現在の設定（`Context.install!` 後の pqc_rails の Cipher + KeyProvider）で暗号化される |
+| pqc_rails 導入後に書き込まれたレコードの読み出し | 現在の設定でそのまま復号される |
+| pqc_rails 導入前に書き込まれたレコードの読み出し | 現在の設定での復号に失敗すると、`previous:` に列挙したスキームを順番に試し、旧方式（AES-256-GCM + 導出鍵）で復号される |
+
+読み出しのたびに現在の設定→`previous:`の順で試行するため、`previous:` に列挙するスキームが増えるほど、失敗した場合の復号コストが増える点には注意してください。移行が完了し旧方式のデータが残っていないことを確認できたら、`previous:` オプションと `OLD_PRIMARY_KEY` は削除して構いません。
+
+## 一括再暗号化したい場合
+
+段階移行ではなく一括で再暗号化したい場合は、Rails 標準の `bin/rails db:encryption:init` 相当の仕組みは pqc_rails には無いため、対象モデルの全レコードを読み出して `save!` するマイグレーションタスクを自前で用意してください（読み出し時に上記の `previous:` 機構で旧データが復号され、書き込み時には現在の設定＝pqc_rails で再暗号化されます）。
+
+## 鍵ローテーション（pqc_rails鍵世代間）
+
+上記の `previous:` は「pqc_rails 導入前の暗号方式」からの移行を扱いますが、ここで扱うのは「pqc_rails 導入後、鍵そのものを世代交代させたい」場合の手順です。セッション・DB のどちらも、現行鍵に加えて旧鍵世代を併用できます。
+
+### DB（ActiveRecord::Encryption）
+
+`PqcRails::ActiveRecord::KeyProvider#decryption_keys` は、現行鍵に続けて旧鍵世代を返します。ローテーションの手順は次の通りです。
+
+1. 新しい鍵ペアを生成し、`PQC_RECORD_KEY`（または `pqc_record_key` credentials）に設定する
+2. 元々 `PQC_RECORD_KEY` に設定していた値を `PQC_RECORD_PREVIOUS_KEYS`（または `pqc_record_previous_keys` credentials）に移す
+3. アプリを再起動する。新規の暗号化は新しい鍵で行われ、旧鍵で暗号化済みのレコードもそのまま復号できる
+4. 旧鍵で暗号化されたレコードが残っている間は `PQC_RECORD_PREVIOUS_KEYS` を維持する。全レコードを新しい鍵で再暗号化し終えたら（上記「一括再暗号化したい場合」の手順を新旧鍵の組で実行）、`PQC_RECORD_PREVIOUS_KEYS` を削除してよい
+
+`PQC_RECORD_PREVIOUS_KEYS` は複数の旧鍵をカンマ区切りで指定できます（credentials の場合は配列）。世代数に上限はありません。
+
+### セッション（PqcCookieStore）
+
+`PqcCookieStore` は書き込み（`set_cookie`）には常に現行鍵のみを使い、読み込み（`get_cookie`）は現行鍵で復号できなかった場合に旧鍵世代を順に試します。手順は DB 側と同様に `PQC_SESSION_KEY` / `PQC_SESSION_PREVIOUS_KEYS`（または `pqc_session_key` / `pqc_session_previous_keys` credentials）を使います。
+
+セッションは DB のレコードと異なり、Cookie の有効期限（`expire_after` 等）が過ぎれば自然に失効します。そのため `PQC_SESSION_PREVIOUS_KEYS` は「ローテーション後、旧鍵で発行されたセッションが有効期限切れになるまで」の一時的な設定として運用し、その期間を過ぎたら削除してください（DB側のような一括再暗号化の手順は不要です）。
+
+### 外部鍵ソース（HSM等）への差し替えについて
+
+鍵の取得元は、デフォルトでは `PqcRails::KeySource::EnvCredentials`（ENV → Rails credentials）です。`#current_keypair` / `#previous_keypairs` の2メソッドを実装したオブジェクトであれば差し替えられます。
+
+- **DB側**: `PqcRails::ActiveRecord::KeyProvider.new(key_source: your_source)` のように、`Context.install!` に渡す `KeyProvider` へ直接注入できます。
+- **セッション側**: `PqcRails::Session::KeyManager` はモジュール実装のため同様の注入口はありませんが、`PqcCookieStore` は `keypair:` / `previous_keypairs:` オプションで実際の鍵ペアを直接受け取れます（`KeyManager` を経由しない）。外部鍵ソースから取得した鍵ペアをこのオプションに渡すことで、同様に差し替え可能です。
+
+将来 HSM/PKCS#11 経由の鍵管理と連携する場合の拡張ポイントとして用意していますが、pqc_rails 自体は具体的な HSM 連携実装を提供しません。
+
+## 鍵の紛失・災害復旧
+
+`PQC_RECORD_KEY` / `PQC_SESSION_KEY`（または対応する credentials）を紛失すると、その鍵で暗号化された DB カラム・セッション Cookie は二度と復号できません。pqc_rails 自体は鍵のエスクロー機能を持たず、liboqs にもその機能はないため、鍵のバックアップは利用者側の運用に完全に委ねられています。特に DB カラムは長期間残り続けるデータであるため、**鍵紛失イコールデータの永久喪失**に直結します。
+
+以下は推奨する運用です。
+
+- **Rails credentials 経由で鍵を管理する場合**：実質的な「鍵の鍵」は `config/master.key`（または `RAILS_MASTER_KEY`）です。`config/credentials.yml.enc` はリポジトリに含まれますが、`master.key` はバージョン管理から除外されるため、これ自体を通常のインフラ資産と同様のバックアップ体制（社内のシークレット管理システム、複数人でのオフライン保管等）に含めてください。
+- **環境変数（`PQC_RECORD_KEY` 等）経由で管理する場合**：値そのものを手動でファイルに控えるのではなく、AWS Secrets Manager・HashiCorp Vault・GCP Secret Manager 等のシークレットマネージャが提供するバージョニング・自動バックアップ機能を利用してください。
+- **定期的な復旧リハーサル**：バックアップした鍵が「存在すること」の確認だけでは不十分です。実際にその鍵をテスト環境へ復元し、既存の暗号化データを復号できることまで確認してください。バックアップ手順自体の欠陥（フォーマット破損、鍵の取り違え等）は、復旧を試みて初めて発覚します。
+- **鍵ローテーションを平常運用に組み込む**：上記の鍵ローテーション手順を定期的に実施することで、単一世代の鍵に依存し続ける期間そのものを短くできます。
+
+複数管理者による鍵の分散管理（Shamir's Secret Sharing 等による鍵分割）や鍵のエスクローが必要な場合、pqc_rails 自体はその機能を提供しないため、前述の外部鍵ソース差し替え機構を経由した HSM/KMS の利用を検討してください。
+
+## ロールバック手順（pqc_rails 導入前の状態に戻す）
+
+pqc_rails 導入後に、何らかの理由で導入前の状態へ戻す必要が生じた場合の手順です。
+
+### DB（ActiveRecord::Encryption）
+
+考え方は導入時の段階移行と対称です。`previous:` に pqc_rails 側のスキームを指定することで、新規の書き込みを Rails 標準方式に戻しつつ、pqc_rails で暗号化済みのデータも読み出せる状態にします。
+
+```ruby
+class User < ApplicationRecord
+  encrypts :email, previous: [
+    {
+      cipher: PqcRails::Cipher.new,
+      key_provider: PqcRails::ActiveRecord::KeyProvider.new
+    }
+  ]
+end
+```
+
+- `Context.install!` の呼び出し自体を削除（または呼ばない状態に戻す）することで、新規の暗号化は Rails 標準（AES-256-GCM + 導出鍵）に戻ります。
+- 完全に pqc_rails 以前の状態へ戻したい場合は、上記「一括再暗号化したい場合」と同じ要領で全レコードを読み出して `save!` し、Rails 標準方式で再暗号化してください。
+- 移行が完了し pqc_rails 方式のデータが残っていないことを確認できるまで、`PQC_RECORD_KEY`（または `pqc_record_key` credentials）は削除しないでください。
+
+### セッション（PqcCookieStore）
+
+セッションには DB のような「既存データを段階的に読み替える」仕組みはそもそも必要ありません。セッション Cookie は元々 `expire_after` 等で有効期限が切れる一時的なデータであるためです。
+
+`config.session_store` を `:pqc_cookie_store` から `:cookie_store`（Rails 標準）へ戻すだけでロールバックは完了しますが、これは導入時の移行と同様に**その時点で有効な全セッションが無効化される（全ユーザーが再ログインになる）**ことを意味します。これは不具合ではなく、導入時と対称な想定内の挙動です。段階的にロールバックしたい場合の仕組み（旧方式との併用）は現時点では提供していません。