---
pkg: "@nocobase/plugin-field-encryption"
---

# 暗号化

## はじめに

顧客の電話番号、メールアドレス、カード番号といった機密性の高いビジネスデータは、暗号化してデータベースに暗号文として保存できます。

![20251104192513](https://static-docs.nocobase.com/20251104192513.png)

## 暗号化の仕組み

:::warning
プラグインは自動的に`アプリケーションキー`を生成し、`/storage/apps/main/encryption-field-keys` ディレクトリに保存します。

`アプリケーションキー`のファイル名はキーIDとなり、拡張子が`.key`となります。ファイル名をむやみに変更しないでください。

`アプリケーションキー`ファイルは適切に保管してください。もし紛失した場合、暗号化されたデータは復号できなくなります。

サブアプリケーションでプラグインを有効にしている場合、キーのデフォルト保存ディレクトリは `/storage/apps/${サブアプリケーション名}/encryption-field-keys` となります。
:::

### 動作原理

エンベロープ暗号化方式を採用しています。

![20251118151339](https://static-docs.nocobase.com/20251118151143.png)

### キーの作成プロセス
1. 暗号化フィールドを初めて作成する際、システムは自動的に32ビットの`アプリケーションキー`を生成し、Base64エンコード形式でデフォルトの保存ディレクトリに保存します。
2. 新しい暗号化フィールドを作成するたびに、そのフィールド用にランダムな32ビットの`フィールドキー`が生成されます。その後、`アプリケーションキー`とランダムに生成された16ビットの`フィールド暗号化ベクトル`（`AES`暗号化アルゴリズム）を使用して暗号化され、`fields`テーブルの`options`フィールドに保存されます。

### フィールド暗号化プロセス
1. 暗号化フィールドにデータを書き込むたびに、まず`fields`テーブルの`options`フィールドから暗号化された`フィールドキー`と`フィールド暗号化ベクトル`を取得します。
2. `アプリケーションキー`と`フィールド暗号化ベクトル`を使用して、暗号化された`フィールドキー`を復号します。その後、`フィールドキー`とランダムに生成された16ビットの`データ暗号化ベクトル`（`AES`暗号化アルゴリズム）を使用してデータを暗号化します。
3. 復号された`フィールドキー`を使用してデータを署名し（`HMAC-SHA256`ダイジェストアルゴリズム）、Base64エンコードで文字列に変換します（生成された`データ署名`は、後続のデータ検索に使用されます）。
4. 16ビットの`データ暗号化ベクトル`と暗号化された`データ暗号文`をバイナリ結合し、Base64エンコードで文字列に変換します。
5. `データ署名`のBase64エンコード文字列と、結合された`データ暗号文`のBase64エンコード文字列を`.`区切りで結合します。
6. 最終的に結合された文字列をデータベースに保存します。

## 環境変数

`アプリケーションキー`を指定したい場合は、環境変数 `ENCRYPTION_FIELD_KEY_PATH` を使用できます。プラグインは、そのパスにあるファイルを`アプリケーションキー`として読み込みます。

`アプリケーションキー`ファイルの要件：
1. ファイル拡張子は`.key`である必要があります。
2. ファイル名はキーIDとして使用されます。一意性を保証するためにUUIDを使用することをお勧めします。
3. ファイルの内容は、Base64エンコードされた32バイトのバイナリデータである必要があります。

```bash
ENCRYPTION_FIELD_KEY_PATH=/path/to/my/app-keys/270263524860909922913.key
```

## フィールド設定

![20240802173721](https://static-docs.nocobase.com/20240802173721.png)

## 暗号化後のフィルタリングへの影響

暗号化されたフィールドは、「等しい」「等しくない」「存在する」「存在しない」といったフィルタリングのみをサポートします。

![20240802174042](https://static-docs.nocobase.com/20240802174042.png)

データフィルタリングの仕組み：
1. 暗号化フィールドの`フィールドキー`を取得し、`アプリケーションキー`を使用して`フィールドキー`を復号します。
2. `フィールドキー`を使用して、ユーザーが入力した検索テキストを署名します（`HMAC-SHA256`ダイジェストアルゴリズム）。
3. 署名された検索テキストに`.`区切り文字を結合し、データベース内で暗号化フィールドに対して前方一致検索を実行します。

## キーローテーション

:::warning
`nocobase key-rotation` コマンドを使用する前に、アプリケーションがこのプラグインをロードしていることを確認してください。
:::

アプリケーションを新しい環境に移行した後、古い環境と同じキーを使い続けたくない場合は、`nocobase key-rotation` コマンドを使用して`アプリケーションキー`を置き換えることができます。

キーローテーションコマンドを実行するには、古い環境の`アプリケーションキー`を指定する必要があります。コマンド実行後、新しい`アプリケーションキー`が生成され、古いキーと置き換えられます。新しい`アプリケーションキー`はBase64エンコード形式でデフォルトの保存ディレクトリに保存されます。

```bash
# --key-path は、データベースの暗号化データに対応する古い環境のアプリケーションキーファイルを指定します。
 yarn nocobase key-rotation --key-path /path/to/old-app-keys/270263524860909922913.key
```

サブアプリケーションの`アプリケーションキー`を置き換える場合は、`--app-name` パラメータを追加してサブアプリケーションの`name`を指定する必要があります。

```bash
 yarn nocobase key-rotation --app-name a_w0r211vv0az --key-path /path/to/old-app-keys/270263524860909922913.key
```