MongoDB\Database::createEncryptedCollection()

Definición

MongoDB\Database::createEncryptedCollection()

Crea explícitamente una colección cifrada.

function createEncryptedCollection(
    string $collectionName,
    MongoDB\Driver\ClientEncryption $clientEncryption,
    string $kmsProvider,
    ?array $masterKey,
    array $options
): array

Este método creará automáticamente claves de datos para todos los campos cifrados donde keyId sea null. Las claves de datos se crearán utilizando MongoDB\Driver\ClientEncryption::createDataKey() y los parámetros proporcionados $kmsProvider y $masterKey. Se devolverá una copia de la opción modificada encryptedFields además del resultado de crear la colección.

Este método no afecta ninguna configuración de autoencriptado en la existente MongoDB\Client objetos. Los usuarios deben configurar el cifrado automático después de crear la colección cifrada con createEncryptedCollection().

Parámetros

$collectionName : string

El nombre de la colección cifrada que se va a crear.

$clientEncryption MongoDB\Driver\ClientEncryption

El objeto ClientEncryption utilizado para crear claves de datos.

$kmsProvider : string

Proveedor KMS (por ejemplo, "local", "aws") que se utilizará para cifrar nuevas claves de datos. Esto corresponde al parámetro $kmsProvider para MongoDB\Driver\ClientEncryption::createDataKey().

$masterKey : arreglo|null

Opciones de clave específicas de KMS que se usarán para cifrar nuevas claves de datos. Esto corresponde con la opción masterKey para MongoDB\Driver\ClientEncryption::createDataKey().

Si $kmsProvider es "local", esto debería ser null.

$options : arreglo

Un arreglo que especifica las opciones deseadas.

El parámetro $options permite las mismas opciones que MongoDB\Database::createCollection(). La opción encryptedFields es obligatoria.

Return Values

Una tupla (es decir, arreglo de dos elementos) que contiene el documento resultante del comando crear (un arreglo u objeto según la opción typeMap) y la opción modificada encryptedFields.

Errores/Excepciones

MongoDB\Exception\CreateEncryptedCollectionException si se encuentra algún error al crear las claves de datos o la colección. Se puede acceder a la excepción original y a la opción encryptedFields modificada a través de los métodos getPrevious() y getEncryptedFields(), respectivamente.

MongoDB\Exception\InvalidArgumentException por errores relacionados con el análisis de parámetros u opciones.

Ejemplo

El siguiente ejemplo crea una colección users cifrada en la base de datos test. El campo ssn dentro de la colección users se definirá como un campo de string cifrado.

<?php
// 96-byte master key used to encrypt/decrypt data keys
define('LOCAL_MASTERKEY', '...');
$client = new MongoDB\Client;
$clientEncryption = $client->createClientEncryption([
    'keyVaultNamespace' => 'keyvault.datakeys',
    'kmsProviders' => [
        'local' => ['key' => new MongoDB\BSON\Binary(base64_decode(LOCAL_MASTERKEY), 0)],
     ],
);
[$result, $encryptedFields] = $client->test->createEncryptedCollection(
    'users',
    $clientEncryption,
    'local',
    null,
    [
        'encryptedFields' => [
            'fields' => [
                ['path' => 'ssn', 'bsonType' => 'string', 'keyId' => null],
            ],
        ],
    ]
);

Si la colección cifrada se creó de forma correcta, $result contendrá el documento de respuesta del comando create y $encryptedFields['fields'][0]['keyId'] contendrá un objeto MongoDB\BSON\Binary con subtipo 4 (es decir, UUID).

La opción encryptedFields modificada puede utilizarse para construir un nuevo MongoDB\Client con cifrado automático habilitado.

<?php
$encryptedClient = new MongoDB\Client(
    null, // Connection string
    [], // Additional connection string options
    [
        'autoEncryption' => [
            'keyVaultNamespace' => 'keyvault.datakeys',
            'kmsProviders' => [
                'local' => ['key' => new MongoDB\BSON\Binary(base64_decode(LOCAL_MASTERKEY), 0)],
             ],
             'encryptedFieldsMap' => [
                 'test.users' => $encryptedFields,
             ],
        ],
    ]
);

Ver también

• MongoDB\Database::createCollection()

• MongoDB\Client::createClientEncryption()

• MongoDB\Driver\ClientEncryption::createDataKey()

• referencia del comando crear en el manual de MongoDB