Designing Rust APIs around KEM, AEAD and key derivation workflows

Designing Rust APIs around KEM, AEAD and key derivation workflows

現在のプロジェクトステータス（2026-10-28確認済み）： NEXUS-Q v4.1.2 が現在のリリースです。プロダクションレディネスの主張なし、FIPS認証なし、外部監査保留中。レジストリの利用可能性とリリースプロビナンスは別途文書化されています。Goモジュールは独立したv0.xバージョンを維持しています。ネイティブML-KEM/ML-DSAバックエンドは実験的でオプトインのままです。RustCryptoがデフォルトのパスです。

v4.1.2 リリースステータス（2026-10-28）： 監査準備完了リリース。プロダクションレディネスの主張なし、FIPS認証なし、外部監査保留中。 リリース証拠と制限事項は docs/V4_RELEASE.md に文書化されています。レジストリの利用可能性は、各エコシステムパッケージのビルドプロビナンスの証明ではありません。

クイックナビゲーション

プロジェクト概要

機能と成熟度マトリックス

これはクイックオリエンテーションであり、モジュールごとのドキュメントやリリースプロビナンスの代わりにはなりません。「利用可能」とは、リポジトリに実装されたパスがあることを意味し、独立した監査や認証を意味するものではありません。

セキュリティモデル概要

モジュールとSDK

リポジトリは、暗号コアをインターフェース、オプションサービス、言語バインディングから分離しています。これらの名前はリポジトリコンポーネントを説明するものであり、すべてのパッケージが同一の成熟度、プラットフォームサポート、またはリリースプロビナンスを持つことを主張するものではありません。必要なパッケージとターゲットを確認するには、インストールテーブルと各バインディング固有のドキュメントを使用してください。

リポジトリには、アーキテクチャフロー、プロジェクト概要、ベンチマーク比較のビジュアルアセットが既に含まれています。ベンチマークビジュアルは文書化された測定値に基づいています。グラフィックを単独のパフォーマンス保証として扱うのではなく、関連するテーブルと実行固有の注記を参照してください。

［画像: 5 Rust crates, 5 SDK languages, 8 Arena implementations, 57 measurements］

［画像: Overview］

Overview

NEXUS-Qは、以下の保護を目的としたポスト量子暗号セキュリティエンジンです。

アプリケーションおよびサーバー向けの暗号化/セキュリティエンジンとして意図されています。リポジトリは、将来のTPM、HSM、セキュアエレメント、エンクレーブ、RISC-V統合のためのハードウェアプロバイダー抽象化ポイントも定義しています。デフォルトのソフトウェアバックエンド自体はハードウェア分離を提供しません。

［画像: How it works］

［画像: Unlock the vault, manage keys, encrypt or sign, enforce policy, audit everything］

すべての操作は同じビルディングブロックを通過します：パスワードで暗号化されたボールト（フォーマットF-01、アトミック書き込み）をアンロックし、キーはフルライフサイクルを通じて管理され、データはエンベロープ暗号化（フォーマットF-02）で保護され、デフォルト拒否ポリシーエンジンがアクションをゲートし、セキュリティ関連イベントはHMAC認証付き監査ログに記録され、ロールバックアンカリングが行われます。

［画像: Design principles］

1. 暗号化を発明しない。 標準化されたアルゴリズムと保守されている暗号ライブラリのみを使用。依存関係の監査ステータスは明示的に文書化されています。
2. ライブラリファースト。 コアはRustライブラリであり、CLI、SDK、サーバーはそれらをラップするレイヤーです。
3. ハードウェアに依存しない境界。 ハードウェアプロバイダーインターフェースはソフトウェアバックエンドから分離されています。具体的なハードウェア分離は、プロバイダーが実装されテストされた場合にのみ主張されます。
4. ゼロ化。 不要になった秘密情報はメモリから消去されます。
5. 監査可能性。 監査可能なセキュリティ状態の変更と暗号アクションは、改ざん防止、HMAC認証付きログに記録されます。
6. ゼロからのセキュリティ。 コードの前に脅威モデルと暗号化ルール。

［画像: Repository layout］

現在の main ビルド要件： Rust 1.88 以降（edition 2024、現在の Cargo.toml MSRVに一致）および Git。公開されているパッケージは異なるソースプロビナンスとMSRVを持つ場合があります。古いツールチェーンをターゲットにする場合は、特定のパッケージメタデータをチェックしてください。追加のSDKツールチェーンは、特定のバインディング（C/C++、Python、Go、Ruby）をビルドする場合にのみ必要です。

ターゲットプラットフォーム： Linux (x86_64, aarch64); Android / Termux (aarch64); RISC-V (riscv64gc-unknown-linux-gnu)、ビルド検証済み; macOS および Windows のリリースビルドは V2 CI/リリースゲートによって検証されます。

［画像: Cryptography］

Cryptography

参照ドキュメントは docs/CRYPTOGRAPHY.md です。計画中のアルゴリズムは、実装およびテストされるまで利用可能として記述してはなりません。

［画像: Status］

Status

完了：

• 基盤ドキュメント、脅威モデル、暗号化ルール。
• 暗号コア：ML-KEM-768 (X25519とのハイブリッド)、AES-256-GCM、ChaCha20-Poly1305、Ed25519、SHA-2、SHA-3、Argon2id、HKDF。
• フルライフサイクルを持つキー管理。
• 暗号化ボールト（フォーマットF-01）とアトミック書き込み。
• エンベロープ暗号化（フォーマットF-02）。
• 署名、検証、ローテーション、失効、署名付きクレデンシャルを持つID。
• ソフトウェア、TPM、HSM、セキュアエレメント、RISC-Vのためのハードウェア抽象化トレイト。
• ヘルスチェックとミキシングを備えたTRNGサポート。
• RISC-Vへのクロスコンパイル検証済み。
• ストレージ：HMAC認証付き監査ログ（ロールバックアンカリング付き）、バックアップバンドル、ストレージDB。
• デフォルト拒否ポリシーエンジン。
• ボールト、キー、データ、署名、ID、クレデンシャル、監査コマンドをカバーするCLI。

［画像: Benchmarks］

Benchmarks

以下のベンチマークテーブルは、記録された測定値、過去の比較、および既知の注意点を意図的に保持しています。これらは実際のプロジェクトベンチマーク結果であり、例示的な数値ではありません。各データセットには独自のコンテキストがあります。ローカル診断、ホストランナーのリリースゲート、過去のアリーナ実行は、単一の管理された実験であるかのように比較されるべきではありません。

再現性とより完全なコンテキストのために、PQCベンチマークアリーナのドキュメント、ベンチマークインデックス、V4リリースノート、およびリンクされた実行ごとのCIアーティファクト/レポートから始めてください。ハードウェア、CPUガバナー、ランナー環境、サンプル数、ウォームアップ、比較バージョン、集計方法は重要です。レイテンシ比は操作固有であり、複合スコアはありません。低いレイテンシが良い結果であり、ベンチマークの合格はエンドツーエンドのアプリケーションパフォーマンスまたはセキュリティ認証の主張ではありません。

NEXUS-Qは普遍的なパフォーマンスリーダーとして提示されていません。2026-10-21のローカルx86-64ベンチマークでは、オプトインネイティブバックエンドは、一致するAWS-LC RNGを使用して、各操作で最も適した比較対象と比較されました。9つの操作のうち6つが中央値とp95の両方で比較対象を上回り、残りの3つは同等に近い結果でした：ML-DSA-65署名（中央値の1.063倍 / p95の1.115倍）、ML-KEM-1024キー生成（1.021倍 / 1.020倍）、およびML-KEM-768キー生成（1.015倍 / 1.013倍）。これは、CPUガバナーがpowersaveに設定されたIntel Core i3-N305からのローカル診断証拠であり、ホストランナーのリリースベンチマークや普遍的なパフォーマンスの主張ではありません。プロジェクトオーナーはこの結果をIssue #23 を完了するために十分とみなし、残りの差はdocs/performance/ISSUE_23_FINAL_GATE_AUDIT_2026-10-21.md に文書化されています。デフォルトのnexusq-coreビルド、CLI、SDKは引き続き本番呼び出しパスにRustCryptoを使用しています。ネイティブパスはオプトインおよび実験的です。低いレイテンシが良い結果です。

［画像: NEXUS-Q v4.1.0 (opt-in native backend) versus AWS-LC on nine ML-KEM and ML-DSA operations］

v4.1.0安定ライン、2026-10-19：マージされたv4.1.0コードでグリーンリリースCIから取得した、オプトインネイティブバックエンドとAWS-LCの公式1.5倍中央値およびp95本番パスゲート。各実装で3回の交互ラウンド、プールされた中央値と最も近いランクのp95、各操作あたり3,000サンプルをAMD EPYC 7763 CIランナーで実行。同じリリースからの完全なPQCベンチマークアリーナ実行（241の正規化された測定値、8つの比較対象とV1/V1+zeroize/V3コントロール）はCIアーティファクトとして保持されています。複合スコアなしで報告。

［画像: Measured median latency ratio for nine NEXUS-Q native-backend operations versus AWS-LC in the v4.1.0 hosted CI run; values below 1.0 mean lower NEXUS-Q median latency for that run］

v1.0 Arena baseline (historical)

v1ベースラインは、測定されたML-KEMおよびML-DSA操作において、最も高速な成熟した実装よりも遅かったです。そのギャップを埋めることがV4ラインの主要なエンジニアリングターゲットでした。

最終v1.0アリーナ実行、2026-10-05：同じx86_64 Linux CI環境で8つの実装からの57の正規化された測定値、各操作あたり20イテレーションと3回のウォームアップ。複合スコアなしで報告。比較対象：AWS-LC、Botan、CIRCL、liboqs、OpenSSL、PQ Code Package、およびRustCrypto KEM。生の測定値はCIアーティファクトとして保持されています。

V1 vs V2 (同じランナーでのアリーナ比較)

最終ベンチマーク記録は、V1に対するパフォーマンスの向上を主張していません。修正されたアリーナ実行では、V2/V1の幾何平均が0.885および1.0647513576となり、パフォーマンスは検証済みのリグレッションまたは改善ではなく、未解決の調査項目となっています。最新の同じランナーでの比較では、9つのNEXUS-Q操作全体でV2はV1と比較して+0.22%から+52.37%のレイテンシが測定されました。ML-DSA-65署名が主要な外れ値（+52.37%）です。

これらは、保持されているアリーナJSONLアーティファクトからの同じランナーでの参照測定値です。以前の修正された実行では0.885 V2/V1が測定され、実行ごとの大きなばらつきを示しています。したがって、V3は単一実行のリグレッションを仮定するのではなく、プロファイリングとベンチマークばらつきの調査から始まります。docs/V2_PERFORMANCE_RESULTS.md を参照してください。パフォーマンス調査は意図的にV3に延期されており、V2はベンチマーク結果を製造するために変更されていません。

V1 vs V3 (ペア調査)

ペア化されたV1/V3調査では、記録されたホストランナー実験において、6つの測定されたML-KEM操作全体で中央値が+2.70%から+6.33%増加しました。従来のML-DSA検証は+6.40%、キー生成は+6.82%、署名中央値は-0.76%でした。これらは単一CIランナーと10回のペアラウンドからの観測であり、普遍的なパフォーマンスの主張ではありません。BENCHMARKS.md および フォレンジックレポート を参照してください。

ML-DSAのみのゼロ化コントロールは、SHA3/SHAKEゼロ化がML-KEMレイテンシデルタの原因であることを証明しません。Issue #41は、明示的なプロジェクトの決定によりクローズされました。V1は速度を優先し、V3はセキュリティ強化を維持し、観測されたパフォーマンスコストを受け入れます。

V4.1.0安定ライン（アリーナ実行と本番パスゲート）

v4.1.0安定ラインリリースは、フルPQCベンチマークアリーナおよび公式1.5倍中央値およびp95本番パスゲートとともにmainで検証されました。両方ともリリースコードでグリーンです（ピン留めされたRust 1.85.1リリースツールチェーンのコンパイル修正PR #57 が着陸しました）。

アリーナ実行（2026-10-19、コミット 70152eb）： 同じubuntu-24.04 x86_64 CI環境で241の正規化された測定値、各操作あたり20イテレーションと3回のウォームアップ。比較対象：AWS-LC (ec05f25)、Botan 3.13.0、OpenSSL 3.5.9、CIRCL 1.6.4、RustCrypto KEMs、liboqs 0.16.0、PQ Code Package、および保持されているV1 / V1+zeroize / V3コントロール。生のJSONL測定値は、アリーナ実行のCIアーティファクト として保持されています。複合スコアなしで報告。

本番パスゲート（ネイティブバックエンド vs AWS-LC、各実装で3回の交互ラウンド、プールされた中央値と最も近いランクのp95、各操作あたり3,000サンプル）： 9つのすべての操作が、マージされたリリースコードで変更されていない1.5倍中央値およびp95ゲートをパスしました（ゲート実行）。

これらはAMD EPYC 7763ホストランナーでの単一ランナーCI測定値であり、普遍的なパフォーマンスの主張ではありません。ネイティブバックエンドは実験的でオプトインのままです。デフォルトのnexusq-coreビルド、CLI、SDKは引き続き本番呼び出しパスにRustCryptoを使用しています。docs/performance/NATIVE_BACKEND_FEATURE.md および docs/V4_RELEASE.md を参照してください。

［画像: Versions］

V3エンジニアリングリリースとV4スナップショット

V3は、ハード化された実装、再現可能なPQCベンチマークアリーナ、依存関係/プロファイル診断、修正されたベンチマークサンプリング、およびアーカイブされた証拠を統合します。そのGitHubリリースはエンジニアリングリリースであり、独立した監査、認証、またはレジストリ公開の主張ではありません。V1/V2/V3アーティファクトとチェックサムはartifact-archive/README.md にインデックスされています。

V4は現在v4-engineering-2026-10-16エンジニアリングタグで表され、mainに統合されています。ネイティブバックエンドとそのベンチマークハーネスが存在し、公式の1.5倍中央値およびp95ゲートはレビュー済みのCI証拠でパスしました。PR #55 は、明示的にオプトインされるnative-backendフィーチャーの背後でバックエンドをnexusq-coreに配線します。デフォルトビルドとすべてのSDKは引き続きRustCryptoを使用し、フィーチャーはどこでもデフォルトで有効になっておらず、本番パスベンチマークは変更されていない1.5倍中央値およびp95ゲートをパスしました。これは実験的なままであり、独立した監査は受けていません。フェーズ21の外部監査はまだ進行中です。以前のIssue #48トラッキングアイテムはクローズされました。そのチェックリストは、docs/performance/ の下にある過去のエンジニアリング証拠として保持されています。

V2.0.0およびV1.0ステータス

v2エンジニアリングラインは、バージョン2.0.0でnexusqv2にフリーズされています。V2はv1のセキュリティモデルを維持しつつ、完了したパフォーマンス、正確性/相互運用性、セキュリティ/ファジング、バックエンド戦略、およびリリースゲートを追加します。GitHub V2.0.0エンジニアリングリリースは過去のものであり、crates.io、PyPI、およびその他のSDKレジストリは個別の公開操作のままです。docs/V2_ROADMAP.md、docs/V2_RELEASE.md、およびdocs/V2_BENCHMARK_BASELINE.md を参照してください。

v1.0エンジニアリングベースラインは完了しており、意図的にフリーズされています。最終CI/アリーナ証拠は、正確性、セキュリティゲート、デプロイメント、ドキュメント、およびPQCパフォーマンスのための再現可能な参照ポイントを確立しました。v1ベースラインはパフォーマンスリーダーとして提示されておらず、サポートされていない本番認証または独立監査の主張も行われていません。外部レジストリ/パッケージ公開は意図的に延期されています。BENCHMARKS.md および docs/ROADMAP.md を参照してください。

［画像: Quick start］

Quick start

リポジトリのルートから、Rust 1.88+がインストールされている状態で：

# ワークスペースをビルド
cargo build --workspace --release

# ボールトを作成して検査
./target/release/nexusq vault create ./example.nqv
./target/release/nexusq vault status ./example.nqv
./target/release/nexusq health

# 署名キーを生成（パスワードを直接入力するよりも --password-file を推奨）
./target/release/nexusq key generate ./example.nqv --algorithm ed25519 --purpose sign --password-file ./password.txt

# データの暗号化と復号
./target/release/nexusq data encrypt ./example.nqv --key-id <key-id> ./secret.txt
./target/release/nexusq data decrypt ./example.nqv ./secret.txt.nqx ./secret.out

password.txt は秘密情報として扱ってください。権限を制限し、決してコミットしないでください。開発中は、cargo build および cargo test は通常通り機能し、CLIバイナリは target/debug/nexusq にあります。RISC-V用にビルドするには、docs/CROSS_COMPILE.md を参照してください。上記の署名キーの例は明示的にEd25519（ポスト量子ではない古典的アルゴリズム）を使用しています。CLIでサポートされているアルゴリズムについては、docs/user/CLI.md を参照してください。ライブラリレベルのML-KEM/ML-DSA操作すべてが同じCLIワークフローで公開されているとは限りません。コマンドはオリエンテーション用です。まずパスワードファイルと入力ファイルを作成し、キー生成時に表示される実際のキーIDを<key-id>に置き換えてください。

リリースデプロイメント：

cargo build --workspace --release
./deploy/package-release.sh

生成されたアーカイブには、CLI、サーバー、非秘密設定例、デプロイメントドキュメント、およびSHA-256マニフェストが含まれています。本番トークン、ボールト、秘密キー、またはログは含まれていません。サーバーのインストールと操作については、docs/DEPLOYMENT.md および docs/SERVER.md を参照してください。

Installation

NEXUS-Q v4.1.2 は現在の監査準備完了リリースです。以下のテーブルは、インストールターゲットと最新の公開パッケージバージョンを示しています。Goモジュールと実験的なネイティブバックエンドは独立したバージョンラインを維持しています。v4.1.1でリストされている補助的なRustクレートは、その安定した公開バージョンで引き続き利用可能です。このリリースはドキュメント変更のみを含み、新しいクレートバージョンを必要としなかったため、v4.1.2として再公開されませんでした。これは意図的なものであり、利用可能性のエラーではありません。レジストリの利用可能性は、すべてのエコシステムに対するビルドプロビナンスを証明するものではありません。以前のv4.1.1プロビナンスの注意点は過去のものとして文書化されています。

Maven座標

以下の座標が公開されており、直接使用できます：

<dependency>
  <groupId>io.github.lecodev-26</groupId>
  <artifactId>nexusq</artifactId>
  <version>4.1.2</version>
</dependency>

// Gradle Kotlin DSL
implementation("io.github.lecodev-26:nexusq:4.1.2")
implementation("io.github.lecodev-26:nexusq-kotlin:4.1.2")

ネイティブランタイムに関する注記

• Go、PHP、Ruby、TypeScript、Java (JNA)、Kotlin (JNA)、Dartバインディングは、C SDK (libnexusq) の薄いFFIラッパーです。言語固有のセットアップ手順をbindings/およびdocs/NATIVE_RUNTIME_PACKAGING.mdで確認してください。プラットフォームサポートと自動ランタイムダウンロードの動作は、SDKによって異なります。
• Pythonパッケージは、crates/nexusq-py (PyO3) からビルドされたネイティブ拡張モジュールです。PyPI 4.1.2のアップロードには、現在プラットフォームホイールではなくsdistが含まれています。
• C#/.NETバインディングはP/Invokeを使用し、SwiftバインディングはSwift Package Managerシステムライブラリターゲットを介してC SDKをリンクします。ネイティブライブラリが関連するバインディングドキュメントに記載されているように利用可能であることを確認してください。
• C SDKはCおよびC++から直接利用可能です。ソースからcargo build -p nexusq-c --releaseでビルドするか、C SDKパッケージを使用してください。
• GitHubリリースアーカイブには、CLI/サーバーとネイティブランタイムアセットが含まれています。これはC SDK開発ヘッダーをインストールする代わりにはなりません。
• レジストリの利用可能性は配布チャネルであり、セキュリティ検証の主張ではありません。セキュリティと保証のセクションを参照してください。

［画像: Documentation］

Documentation

ユーザー向けドキュメントはdocs/user/README.mdから始まり、タスク指向のはじめにガイド、インストール手順、CLIガイド、SDKガイド、およびトラブルシューティングガイドがあります。技術およびリファレンスドキュメントはdocs/にあります：

［画像: Benchmark Arena］

［画像: Security and assurance］

Security and assurance

V1～V4はエンジニアリングバージョンライン/スナップショットであり、本番レディネスの証明ではありません。GitHubリリースは、独立したセキュリティ監査、認証、FIPS検証、または本番レディネスを意味するものではありません。これはレジストリ公開にも当てはまります。レジストリ公開は配布チャネルであり、検証の主張ではありません。V4ネイティブバックエンドは実験的でオプトインのままです。nexusq-coreにnative-backendフィーチャーの背後で配線されていますが、コア、CLI、サーバー、またはSDKではデフォルトで有効になっていません。パフォーマンスゲートの結果は、ベンチマークされたバックエンドに適用され、エンドツーエンドのアプリケーションパフォーマンスの主張として読み取られるべきではありません。検証ステートメントに依存する前に、現在のmain CIを確認してください。

疑わしい脆弱性は、GitHub Security Advisories を通じてプライベートに報告してください。SECURITY.md を参照してください。

Contributing

イシュー、再現可能なバグレポート、ドキュメント改善、および的を絞ったプルリクエストを歓迎します。変更を送信する前に：

1. 変更に関連するアーキテクチャ、脅威モデル、暗号化ルール、およびセキュリティポリシーを読んでください。

2. 暗号化プリミティブは確立されたライブラリに委任してください。自作の暗号化を導入したり、シリアル化されたフォーマットをサイレントに変更したりしないでください。

3. 動作変更と並行して、テストとドキュメントを追加または更新してください。パフォーマンス作業については、再現可能な測定値を含め、ベンチマーク条件と生の証拠を保持してください。

4. 送信前に、関連するローカルチェックを実行してください。Rustの変更に対する有用なベースラインは次のとおりです：

   cargo fmt --all -- --check
   cargo test --workspace
   cargo build --workspace --release
   

   変更したクレートおよびSDKに適用されるチェックを実行してください。CIは、サポートされている完全なマトリックスの権威あるチェックであり続けます。

5. プルリクエストでは、セキュリティに影響する変更と互換性に関する影響を明確に記述してください。秘密情報、秘密キー、ボールトの内容、本番認証情報、または機密ログを絶対に含めないでください。

疑わしい脆弱性は、公開されたイシューで悪用可能な詳細を公開するのではなく、SECURITY.md のプロセスを使用してプライベートに報告してください。

［画像: License］

License

MITライセンス または Apache License 2.0 のいずれかを選択できるデュアルライセンス。これはRustエコシステムの慣例（Rust、Tokio、Serdeと同じ選択）に従っています。