Regras de criptografia automática

Nesta página

encrypt Schema Keyword

encryptMetadata Schema Keyword
Exemplos

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.

Observação

Funcionalidade de empresas

O recurso automático da criptografia no nível do campo só está disponível no MongoDB Enterprise 4.2 ou posterior e no MongoDB Atlas 4.2 ou clusters posteriores.

A criptografia automática em nível de campo no lado do cliente requer regras especificadas pelo usuário que identifiquem quais campos devem ser criptografados e como criptografar esses campos. Os aplicativos devem especificar as regras de criptografia automática usando um subconjunto rigoroso da sintaxe padrão do JSON schema 4 e as seguintes palavras-chave específicas da criptografia:

encrypt Palavra-chave do esquema - especifica as opções de criptografia a serem usadas ao criptografar o campo atual.
encryptMetadata Palavra-chave do esquema - especifica opções de criptografia herdáveis.

Considere um banco de banco de dados MongoDB onde a collection employees no banco de banco de dados hr contém documentos que se assemelham ao seguinte:

{
  "fname" : "Jo",
  "lname" : "Doe",
  "taxid" : "123-45-6789",
  "taxid-short" : "6789"
}

Os campos taxid e taxid-short contêm informações de identificação pessoal (PII) que devem ser protegidas contra visualização não autorizada no cliente e no servidor. As seguintes regras de criptografia automática para a coleção hr.employees marcam os campos taxid e taxid-short para criptografia automática de nível de campo do lado do cliente . MongoDB oficial 4.2+drivers compatíveis , mongosh e 4.2 ou legado mongo shell configurado com essas regras criptografa automaticamente os campos taxid e taxid-short para operações de gravação ou leitura na coleção hr.employees .

{
  "hr.employees": {
    "bsonType": "object",
    "properties": {
      "taxid": {
        "encrypt": {
          "keyId": [UUID("11d58b8a-0c6c-4d69-a0bd-70c6d9befae9")],
          "algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512_Random",
          "bsonType" : "string"
        }
      },
      "taxid-short": {
        "encrypt": {
          "keyId": [UUID("2ee77064-5cc5-45a6-92e1-7de6616134a8")],
          "algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
          "bsonType": "string"
        }
      }
    }
  }
}

Para o shell do MongoDB, use o construtor Mongo() para criar a conexão de banco de dados com as regras de criptografia automática incluídas como parte do objeto de configuração Client-Side Field Level Encryption. Consulte Conectar-se a um cluster com criptografia automática do lado do cliente habilitada para ver um exemplo.
Para os drivers oficiais do MongoDB, use o construtor de conexão do banco de dados específico do driver (por exemplo MongoClient) para criar a conexão do banco de dados com as regras de criptografia automática incluídas como parte do objeto de configuração de criptografia de nível de campo no lado do cliente. Consulte a referência da API do driver para obter documentação e tutoriais mais completos.

Importante

A criptografia automática em nível de campo do lado do cliente oferece suporte a um subconjunto rigoroso da sintaxe do JSON schema apenas para definir o comportamento da criptografia. Não especifique palavras-chave de validação de documento nas regras de criptografia automática . Para definir regras de validação de documento , configure a validação de esquema do lado do servidor.

`encrypt` Schema Keyword

"bsonType" : "object",
"properties" : {
  "<fieldName>" : {
    "encrypt" : {
      "algorithm" : "<string>",
      "bsonType" : "<string>" | [ "<string>" ],
      "keyId" : [ <UUID> ]
    }
  }
}

encrypt

Objeto

Indica que <fieldName> deve ser criptografado. O objeto encrypt tem os seguintes requisitos:

encrypt não pode ter nenhum campo filho no objeto <fieldName> . encrypt deve ser o único filho do objeto <fieldName> .
encrypt não pode ser especificado dentro de qualquer subesquema das palavras-chave items ou additionalItems . Especificamente, a criptografia automática no nível do campo do lado do cliente não suporta a criptografia de elementos individuais de uma array.

O objeto encrypt pode conter somente os seguintes campos:

algorithm
bsonType
keyId

Incluir qualquer outro campo no objeto encrypt resulta em erros ao emitir operações de leitura ou gravação criptografadas automaticamente

Se keyId ou algorithm forem omitidos, a Biblioteca Compartilhada de Criptografia Automática verificará a árvore completa de campos pai e tentará construir essas opções a partir do objeto encryptMetadata mais próximo que especifica a opção. bsonType não pode ser herdado e pode ser necessário dependendo do valor de algorithm.

Se a Biblioteca compartilhada de criptografia automática não puder construir o objeto encrypt completo usando os campos especificados para o objeto e quaisquer chaves herdadas encryptMetadatanecessárias, a criptografia automática falhará e retornará um erro.

encrypt.algorithm

String

Indica qual algoritmo de criptografia usar ao criptografar valores de <fieldName>. Suporta apenas os seguintes algoritmos :

AEAD_AES_256_CBC_HMAC_SHA_512-Random
AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic

Para obter a documentação completa sobre os algoritmos de criptografia, consulte Algoritmos de criptografia.

Se omitido, a Biblioteca Compartilhada de Criptografia Automática verifica a árvore completa de campos pai para a chave encryptMetadata.algorithm mais próxima e herda esse valor. Se não houver nenhum algorithm pai, a criptografia automática em nível de campo falhará e retornará um erro.

Se encrypt.algorithm ou seu valor herdado for AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic, o objeto encrypt exigirá o campo encrypt.bsonType.
Se encrypt.algorithm ou seu valor herdado for AEAD_AES_256_CBC_HMAC_SHA_512-Random, o objeto encrypt poderá incluir o campo encrypt.bsonType .

encrypt.bsonType

Corda | Array de strings

O tipo de BSON do campo que está sendo criptografado. Obrigatório se encrypt.algorithm for AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic.

Se encrypt.algorithm ou seu valor herdado for AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic, bsonType deverá especificar um único tipo. bsonType não suporta nenhum dos seguintes BSON types com o algoritmo de criptografia determinística:

double
decimal128
bool
object
array

Se encrypt.algorithm ou seu valor herdado for AED_AES_256_CBC_HMAC_SHA_512-Random, bsonType é opcional e pode especificar uma array de tipos de bson suportados. Para campos com bsonType de array ou object, o cliente criptografa toda a array ou objeto e não seus elementos individuais.

encrypt.bsonType não suporta os seguintes tipos, independentemente de encrypt.algorithm ou de seu valor herdado:

minKey
maxKey
null
undefined

encrypt.keyId

Array de UUID único

O UUID da chave de criptografia de dados a ser usada para criptografar valores de campo. O UUID é um conjunto de dados binários BSON elemento do subtipo 4.

Especifique uma string dentro da array.

Se omitido, a Biblioteca Compartilhada de Criptografia Automática verifica a árvore completa de campos pai para a chave encryptMetadata.keyId mais próxima e herda esse valor. Se não houver nenhum keyId pai, a criptografia automática em nível de campo falhará e retornará um erro.

O keyId ou seu valor herdado deve existir no cofre de chave especificado como parte das opções de configuração de criptografia automática. Se a chave de encriptação de dados especificada não existir, a criptografia automática falhará.

Os drivers oficiais do MongoDB têm requisitos específicos da linguagem para especificar a UUID. Consulte a documentação do driver para ver a documentação completa sobre a implementação da criptografia no nível do campo no lado do cliente.

`encryptMetadata` Schema Keyword

{
  "bsonType" : "object",
  "encryptMetadata" : {
    "algorithm" : "<string>",
    "keyId" : [ <UUID> ]
  },
  "properties" : {
    "encrypt" : {}
  }
}

encryptMetadata

Objeto

Define as opções de criptografia que um objeto encrypt aninhado no filho properties pode herdar. Se um encrypt estiver faltando uma opção necessária para oferecer suporte à criptografia, a Biblioteca Compartilhada de Criptografia Automática pesquisará toda a árvore de objetos pai para localizar um objeto encryptMetadata que especifique a opção ausente.

encryptMetadata deve ser especificado em subesquemas com bsonType: "object". encryptMetadata não pode ser especificado para nenhum subesquema das palavras-chave items ou additionalItems . Especificamente, a criptografia automática no nível do campo do lado do cliente não suporta a criptografia de elementos individuais de uma array.

O objeto encryptMetadata pode conter somente os seguintes campos. Incluir qualquer outro campo no objeto encrypt resulta em erros ao emitir operações de leitura ou gravação criptografadas automaticamente:

algorithm
keyId

encryptMetadata.algorithm

String

O algoritmo de criptografia a ser usado para criptografar um determinado campo. Se um objeto encrypt não estiver no campo algorithm , a Biblioteca Compartilhada de Criptografia Automática procurará toda a árvore de objetos pai para localizar um objeto encryptMetadata que especifique encryptMetadata.algorithm.

Suporta apenas os seguintes algoritmos :

AEAD_AES_256_CBC_HMAC_SHA_512-Random
AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic

Para obter a documentação completa sobre os algoritmos de criptografia, consulte Algoritmos de criptografia.

Se especificar AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic, qualquer objeto encrypt que herde esse valor deverá especificar encrypt.bsonType.

encryptMetadata.keyId

Array de UUID único

O UUID de uma chave de criptografia de dados. O UUID é um conjunto de dados binários BSON elemento do subtipo 4.

Especifique uma string dentro da array.

Se um objeto encrypt não estiver no campo keyId , a Biblioteca Compartilhada de Criptografia Automática procurará toda a árvore de objetos pai para localizar um objeto encryptMetadata que especifique encryptMetadata.keyId.

A chave de criptografia de dados deve existir no cofre de chave especificado como parte das opções de configuração de criptografia automática. As opções de configuração especificadas também devem incluir acesso apropriado ao KMS (KMS) e à Chave Mestra do Cliente (CMK) usada para criar a chave de dados. A criptografia automática falhará se a chave de criptografia de dados não existir ou se o cliente não puder descriptografar a chave com o KMS e CMK especificados.

Exemplos

Criptografar vários campos automaticamente
Criptografar automaticamente vários campos com herança

Criptografar vários campos automaticamente

Considere uma collection MedCo.patients onde cada documento tem a seguinte estrutura:

{
  "fname" : "<String>",
  "lname" : "<String>",
  "passportId" : "<String>",
  "bloodType" : "<String>",
  "medicalRecords" : [
    {<object>}
  ],
  "insurance" : {
    "policyNumber" : "<string>",
    "provider" : "<string>"
  }
}

O campo a seguir contém informações de identificação pessoal (PII) que podem ser query:

passportId
bloodType
insurance.policyNumber
insurance.provider

O algoritmo de criptografia determinístico garante que a saída criptografada de um valor permaneça estática. Isso permite que query de um valor específico retornem resultados significativos ao custo de maior suscetibilidade à recuperação da análise de frequência. O algoritmo de criptografia determinístico atende, portanto, aos requisitos de criptografia e de consultabilidade dos dados.

O campo a seguir contém informações de identificação pessoal (PII) protegidas por lei que podem nunca ser query:

medicalRecords

O algoritmo de criptografia aleatório garante que a saída criptografada de um valor seja sempre exclusiva. Isso impede que query de um valor de campo específico retornem resultados significativos, ao mesmo tempo em que oferece a maior proteção possível do conteúdo do campo. O algoritmo de criptografia aleatório atende, portanto, aos requisitos de criptografia e de consultabilidade dos dados.

O esquema a seguir especifica regras de criptografia automática que atendem aos requisitos acima para a collection MedCo.patients :

{
  "MedCo.patients" : {
    "bsonType" : "object",
    "properties" : {
      "passportId" : {
        "encrypt" : {
          "keyId" : [UUID("bffb361b-30d3-42c0-b7a4-d24a272b72e3")],
          "algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
          "bsonType" : "string"
        }
      },
      "bloodType" : {
        "encrypt" : {
          "keyId" : [UUID("bffb361b-30d3-42c0-b7a4-d24a272b72e3")],
          "algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
          "bsonType" : "string"
        }
      },
      "medicalRecords" : {
        "encrypt" : {
          "keyId" : [UUID("f3821212-e697-4d65-b740-4a6791697c6d")],
          "algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Random",
          "bsonType" : "array"
        }
      },
      "insurance" : {
        "bsonType" : "object",
        "properties" : {
          "policyNumber" : {
            "encrypt" : {
              "keyId" : [UUID("bffb361b-30d3-42c0-b7a4-d24a272b72e3")],
              "algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
              "bsonType" : "string"
            }
          },
          "provider" : {
            "encrypt" : {
              "keyId" : [UUID("bffb361b-30d3-42c0-b7a4-d24a272b72e3")],
              "algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
              "bsonType" : "string"
            }
          }
        }
      }
    }
  }
}

As regras de criptografia automática acima marcam os campos passportId, bloodType, insurance.policyNumber, insurance.provider e medicalRecords para criptografia.

Os campos passportId, bloodType, insurance.policyNumber e provider exigem criptografia determinística usando a chave especificada.
O campo medicalRecords requer criptografia aleatória usando a chave especificada.

Embora a criptografia no nível do campo do lado do cliente não ofereça suporte à criptografia de elementos individuais da array, a criptografia aleatória oferece suporte à criptografia de todo o campo da array em vez de elementos individuais no campo. As regras de criptografia automática do exemplo especificam a criptografia aleatória para o campo medicalRecords para criptografar toda a array. Se as regras de criptografia automática especificarem encrypt ou encryptMetadata dentro medicalRecords.items ou medicalRecords.additionalItems, a criptografia automática em nível de campo falhará e retornará um erro.

Os drivers compatíveis oficiais do MongoDB 4.2+, mongosh e o shell 4.2 ou posterior mongo legado exigem a especificação das regras de criptografia automática como parte da criação do objeto de conexão do banco de dados de dados :

Para mongosh, utilize o construtor Mongo() para criar uma conexão do reconhecimento de data center. Especifique as regras de criptografia automática para a schemaMap chave do parâmetro ClientSideFieldLevelEncryptionOptions . Consulte Conectar a um cluster com criptografia automática do lado do cliente habilitada para obter um exemplo completo.
Para os drivers compatíveis com o MongoDB 4.2+, use o construtor de conexão de banco de dados específico do driver (por exemplo MongoClient) para criar a conexão do banco de dados com as regras de criptografia automática incluídas como parte do objeto de configuração de criptografia de nível de campo no lado do cliente. Consulte a referência da API do driver para obter documentação e tutoriais mais completos.

Para todos os clientes, o keyVault e o kmsProviders especificados para o parâmetro de criptografia de nível de campo do lado do cliente devem conceder acesso às chaves de criptografia de dados especificadas nas regras de criptografia automática e à Chave Mestre do Cliente usada para criptografar as chaves de criptografia de dados.

Criptografar automaticamente vários campos com herança

Considere uma collection MedCo.patients onde cada documento tem a seguinte estrutura:

{
  "fname" : "<String>",
  "lname" : "<String>",
  "passportId" : "<String>",
  "bloodType" : "<String>",
  "medicalRecords" : [
    {<object>}
  ],
  "insurance" : {
    "policyNumber" : "<string>",
    "provider" : "<string>"
  }
}

Os seguintes campo contêm dados privados que podem ser query:

passportId
bloodType
insurance.policyNumber
insurance.provider

Os seguintes campo contêm dados privados que podem nunca ser query:

medicalRecords

O esquema a seguir especifica regras de criptografia automática que atendem aos requisitos de criptografia para a collection MedCo.patients :

{
  "MedCo.patients" : {
    "bsonType" : "object",
    "encryptMetadata" : {
      "keyId" : [UUID("6c512f5e-09bc-434f-b6db-c42eee30c6b1")],
      "algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic"
    },
    "properties" : {
      "passportId" : {
        "encrypt" : {
          "bsonType" : "string"
        }
      },
      "bloodType" : {
        "encrypt" : {
          "bsonType" : "string"
        }
      },
      "medicalRecords" : {
        "encrypt" : {
          "keyId" : [UUID("6c512f5e-09bc-434f-b6db-c42eee30c6b1")],
          "algorithm" : "AEAD_AES_256_CBC_HMAC_SHA_512-Random",
          "bsonType" : "array"
        }
      },
      "insurance" : {
        "bsonType" : "object",
        "properties" : {
          "policyNumber" : {
            "encrypt" : {
              "bsonType" : "string"
            }
          },
          "provider" : {
            "encrypt" : {
              "bsonType" : "string"
            }
          }
        }
      }
    }
  }
}

As regras de criptografia automática acima marcam os campos passportId, bloodType, insurance.policyNumber, insurance.provider e medicalRecords para criptografia.

Os campos passportId, bloodType, insurance.policyNumber e provider herdam suas configurações de criptografia do campo encryptMetadata principal. Especificamente, esses campos herdam os valores algorithm e keyId que especificam a criptografia determinística com a chave de criptografia de dados especificada.
O campo medicalRecords requer criptografia aleatória usando a chave especificada. As opções encrypt substituem aquelas especificadas no campo encryptMetadata pai.

Para mongosh, utilize o construtor Mongo() para criar uma conexão do reconhecimento de data center. Especifique as regras de criptografia automática para a schemaMap chave do parâmetro ClientSideFieldLevelEncryptionOptions . Consulte Conectar a um cluster com criptografia automática do lado do cliente habilitada para obter um exemplo completo.
Para os drivers compatíveis com o MongoDB 4.2+, use o construtor de conexão de banco de dados específico do driver (por exemplo MongoClient) para criar a conexão do banco de dados com as regras de criptografia automática incluídas como parte do objeto de configuração de criptografia de nível de campo no lado do cliente. Consulte a referência da API do driver para obter documentação e tutoriais mais completos.

Voltar

Criptografia automática no nível do campo do lado do cliente

Suporte de leitura/gravação com criptografia automática de nível de campo