Configurar o TLS (Transport Layer Security)
Nesta página
Visão geral
Neste guia, você aprenderá a usar o TLS protocolo para proteger sua conexão com um sistema do 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 .
Observação
Esta página pressupõe conhecimento prévio de TLS/SSL e acesso a certificados válidos. Uma descrição completa de certificados TLS/SSL, PKI (Public Key Infrastructure) e Autoridades de Certificação (CAs) está além do escopo desta documentação.
Dica
A biblioteca PHP delega a maior parte do comportamento TLS ao Driver MongoDB C. Para obter informações sobre como o driver C lida com o TLS, incluindo etapas de configuração e comportamento esperado, consulte Configurar o TLS na documentação do driver C.
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);
Dica
Se a string de conexão incluir a modificação +srv
, que especifica o formato de conexão SRV, o TLS será habilitado na sua conexão por padrão.
Para saber mais sobre o formato de conexão SRV, consulte Formato de conexão SRV na documentação do MongoDB Server .
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);
Especifique um diretório de CA
Se você estiver usando OpenSSL ou LibreSSL (libtls
) para suporte a TLS, também poderá usar a opção ca_dir
para instruir a biblioteca PHP a procurar um arquivo CA em um diretório. O driver pesquisa nesse diretório se não encontrar um arquivo CA no caminho especificado na opção tlsCAFile
.
O seguinte exemplo de código mostra como utilizar o parâmetro driverOptions
para especificar a opção ca_dir
:
$uri = 'mongodb://<hostname>:<port>'; $uriOptions = [ 'tls' => true, ]; $driverOptions = [ 'ca_dir' => '/path/to/search/' ]; $client = new MongoDB\Client($uri, $uriOptions, $driverOptions);
Dica
Esta opção corresponde ao OpenSSL SSL_CTX_load_verify_locations e o LibreSSL tls_config_set_ca_path Parâmetro.
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.
OCSP
O processo do Protocolo de Status do Certificado Online (OCSP) varia dependendo da versão do MongoDB Server à qual você está se conectando:
MongoDB v4.4 ou posterior: o servidor grampeia uma resposta OCSP com registro de data e hora em seu certificado. A biblioteca PHP valida o certificado em relação à resposta OCSP. Se a CA tiver revogado o certificado ou se a resposta OCSP for inválida, a negociação TLS falhará.
MongoDB v4.3 ou anterior: o servidor fornece um endpoint OCSP, com o qual a biblioteca PHP entra em contato diretamente. A biblioteca PHP então valida o certificado em relação à resposta OCSP. Se a CA não tiver revogado o certificado, o handshake TLS continuará, mesmo que a resposta OCSP seja inválida ou malformada.
Para impedir que a biblioteca PHP entre em contato com o endpoint OCSP, defina a opção de conexão tlsDisableOCSPEndpointCheck
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 string de conexão.
$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);
Observação
Mesmo que a opção tlsDisableOCSPEndpointCheck
esteja definida como true
, a biblioteca PHP ainda verificará qualquer resposta OCSP grampeada no certificado de um servidor.
Lista de revogação de certificados
Em vez de usar o OCSP, você pode usar a instrução da biblioteca PHP para verificar o certificado do servidor em relação a uma Lista de revogação de certificados (CRL) publicada pela CA. Para fazer isso, defina a opção crl_file
para o caminho do arquivo da CRL. Inclua esta opção no driverOptions
parâmetro do MongoDB\Client
construtor , como mostrado no seguinte exemplo de código:
$uri = 'mongodb://<hostname>:<port>'; $uriOptions = [ 'tls' => true, ]; $driverOptions = [ 'crl_file' => '/path/to/file.pem' ]; $client = new MongoDB\Client($uri, $uriOptions, $driverOptions);
Dica
Você pode especificar um arquivo CRL no formato .pem
ou .der
.
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);
Importante
Seu certificado de cliente e chave privada devem estar no mesmo arquivo .pem
. Se estiverem armazenados em arquivos diferentes, você deverá concatená-los. O exemplo a seguir mostra como concatenar um arquivo de chave e um arquivo de certificado em um terceiro arquivo chamado combined.pem
em um sistema Unix:
cat key.pem cert.pem > combined.pem
Forneça uma senha de chave
Se a chave privada em seu arquivo de certificado estiver criptografada, você deverá usar a opção tlsCertificateKeyFilePassword
para fornecer a senha. 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, '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.
Observação
Mesmo quando o TLS inseguro está habilitado, a comunicação entre o cliente e o servidor é criptografada com TLS.
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);
Aviso
Não use em produção
Sempre defina as opções tlsInsecure
, tlsAllowInvalidCertificates
e tlsAllowInvalidHostnames
como false
em produção.
Definir qualquer uma dessas opções como true
em um ambiente de produção torna seu aplicativo desprotegido e potencialmente vulnerável a certificados expirados e a processos externos que se apresentam como instâncias de cliente válidas.
Documentação da API
Para saber mais sobre como configurar o TLS para a biblioteca PHP, consulte a seguinte documentação da API: