platform-encryption-configure

Platform Encryption の設定

Salesforce Shield Platform Encryption を設定するために、暗号化を有効にするメタデータを生成し、適切な設定を選択します。具体的には、フィールドで使用する暗号化方式、要件に適した鍵管理モデル、テナントシークレットのライフサイクルの仕組みを決定します。これはハイブリッドスキルです。Platform Encryption が Metadata API の実際のインターフェースを公開している場合は、デプロイ可能な *.settings-meta.xml / *.field-meta.xml を出力し、UI または REST のみで実行できる操作については、根拠に基づいたガイダンスを提供します。

対象範囲

• 対象：フィールドで encryptionScheme を選択して適用すること、PlatformEncryptionSettings / EncryptionKeySettings による決定論的暗号化、Cache-Only Keys、External Key Management、リプレイ検出の有効化、BYOK / BYOKMS / EKM / Cache-Only キーモデルの説明、テナントシークレットのローテーションと破棄の仕様、暗号化フィールドのクエリ動作。
• 対象外：暗号化しない通常のカスタムフィールド（platform-custom-field-generate を使用してください）、Metadata API フィールドリファレンス（platform-metadata-api-context-get を使用してください）、Classic Encryption（EncryptedText フィールド）— これは別のレガシー機能です。メタデータの組織へのデプロイ／プッシュ（デプロイライフサイクルスキルの対象です）。

---

必須入力

作業を進める前に、以下を収集または推定してください。

• 質問の種類：ユーザーはデプロイ可能な成果物（設定ファイル、暗号化フィールド）を求めていますか、それともガイダンス（どのモデルがよいか、鍵をローテーションするとどうなるか）を求めていますか？デプロイ可能な成果物の場合は、assets/ から XML を生成します。ガイダンスの場合は、references/ に基づいて回答します。説明、確認、比較を求める質問は、すべてガイダンスです。「これは正しいですか？」「どのような関係がありますか？」「できますか？」「順序の要件はありますか？」「X と Y の違いを説明してください」「どの鍵モデルを使うべきですか？」などが該当します。**ユーザーが自分で設定を作成、デプロイ、記述しようとしている場合でも同様です。**設定を記述するのはユーザーの作業であり、スキルが提供する成果物がファイルになるわけではありません。明示的に「生成して／作成して／ファイルをください／このフィールドを暗号化してください」と依頼された場合に限り、成果物のリクエストとして扱います。
• 鍵モデルの選択に関する質問は、デプロイ可能なメタデータではなくガイダンスです。「BYOK と外部鍵管理／BYOKMS／EKM／Cache-Only の違いを説明してください」「鍵のマテリアルを Salesforce の外部に保持できるのはどれですか？」「BYOK と EKM のどちらを使うべきですか？」などには、デプロイ可能な *.settings-meta.xml ではなく、単一の Markdown 回答ファイル（ガイダンスの説明）で回答します。その回答で有効化設定（例：canExternalKeyManagement、enableCacheOnlyKeys）の名前を挙げても、設定成果物にはなりません。回答ファイル内でフィールド名を明記し、ユーザーが明示的に「設定ファイルを生成／作成してください」と依頼しない限り、EncryptionKey.settings-meta.xml は出力しないでください。
• フィールド暗号化の対象（フィールドに関する作業の場合）：オブジェクトとフィールドの API 名、およびユーザーがそのフィールドでフィルター、並べ替え、グループ化を行う必要があるかどうか（決定論的暗号化と確率的暗号化の選択に影響します）。
• 鍵モデル（鍵に関する作業の場合）：鍵が Salesforce で生成されるか（デフォルト）、顧客から提供されるか（BYOK）、外部 KMS に保存されるか（BYOKMS/EKM）、オンデマンドで取得されるか（Cache-Only）。

リクエストが明確な場合は、すぐに生成または回答してください。ユーザーに質問を重ねないでください。

---

ワークフロー

1. リクエストを分類する — 上記の「必要な入力」を用いて、デプロイ可能な成果物かガイダンスかに振り分けます。その後、出力を求められた内容に正確に絞り込みます:

   • ガイダンスの質問では、Markdown の回答ファイルをちょうど 1 つ生成します — 完全な診断・説明を記述した単一のファイル（例: answer.md）であり、それ以外は何も生成しません。*.settings-meta.xml、*.field-meta.xml、あるいは 2 つ目の補助ドキュメントも出力しないでください。これは、「…するとどうなりますか?」「…するにはどうすればよいですか?」「どのモデルが…?」「X は正しいですか?」「…できますか?」「関係性や順序はどうなっていますか?」といったあらゆる質問（クエリの動作や Cache-Only／リプレイに関する質問を含む）を対象とします。「設定を書く前に」や「ファイルを作成する前に」といった節は、ユーザーの次のステップを述べているにすぎず、その質問をデプロイ可能なメタデータのリクエストに変えるものではありません — 設定ファイルではなく、回答ファイルを作成してください。
   • ガイダンスの回答内でメタデータの変更に言及することは、そのデプロイ可能なファイルを出力することを意味しません。 修正や診断の質問 — 「フィールドをクエリ可能にするにはどうすればよいですか?」、「クエリが失敗したのはなぜで、どう修正すればよいですか?」、「どのキーモデルならデータを Salesforce に残さずに済みますか?」 — は、1 つの Markdown 回答ファイルの中で答えます。その中で関連する要素やスキームをインラインで挙げてください（例: 「Deterministic* スキームに切り替えて enableDeterministicEncryption を有効にする」、「External Key Management — canExternalKeyManagement を使う」）。その変更を実演するために *.field-meta.xml や *.settings-meta.xml を追加で実体化してはいけません — 回答内でその要素に言及することが成果物のすべてです。デプロイ可能なメタデータファイルを生成するのは、ユーザーがフィールドや設定ファイルを生成・作成・提供するよう明示的に述べた場合のみです。
   • 成果物のリクエストでは、指定された特定のメタデータファイルのみを生成します — DEPLOYMENT_GUIDE.md、README.md、EXPLANATION.md、組織の settings ファイル、あるいはユーザーが求めていない付随的な成果物を追加しないでください。
   • デプロイ手順や組織の設定が前提条件である場合は、1 つの回答ファイル内（ガイダンスの場合）または1 つの成果物内のコードコメント（成果物リクエストの場合）で述べてください — 決して余分なファイルとして述べないでください。

2. フィールド暗号化の場合 — references/encryption-schemes.md を読んでスキームを選択し、assets/encrypted-field.field-meta.xml を開始テンプレートとして読み込みます。encryptionScheme には、4 つの有効な enum 値のうちちょうど 1 つを設定します（リファレンスを参照）。フィルタ可能なのは Deterministic* スキームのみです。

   フィールドファイルはリポジトリのルートではなく、SFDX のソースパスに書き込んでください。 *.field-meta.xml は 必ず objects/<ObjectApiName>/fields/<FieldApiName>__c.field-meta.xml に配置する必要があります（例: objects/Patient__c/fields/Diagnosis_Notes__c.field-meta.xml）。オブジェクトフォルダにはオブジェクトの API 名を使い（カスタムオブジェクトなら Patient__c、標準オブジェクトなら Contact）、ファイル名はフィールドの API 名にちなんで付けます。ファイルをリポジトリのルートやフラットなディレクトリ、その他のフォルダの下に出力することは、XML 自体が正しくても構造上の不備となります。

3. 組織レベルの暗号化設定の場合 — assets/PlatformEncryption.settings-meta.xml（決定論的暗号化、フィールド履歴の暗号化、MEK 権限）または assets/EncryptionKey.settings-meta.xml（Cache-Only、EKM、Data 360、トランザクション DB、リプレイ検出）を読み込みます。キーモデルのフィールドを設定する前に、references/key-models.md を読んでください。

   出力ファイルにはルート要素ではなく Settings のメンバーにちなんで名前を付け、settings/ の下に書き込んでください。 Settings ファイルは settings/<member>.settings-meta.xml でなければなりません。ここで <member> は組織のメタデータメンバー名です — EncryptionKey（ルートは <EncryptionKeySettings>）と PlatformEncryption（ルートは <PlatformEncryptionSettings>）です。これをリポジトリのルートではなく settings/ ソースフォルダに配置します（例: settings/EncryptionKey.settings-meta.xml）。キー設定ファイルを Encryption.settings-meta.xml や EncryptionKeySettings.settings-meta.xml と命名すると、デプロイが 「The object '…' of type Settings metadata does not exist.」 で失敗します。 Cache-Only Keys とリプレイ検出は一方向の依存関係であり、自動的に有効になるわけではありません。 enableReplayDetection を設定できるのは、enableCacheOnlyKeys が true の場合のみです。Cache-Only を有効にしても、リプレイ検出が自動的に有効になることはありません。組織では、リプレイ検出を無効にしたまま Cache-Only を有効にしても問題ありません。

4. テナントシークレットの操作（ローテーション、破棄、BYOK のアップロード、Cache-Only コールアウトの設定）については、references/tenant-secret-lifecycle.md を確認してください。これらの操作は UI／REST のみで実施します。ガイダンスは、デプロイ可能なメタデータファイルではなく、単一の Markdown 回答ファイルに記載してください。

5. 生成した設定 XML を検証してください — scripts/validate-encryption-metadata.sh を、引数にファイルパスを指定して実行し、報告された問題をすべて修正してください。このスクリプトは、リプレイ検出の依存関係と encryptionScheme の列挙値を決定論的に確認します。

6. 実例と照合してください — 生成した EncryptionKeySettings ファイルを examples/cache-only-keys.settings-meta.xml と照合してください。

---

ルール／制約

制約	理由
encryptionScheme は CaseInsensitiveDeterministicEncryption、CaseSensitiveDeterministicEncryption、None、ProbabilisticEncryption のいずれかでなければなりません	Metadata API（CustomField、API 44.0 以降）が受け付ける値はこれらのみです。それ以外の文字列ではデプロイに失敗します。
enableReplayDetection は enableCacheOnlyKeys が true の場合にのみ設定してください	仕様では「enableReplayDetection を true に設定する前に、enableCacheOnlyKeys=true が必要」とされています。一方向の依存関係です。
フィールドの絞り込み、並べ替え、グループ化が必要な場合にのみ、決定論的なスキームを使用してください	確率的暗号化はより強固ですが、絞り込みはできません。決定論的暗号化は、クエリ可能性のために暗号強度をある程度犠牲にします。
確率的に暗号化されたフィールドに対する絞り込み／並べ替え／グループ化が、何も通知されずに 0 件を返すと説明してはいけません	プラットフォームはクエリを INVALID_FIELD で拒否します（注意事項を参照）。ユーザーに「何も返されない」と伝えるのは事実に反します。
enableExternalKeyManagement は出力しないでください — フィールド名は canExternalKeyManagement です	WSDL の要素名は canExternalKeyManagement です。一部のドキュメントにあるサンプルでは、存在しない要素名が使われています。
トランザクション DB、EKM、Data 360 の鍵フィールドには API 63.0 以降が必要です	canEncryptTransactionalDatabase、canExternalKeyManagement、canManageDataCloudKeys は 63.0 で導入されました。
ガイダンスに関する質問には、Markdown の回答ファイルを必ず 1 つだけ作成してください — デプロイ可能な *.settings-meta.xml／*.field-meta.xml は作成せず、別のドキュメントも作成しないでください	回答ファイルはユーザーの参照ドキュメントであり、ワークスペースに保存して共有または改訂できます。ガイダンスの質問に対してデプロイ可能なメタデータファイルを出力するのは、誤って適用されるおそれのある、求められていない設定の提供です。ファイルを何も出力しなければ、ユーザーが利用できる成果物が残りません。
成果物のリクエストでは、依頼されたメタデータファイルのみを出力してください — 付随ファイルは作成しないでください	DEPLOYMENT_GUIDE.md／README.md／EXPLANATION.md や、依頼されていない追加の settings ファイルを作成しても、余計な情報になるだけです。前提条件は、2 つ目のファイルではなく、成果物内のコードコメントに記載してください。

---

注意事項

問題	対処方法
確率的暗号化されたフィールドでのフィルタリング／ソート／グループ化	クエリは INVALID_FIELD で拒否されます。「field '' can not be sorted / filtered / grouped in a query call.」 クエリで使用する必要がある場合は、フィールドを決定論的な方式に変更してください。
キャッシュ専用キーを設定すればリプレイ検知が自動的に有効になると思い込むこと	自動的には有効になりません。enableReplayDetection を明示的に設定してください。また、enableCacheOnlyKeys=true を設定した後にのみ有効にしてください。
決定論的な照合における大文字と小文字の区別	CaseSensitiveDeterministicEncryption は大文字と小文字を区別して完全一致します。CaseInsensitiveDeterministicEncryption は大文字と小文字を正規化します。誤った方式を選ぶと、等価フィルターが気付かないうちに機能しなくなります。
BYOK と BYOKMS/EKM の混同	BYOK では、キー素材をアップロードし、Salesforce が保管します。BYOKMS/EKM では、キー素材は外部 KMS に保持されます。references/key-models.md を参照してください。
enableExternalKeyManagement という要素名の使用	要素名が間違っています。フィールド名は canExternalKeyManagement です。
Classic Encryption と Shield の混同	encryptionScheme は Shield 専用です。EncryptedText カスタムフィールドは従来の Classic 機能であり、対象外です。

---

出力要件

成果物は依頼内容によって異なります。次のものだけを正確に作成してください。

• ガイダンスに関する質問には、Markdown の回答ファイルを必ず 1 つだけ作成してください。 「…するとどうなりますか」「…するにはどうすればよいですか」「どのモデルが…ですか」「X は適切ですか」といった質問は、暗号化フィールドのクエリ動作、キャッシュ専用／リプレイ検知の関係、テナントシークレット／BYOK／キャッシュ専用のライフサイクル、キーのモデル選択に関するものも含め、診断や説明を十分に記した単一の Markdown ファイル（例：answer.md）を作成して回答してください。デプロイ可能な *.settings-meta.xml／*.field-meta.xml や 2 つ目のドキュメントを追加で出力しないでください。また、ファイルを一切作成せずに回答してはいけません。回答ファイルはユーザーが参照用に保存できるドキュメントです。
• フィールド暗号化の成果物：encryptionScheme を設定した *.field-meta.xml のみを、objects/<ObjectApiName>/fields/<FieldApiName>__c.field-meta.xml に作成してください。設定ファイルやデプロイガイドは作成しないでください。依頼に合わせて <type> を選択してください。最大 255 文字の文字列フィールドには Text、255 文字を超える必要がある場合（256 文字以上）に限り LongTextArea を使用してください。「255 文字までの長いテキスト」は LongTextArea ではなく Text フィールドです。納品するファイルからテンプレートの説明コメントブロックを削除し、クリーンなメタデータを提出してください。チャットでの説明は簡潔にし、選択した方式とその理由を述べる 1〜2 文にとどめてください（例：「ProbabilisticEncryption — 保存時の保護が最も強く、フィルタリング／ソート／グループ化はできません。クエリ不要という要件に合致します」。依頼内容を丸ごと繰り返したり、すべての方式を列挙したり、設定／デプロイ手順を追加したりしないでください。提出物はファイルであり、エッセイではありません。
• 組織設定の成果物：依頼に必要な設定ファイルのみを、Metadata API のメンバー名に基づく settings/<member>.settings-meta.xml に作成してください。settings/PlatformEncryption.settings-meta.xml（ルート要素は <PlatformEncryptionSettings>）および／または settings/EncryptionKey.settings-meta.xml（ルート要素は <EncryptionKeySettings>）です。ルート要素の名前をファイル名に使ったり、リポジトリのルートに配置したりしないでください。

依頼されていない補助ファイル（DEPLOYMENT_GUIDE.md、README.md、追加の組織設定ファイルなど）を作成しないでください。前提条件は成果物内のコードコメント、またはガイダンス用の単一回答ファイル内に記載してください。ファイル構成は assets/ 内のテンプレートに従います。

---

スキル間の連携

必要なもの	委任先
暗号化なしのカスタムフィールド	platform-custom-field-generate
Metadata API の生の型／フィールド参照情報	platform-metadata-api-context-get

参照ファイル一覧

ファイル	参照するタイミング
assets/encrypted-field.field-meta.xml	暗号化されたカスタム項目を生成する前
assets/PlatformEncryption.settings-meta.xml	組織の暗号化ポリシー設定（メンバー PlatformEncryption）を生成する前
assets/EncryptionKey.settings-meta.xml	キー管理設定（Cache-Only、EKM、Data 360、メンバー EncryptionKey）を生成する前
references/encryption-schemes.md	決定論的方式と確率論的方式を選択する場合、または暗号化された項目のクエリ動作を説明する場合
references/key-models.md	BYOK／BYOKMS／EKM／Cache-Only のキーモデルを設定または説明する場合
references/tenant-secret-lifecycle.md	キーのローテーション、破棄、BYOK のアップロードについてユーザーから質問された場合
examples/cache-only-keys.settings-meta.xml	生成した Cache-Only キー設定ファイルを検証する場合
scripts/validate-encryption-metadata.sh	設定 XML を生成した後 — 再生依存関係と方式の列挙値を検証します