KeyVault.createKey()

項目一覧

互換性

構文
動作
例

MongoDB5.0 は 10 月2024 をもってサポートを終了します。このバージョンのドキュメントはサポート対象外になりました。配置をアップグレードするには、 MongoDB を参照してください。5.0 60アップグレード手順。

KeyVault.createKey(keyManagementService, customerMasterKey, ["keyAltName"])

データベース接続に関連付けられたキーヴォールトにデータ暗号化キーを追加します。クライアント側のフィールドレベル暗号化では、フィールド値の暗号化と復号化をサポートするためにデータ暗号化キーを使用します。

次の値を返します。	作成されたデータ暗号化キーの`UUID`一意の識別子。

互換性

このコマンドは、次の環境でホストされている配置で使用できます。

MongoDB Atlas はクラウドでの MongoDB 配置のためのフルマネージドサービスです

MongoDB Enterprise: サブスクリプションベースの自己管理型 MongoDB バージョン
MongoDB Community: ソースが利用可能で、無料で使用できる自己管理型の MongoDB のバージョン

構文

createKey() の構文は次のとおりです。

keyVault = db.getMongo().getKeyVault()
keyVault.createKey(
  keyManagementService,
  customerMasterKey,
  [ "keyAltName" ]
)

Parameter	タイプ	説明
`keyManagementService`	string	必須 CMK（Customer Master Key）の取得に使用するKMS （ KMS ）。次のパラメータを受け入れます。 `aws` Amazon Web Services KMSの。 `customerMasterKey` の CMK（Customer Master Key） stringを指定する必要があります。 `azure` Azure Key Vault用の。 `customerMasterKey`の CMK（Customer Master Key）ドキュメントを指定する必要があります。バージョン 5.0 で追加 `gcp` Google Cloud Platform KMS用。 `customerMasterKey`の CMK（Customer Master Key）ドキュメントを指定する必要があります。バージョン 5.0 で追加 `local` ローカルで管理されているキーの場合 `database connection`が指定された KMS で構成されていない場合、データ暗号化キーの作成は失敗します。
`customerMasterKey`	文字列またはドキュメント	データ暗号化キーの暗号化に使用する CMK（Customer Master Key）。 `keyManagementService`が`aws` 、 `azure` 、または`gcp`の場合に必須です。 KMS プロバイダーに応じて、次のように CMK を指定します。 Amazon Web Services KMS の場合は、完全な Amazon リソース名（ARN）を指定しますマスターキーのを単一の string として表示します。 Azure Key Vault KMS の場合は、次のキーと値のペアを含むドキュメントを指定します。 `keyName` - Azure Key Vault 名 `keyVaultEndpoint` - 使用する Azure Key Vault の DNS 名 `keyVersion` - 任意。 `keyName`で指定されたキーのバージョン（該当する場合）バージョン 5.0 で追加 Google Cloud Platform KMSの場合は、次のキーと値のペアを含むドキュメントを指定します。 `projectId` - GCP プロジェクト名 `location` - KMS キーの場所 `keyRing` - KMS キーリングの名前（多くの場合「グローバル」） `keyName` - 使用するキーの名前 `keyVersion` - 任意。 `keyName`で指定されたキーのバージョン（該当する場合）バージョンの新機能5.0 : は、指定された`createKey()` CMK を使用してデータ暗号化のキーマテリアルを暗号化することを要求します。 CMK が存在しない場合、または `ClientSideFieldLevelEncryptionOptions`構成に CMK を使用するための十分な特権がない場合、`createKey()` はエラーを返します。このパラメータは、 `keyManagementService`が`local`である場合は効果がなく、省略しても問題ありません。
`keyAltName`	文字列の配列	任意データ暗号化キーの別名。特定のデータ暗号化キーを見つけやすくするには、またはコメントに類似するものとして`keyAltName`を使用します。メソッドは、 `getKeyVault()`が存在するドキュメントのみを対象とする部分インデックス `keyAltNames`フィルターを使用して、フィールドに一意のインデックス`keyAltNames` を自動的に作成します。

動作

データベース接続にクライアント側のフィールドレベル暗号化を構成する必要があります

mongoクライアント側のフィールドレベル暗号化メソッドでは、クライアント側のフィールドレベル暗号化が有効になっているデータベース接続が必要です。現在のデータベース接続がクライアント側のフィールドレベル暗号化を有効にして開始されなかった場合、次のいずれかが発生します。

必要なクライアント側のフィールドレベル暗号化オプションとの接続を確立するには、 Mongo()mongoshell からコンストラクターを使用します。The Mongo() method supports the following Key Management Service (KMS) providers for Customer Master Key (CMK) management:
or
必要なオプションとの接続を確立するには、 mongo shellコマンドラインオプションを使用します。コマンドラインオプションは、CMK 管理用のAmazon Web Services KMSプロバイダーのみをサポートしています。

例

次の例は、クライアント側のフィールドレベル暗号化の迅速な評価を目的としています。サポートされている各KeyVault.createKey() KMS プロバイダーでを使用する具体的な例については、「データ暗号化キーの作成」を参照してください。

ローカルで管理されているキーに対してクライアント側のフィールドレベル暗号化を構成するには、改行を含まない base64 でエンコードされた 96 バイトのstringを指定する必要があります。次の操作では、前述の要件を満たすキーを生成し、それをmongo shell にロードします。

TEST_LOCAL_KEY=$(echo "$(head -c 96 /dev/urandom | base64 | tr -d '\n')")
mongosh --nodb --shell --eval "var TEST_LOCAL_KEY='$TEST_LOCAL_KEY'"

生成されたローカルキーstringを使用して、クライアント側のフィールドレベル暗号化オブジェクトを作成します。

var ClientSideFieldLevelEncryptionOptions = {
  "keyVaultNamespace" : "encryption.__dataKeys",
  "kmsProviders" : {
    "local" : {
      "key" : BinData(0, TEST_LOCAL_KEY)
    }
  }
}

Mongo()コンストラクターを使用して、クライアント側のフィールドレベル暗号化オプションを持つデータベース接続を作成します。 mongodb://myMongo.example.net URI を、ターゲットクラスターの接続string URIに置き換えます。

encryptedClient = Mongo(
  "mongodb://myMongo.example.net:27017/?replSetName=myMongo",
  ClientSideFieldLevelEncryptionOptions
)

keyVaultオブジェクトを取得し、 KeyVault.createKey()メソッドを使用して、ローカルで管理されているキーを使用して新しいデータ暗号化キーを作成します。

keyVault = encryptedClient.getKeyVault()
keyVault.createKey("local", ["data-encryption-key"])

成功した場合、 createKey()は新しいデータ暗号化キーのUUIDを返します。新しいデータ暗号化キードキュメントをキーヴォールトから検索するには、次のいずれかを実行します。

getKey()を使用して、 UUIDによって作成されたキーを取得します。
または
別名でキーを検索するには、 getKeyByAltName()を使用します。

戻る

KeyVault.addKeyAlternateName

KeyVault.deleteKey