Configurar o TLS (Transport Layer Security)

Visão geral

Neste guia, você pode aprender como usar o protocoloTLS para proteger sua conexão com uma implantação MongoDB .

Quando você habilita o TLS para uma conexão, a biblioteca PHP executa as seguintes ações:

• Usa TLS para se conectar ao MongoDB deployment

• Verifica o certificado do sistema

• Garante que o certificado certifique o sistema

Para saber como configurar seu sistema MongoDB para TLS, consulte o guia de configuração TLS no manual do MongoDB Server .

Habilitar TLS

Para habilitar o TLS para a conexão com sua implantação do MongoDB , defina a opção de conexão tls como true. Você pode fazer isso de duas maneiras: usando o uriOptions parâmetro do MongoDB\Client construtor ou por meio de um parâmetro em sua string de conexão.

$uri = 'mongodb://<hostname>:<port>';
$options = [
   'tls' => true
];
$client = new MongoDB\Client($uri, $options);

$uri = 'mongodb://<hostname>:<port>/?tls=true';
$client = MongoDB\Client($uri);

Especifique um arquivo CA

Durante a negociação TLS, o sistema do MongoDB apresenta um arquivo de chave de certificado para seu aplicação para estabelecer sua identidade. Normalmente, o certificado de um sistema foi assinado por uma CA (autoridade de certificação) conhecida, e seu aplicação depende dessa CA para validar o certificado.

No entanto, durante os testes, você pode querer agir como sua própria CA. Nesse caso, você deve instruir a biblioteca PHP a usar seus certificados CA em vez dos assinados por outro CA.

Para fazer isso, use a opção de conexão tlsCAFile para especificar o caminho para um arquivo .pem que contém a cadeia de certificados raiz. Você pode fazer isso de duas maneiras: usando o uriOptions parâmetro do MongoDB\Client construtor ou por meio de um parâmetro em sua string de conexão.

$uri = 'mongodb://<hostname>:<port>';
$options = [
   'tls' => true,
   'tlsCAFile' => '/path/to/ca.pem',
];
$client = new MongoDB\Client($uri, $options);

$uri = 'mongodb://<hostname>:<port>/?tls=true&tlsCAFile=/path/to/ca.pem';
$client = MongoDB\Client($uri);

<?php
$uri = 'mongodb://<hostname>:<port>';
$uriOptions = ['tls' => true];
$driverOptions = ['ca_dir' => '/path/to/search/'];
$client = new MongoDB\Client($uri, $uriOptions, $driverOptions);

Verifique a revogação do certificado

Quando um certificado X.509 não é mais confiável - por exemplo, se sua chave privada tiver sido comprometida - a CA revoga o certificado. A biblioteca PHP inclui duas maneiras de verificar se o certificado de um servidor foi revogado.

$uri = 'mongodb://<hostname>:<port>';
$options = [
   'tls' => true,
   'tlsDisableOCSPEndpointCheck' => true,
];
$client = new MongoDB\Client($uri, $options);

$uri = 'mongodb://<hostname>:<port>/?tls=true&tlsDisableOCSPEndpointCheck=true';
$client = MongoDB\Client($uri);

<?php
$uri = 'mongodb://<hostname>:<port>';
$uriOptions = ['tls' => true];
$driverOptions = ['crl_file' => '/path/to/file.pem'];
$client = new MongoDB\Client($uri, $uriOptions, $driverOptions);

Apresentar um Certificado de Cliente

Algumas implementações do MongoDB exigem que cada aplicação de conexão apresente um certificado de cliente que comprove sua identidade. Para especificar o certificado do cliente para a biblioteca PHP apresentar, defina a opção tleCertificateKeyFile para o caminho do arquivo .pem que contém seu certificado e chave privada.

Você pode fazer isso de duas maneiras: usando o parâmetro uriOptions do construtor MongoDB\Client ou por meio de um parâmetro em sua string de conexão.

$uri = 'mongodb://<hostname>:<port>';
$options = [
   'tls' => true,
   'tlsCertificateKeyFile' => '/path/to/client.pem',
];
$client = new MongoDB\Client($uri, $options);

$uri = 'mongodb://<hostname>:<port>/?tls=true&tlsCertificateKeyFile=/path/to/client.pem';
$client = MongoDB\Client($uri);

$ cat key.pem cert.pem > combined.pem

$uri = 'mongodb://<hostname>:<port>';
$options = [
   'tls' => true,
   'tlsCertificateKeyFile' => '/path/to/client.pem',
   'tlsCertificateKeyFilePassword' => '<passphrase>',
];
$client = new MongoDB\Client($uri, $options);

$uri = 'mongodb://<hostname>:<port>/?tls=true&tlsCertificateKeyFile=/path/to/client.pem&tlsCertificateKeyFilePassword=<passphrase>';
$client = MongoDB\Client($uri);

Permitir TLS Inseguro

Quando o TLS está habilitado, a biblioteca PHP verifica automaticamente o certificado apresentado pelo servidor . Ao testar seu código, você pode desativar essa verificação. Isso é conhecido como TLS inseguro.

Quando o TLS inseguro está ativado, o driver exige apenas que o servidor apresente um certificado X.509 . O driver aceita um certificado mesmo que alguma das seguintes afirmações seja verdadeira:

• O nome do host do servidor e o nome do assunto (ou nome alternativo do assunto) no certificado não correspondem.

• O certificado expirou ou ainda não é válido.

• O certificado não tem um certificado raiz confiável na cadeia.

• A finalidade do certificado não é válida para identificação do servidor.

Para habilitar o TLS inseguro, defina a opção de conexão tlsInsecure como true. Você pode fazer isso de duas maneiras: passando um argumento para o construtor MongoDB\Client ou por meio de um parâmetro em sua connection string.

$uri = 'mongodb://<hostname>:<port>';
$options = [
   'tls' => true,
   'tlsInsecure' => true,
];
$client = new MongoDB\Client($uri, $options);

$uri = 'mongodb://<hostname>:<port>/?tls=true&tlsInsecure=true';
$client = MongoDB\Client($uri);

Para desabilitar somente a validação do certificado, defina a opção tlsAllowInvalidCertificates como true e defina a opção tlsInsecure como false ou omita-a:

$uri = 'mongodb://<hostname>:<port>';
$options = [
   'tls' => true,
   'tlsAllowInvalidCertificates' => true,
];
$client = new MongoDB\Client($uri, $options);

$uri = 'mongodb://<hostname>:<port>/?tls=true&tlsAllowInvalidCertificates=true';
$client = MongoDB\Client($uri);

Para desabilitar somente a verificação do nome de host, configure a opção tlsAllowInvalidHostnames para true e configure a opção tlsInsecure para false ou omita:

$uri = 'mongodb://<hostname>:<port>';
$options = [
   'tls' => true,
   'tlsAllowInvalidHostnames' => true,
];
$client = new MongoDB\Client($uri, $options);

$uri = 'mongodb://<hostname>:<port>/?tls=true&tlsAllowInvalidHostnames=true';
$client = MongoDB\Client($uri);

Documentação da API

Para saber mais sobre como configurar o TLS para a biblioteca PHP, consulte a seguinte documentação da API:

• MongoDB\Client