KeyVault.createKey()

Nesta página

Compatibilidade

Sintaxe
Comportamento
Exemplo

O MongoDB 5.0 é o fim da vida útil a partir de de 2024 outubro. Esta versão da documentação não é mais suportada. Para atualizar sua 5.0 implantação do, consulte o MongoDB 6.0 procedimentos de atualização.

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

Adiciona uma chave de criptografia de dados ao cofre de chave associado à conexão do banco de dados de dados. A criptografia no nível do campo no lado do cliente usa chaves de encriptação de dados para dar suporte à criptografia e descriptografia de valores de campo .

Retorna:	O identificador exclusivo `UUID` do diretório de dados criado.

Compatibilidade

Esse comando está disponível em implantações hospedadas nos seguintes ambientes:

MongoDB Atlas: o serviço totalmente gerenciado para implantações do MongoDB na nuvem

MongoDB Enterprise: a versão autogerenciada e baseada em assinatura do MongoDB
MongoDB Community: uma versão com código disponível, de uso gratuito e autogerenciada do MongoDB

Sintaxe

createKey() tem a seguinte sintaxe:

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

Parâmetro	Tipo	Descrição
`keyManagementService`	string	Obrigatório O serviço de gerenciamento de chaves (KMS) a ser usado para recuperar a chave mestra do cliente (CMK). Aceita os seguintes parâmetros: `aws` para Amazon Web Services KMS. Requer a especificação de uma string de chave mestra do cliente (CMK) para `customerMasterKey`. `azure` para o Azure Key Vault. Requer a especificação de um documento chave mestra do cliente (CMK) para `customerMasterKey`. Novidades na versão 5.0. `gcp` para KMS do Google Cloud Platform. Requer a especificação de um documento chave mestra do cliente (CMK) para `customerMasterKey`. Novidades na versão 5.0. `local` para uma chave managed localmente. Se `database connection` não foi configurado com o KMS especificado, a criação da chave de criptografia de dados falha.
`customerMasterKey`	string ou documento	A chave mestra do cliente (CMK) a ser usada para criptografar a chave de encriptação de dados. Obrigatório se `keyManagementService` for `aws`, `azure` ou `gcp`. Forneça a chave mestra do cliente da seguinte maneira, dependendo do seu provedor de KMS: Para o Amazon Web Services KMS, especifique o nome do recurso da Amazon (ARN) completo da chave mestre como uma única string. Para o Azure Key Vault KMS, especifique um documento contendo os seguintes pares de valores de chave: `keyName` - O nome do Azure Key Vault `keyVaultEndpoint` - O nome DNS do Azure Key Vault a ser usado `keyVersion` - Opcional. A versão da chave especificada em `keyName`, se aplicável Novidades na versão 5.0. Para o GCP KMS, especifique um documento contendo os seguintes pares de valores de chave: `projectId` - O nome do projeto GCP `location` - A localização do chaveiro KMS `keyRing` - O nome do chaveiro KMS (geralmente 'global') `keyName` - O nome da chave a ser usada `keyVersion` - Opcional. A versão da chave especificada em `keyName`, se aplicável New in version 5.0: requests that the KMS encrypt the data chave de`createKey()` criptografia material using the specified CMK. Se a CMK não existir ou se a configuração não tiver privilégios `ClientSideFieldLevelEncryptionOptions` `createKey()` suficientes para utilizar a CMK, retornará um erro. Este parâmetro não terá efeito se `keyManagementService` for `local` e puder ser omitido com segurança.
`keyAltName`	array de strings	Opcional O nome alternativo para a chave de criptografia de dados. Use `keyAltName` para melhorar a encontrabilidade de um diretório de dados específico ou como um análogo de um comentário. O método `getKeyVault()` cria automaticamente um índice único no campo `keyAltNames` com um filtro de índice parcial para somente documentos onde `keyAltNames` existe.

Comportamento

Requer a configuração da criptografia no nível do campo do lado do cliente na conexão do reconhecimento de data center

Os métodos de criptografia de nível de campo do lado do cliente mongo exigem uma conexão de reconhecimento de data center com a criptografia de nível de campo do lado do cliente habilitada. Se o reconhecimento de data center atual não foi iniciado com a criptografia de nível de campo do lado do cliente habilitada:

Use o construtor Mongo() do shell mongo para estabelecer uma conexão com as opções de criptografia de nível de campo do lado do cliente necessárias. O método Mongo() suporta os seguintes fornecedores de serviço de gerenciamento de chaves (KMS) para gerenciamento da chave mestra do cliente (CMK):
ou
Use as opções da linha mongo de comando do shell para estabelecer uma conexão com as opções exigidas. As opções de linha de comando são compatíveis apenas com o fornecedor KMS do Amazon Web Services para gerenciamento da chave mestra do cliente.

Exemplo

O exemplo a seguir destina-se a uma avaliação rápida da criptografia em nível de campo do lado do cliente. Para obter exemplos específicos de uso de KeyVault.createKey() com cada provedor deKMS compatível, consulte Criar uma chave de criptografia de dados.

A configuração da criptografia em nível de campo do lado do cliente para uma chave managed localmente requer a especificação de uma cadeia de 96 bytes codificada em base64 sem quebras de linha. A operação a seguir gera uma chave que atende aos requisitos declarados e a carrega no shell mongo :

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

Crie o objeto de criptografia no nível do campo do lado do cliente usando a string de chave local gerada:

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

Use o construtor Mongo() para criar uma conexão de reconhecimento de data center com as opções de criptografia no nível do campo do lado do cliente. Substitua o URI mongodb://myMongo.example.net pelo URI da string de conexão do cluster de destino.

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

Recupere o objeto keyVault e use o método KeyVault.createKey() para criar uma nova chave de chave de criptografia de dados usando a chave gerenciada localmente:

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

Se for bem-sucedido, createKey() retornará o UUID da nova chave de criptografia de dados. Para recuperar o novo documento da chave de encriptação de dados do cofre de chaves:

Use getKey() para recuperar a chave criada em UUID.
-ou-
Use getKeyByAltName() para recuperar a chave pelo nome alternativo.

Voltar

KeyVault.addKeyAlternetName

KeyVault.deleteKey