メインコンテンツまでスキップ

Vault とキーの API

Vault バックエンドを登録し、アプリにリンクし、そこに保持されるキー素材を管理する。

適用対象:
Cockpit v2マネジメント APIVault とキー

概要​

このページのすべてのルートは、認証済みの マネジメント API（/api/…）上に存在します。各リクエストにはベアラートークンが含まれます。

注記

Authorization: Bearer <access-token>

リクエストは、トークンに埋め込まれた テナント のセキュリティコンテキストで実行されます — テナント ID を渡すことはなく、自分のテナントの Vault とキーのみを参照・変更できます。Vault とキーの操作は、さらに Vault 権限 によって制御されます。呼び出し元は、そのルートが要求する権限（例: Vault の登録、キーの同期、キーによる暗号操作の実行）を保持している必要があります。

ベース URL、テナンシー、エラーモデルについては API 概要 を、トークンの取得方法については 認証 を参照してください。

Vault 管理​

Vault は、1 つのバックエンドインスタンス（ソフトウェア、MPC、HSM、またはクラウド KMS）を記述する、保存されたテナントスコープのレコードです。これらのルートは Vault を登録し、バックエンドのヘルスとパフォーマンスを確認し、バックエンドが既に保持しているキーを検出・インポートします。

メソッド + パス目的
GET · POST /api/vaultsVault の一覧取得 · 新しい Vault の登録
GET · PUT · DELETE /api/vaults/{id}単一の Vault の取得・更新・削除
POST /api/vaults/test-connectionVault 作成前にバックエンドをテスト
GET /api/vaults/{id}/health · /versionバックエンドのヘルスとバージョン
POST /api/vaults/{id}/benchmark · /crypto-testパフォーマンスベンチマークと暗号処理の往復確認
GET /api/vaults/{id}/keys · /remote-key-countVault 内のキーとリモートバックエンドのキー数
POST /api/vaults/{id}/sync-keys既存のバックエンドキーを検出／インポート

アプリと Vault のリンク​

アプリケーションは、使用できる Vault にリンクされます。アプリ用に作成されたキーは特定の Vault に紐づきます。

メソッド + パス目的
GET /api/apps/{id}/vaultsアプリにリンクされた Vault の一覧取得
POST · DELETE /api/apps/{id}/vaults/{vault_id}アプリへの Vault のリンク・リンク解除

Vault タイプとキータイプ​

Vault を登録したり、キーを作成したりする前に、これらの読み取り専用ルートを使ってプラットフォームがサポートするバックエンドと、各バックエンドが受け付けるキータイプを確認します。

メソッド + パス目的
GET /api/vaults/types利用可能な Vault（バックエンド）タイプ
GET /api/vaults/types/{type}/key-types指定した Vault タイプがサポートするキータイプ

キー​

暗号鍵は Vault 内で作成され、vault_id によって参照されます。これらのルートはキーのライフサイクル — 作成、一覧取得、取得、ローテーション、有効化／無効化の状態遷移 — を管理し、キーによる暗号操作を実行します。秘密鍵および共通鍵の素材はバックエンド内にとどまり、エクスポート可能なのは公開鍵のみです。

メソッド + パス目的
GET · POST /api/keysキーの一覧取得 · 新しいキーの作成
GET · PUT · DELETE /api/keys/{id}キーの取得・メタデータ更新・削除
POST /api/keys/{id}/rotateキーを新しいバージョンにローテーション
POST /api/keys/{id}/activate · /deactivateキーの有効化（Active）または無効化（Deactivated）
POST /api/keys/{id}/revoke理由付きでキーを失効
GET /api/keys/{id}/public-keyPEM 形式で公開鍵をエクスポート
POST /api/keys/{id}/encrypt · /decryptキーによる平文の暗号化・暗号文の復号
GET /api/keys/{id}/appsこのキーを使用するアプリの一覧取得
有効化／無効化は状態遷移

独立した enable / disable ルートはありません。activate はキーを Active 状態に、deactivate は Deactivated 状態に遷移させます。暗号操作に使用できるのは Active 状態のキーのみです。

ポスト量子にはソフトウェアまたは Securosys が必要

ポスト量子キータイプ（ML-KEM、ML-DSA、SLH-DSA）は、Software Vault または Securosys を基盤とする Vault でのみ作成できます。キーを作成する前に、GET /api/vaults/types/{type}/key-types を使用して、バックエンドが必要なキータイプを受け付けることを確認してください。

関連項目