Habilitar TLS/SSL em uma conexão
Nesta página
- Visão geral
- Habilitar TLS/SSL
- Configurar certificados
- Configurar o JVM Trust Store
- Configurar o Armazenamento de Chaves JVM
- Configurar um armazenamento confiável e um armazenamento de chaves específicos do cliente
- Desativar verificação de nome de host
- Restringir conexões ao TLS 1,2 Apenas
- Personalizar configuração TLS/SSL através do Java SE SSLContext
- Personalizar configuração TLS/SSL através do Netty SslContext
- Protocolo de status do certificado online (OCSP)
- OCSP orientado ao cliente
- Grampeamento de OCLC
Visão geral
Neste guia, você pode aprender a se conectar a instâncias MongoDB com o protocolo de segurança TLS/SSL usando o suporte TLS/SSL subjacente no JDK. Para configurar sua conexão para usar TLS/SSL, habilite as configurações TLS/SSL em ConnectionString ou MongoClientSettings.
Observação
Depuração de TLS/SSL
Caso encontre problemas para configurar a conexão TLS/SSL, use a propriedade do sistema -Djavax.net.debug=all para exibir mais declarações de log. Consulte o guia da Oracle para a depuração de conexões TLS/SSL para obter mais informações.
Habilitar TLS/SSL
Você pode habilitar o TLS/SSL para a conexão com sua instância do MongoDB de duas maneiras diferentes: por meio de um parâmetro em sua string de conexão ou usando um método na classe MongoClientSettings.Builder.
Observação
Se você se conectar usando o protocolo seedlist DNS, indicado pelo prefixo mongodb+srv em sua connection string, o driver ativará o TLS/SSL. Para desativá-lo, defina o valor do parâmetro tls ou ssl como false em sua connection string ou instância MongoClientSettings.
Para saber mais sobre o comportamento da conexão ao usar uma lista de sementes DNS, consulte a seção Formato de conexão SRV no manual do servidor.
Para habilitar TLS/SSL em uma conexão com uma ConnectionString, atribua ao parâmetro de string de conexão tls um valor de true na string de conexão passada para MongoClients.create():
MongoClient mongoClient = MongoClients.create("mongodb+srv://<db_username>:<db_password>@<cluster-url>?tls=true");
Para configurar as opções de conexão TLS/SSL do MongoClient usando a classe MongoClientSettings.Builder, chame o método applyToSslSettings(). Defina a propriedade enabled como true no bloco SslSettings.Builder para habilitar o TLS/SSL:
MongoClientSettings settings = MongoClientSettings.builder() .applyToSslSettings(builder -> builder.enabled(true)) .build(); MongoClient client = MongoClients.create(settings);
Configurar certificados
Os aplicativos Java que iniciam solicitações TLS/SSL exigem acesso a certificados criptográficos que comprovam a identidade do próprio aplicativo e de outros aplicativos com os quais o aplicativo interage. Você pode configurar o acesso a esses certificados em seu aplicativo com os seguintes mecanismos:
A Loja JVM Trust e a Loja JVM Key
Um repositório fiduciário e um repositório de chaves específicos para o cliente
Observação
As seções a seguir são baseadas na documentação do Oracle JDK, portanto, algumas partes podem ser inaplicáveis ao seu JDK ou à implementação personalizada de TLS/SSL que você usa.
Configurar o JVM Trust Store
Observação
Por padrão, o JRE inclui muitos certificados públicos comumente usados de autoridades de assinatura, como o Let's Encrypt. Como resultado, você pode se conectar a instâncias do MongoDB Atlas (ou a qualquer outro servidor cujo certificado seja assinado por uma autoridade no repositório de certificados padrão do JRE) com TLS/SSL sem configurar o repositório de confiança.
O armazenamento confiável da JVM salva certificados que identificam com segurança outros aplicativos com os quais seu aplicativo Java interage. Usando esses certificados, seu aplicativo pode provar que a conexão com outro aplicativo é genuína e segura contra adulteração por terceiros.
Se sua instância do MongoDB usa um certificado assinado por uma autoridade que não está presente no armazenamento de certificados padrão do JRE, seu aplicativo deve configurar duas propriedades do sistema para iniciar solicitações SSL/TLS. Essas propriedades garantem que seu aplicativo possa validar o certificado TLS/SSL apresentado por uma instância MongoDB conectada.
javax.net.ssl.trustStore: o caminho para um armazenamento de confiança que contém o certificado da autoridade de assinaturajavax.net.ssl.trustStorePassword: a senha para acessar o armazenamento de confiança definido emjavax.net.ssl.trustStore
Você pode criar um armazenamento de confiança com a ferramenta de linha de comando keytool fornecida como parte do JDK:
keytool -importcert -trustcacerts -file <path to certificate authority file> -keystore <path to trust store> -storepass <password>
Configurar o Armazenamento de Chaves JVM
Observação
Por padrão, as instâncias do MongoDB não executam validação de certificado de cliente. Você deve configurar o armazenamento de chaves se configurou sua instância do MongoDB para validar certificados de cliente.
O armazenamento de chaves JVM salva certificados que identificam com segurança seu aplicativo Java em outros aplicativos. Usando esses certificados, outros aplicativos podem provar que a conexão com o seu aplicativo é genuína e segura contra adulteração por terceiros.
Um aplicativo que inicia solicitações TLS/SSL precisa definir duas propriedades do sistema JVM para garantir que o cliente apresente um certificado TLS/SSL para a implantação MongoDB:
javax.net.ssl.keyStore: o caminho para um armazenamento de chaves que contém os certificados TLS/SSL do clientejavax.net.ssl.keyStorePassword: a senha para acessar o armazenamento de chaves definido emjavax.net.ssl.keyStore
Você pode criar um armazenamento de chaves com a ferramenta de linha de comando keytool ou OpenSSL.
Para obter mais informações sobre como configurar um aplicativo Java para usar TLS/SSL, consulte o Guia de referência JSSE.
Configurar um armazenamento confiável e um armazenamento de chaves específicos do cliente
Você pode configurar um armazenamento confiável e um armazenamento de chaves específicos do cliente usando o método init() da classe SSLContext.
Você pode encontrar um exemplo mostrando como configurar um cliente com uma instância do SSLContext na seção Personalizar Configuração TLS/SSL com um SSLContext deste guia.
Para mais informações sobre a classe SSLContext, consulte a documentação API para Contexto SSL.
Desativar verificação de nome de host
Por padrão, o driver garante que o nome de host incluído nos certificados TLS/SSL do servidor corresponda aos nomes de host fornecidos ao construir um MongoClient. Para desabilitar a verificação do nome de host para seu aplicativo, você pode desabilitá-la explicitamente definindo a propriedade invalidHostNameAllowed do construtor true no lambda do construtor applytoSslSettings():
MongoClientSettings settings = MongoClientSettings.builder() .applyToSslSettings(builder -> { builder.enabled(true); builder.invalidHostNameAllowed(true); }) .build();
Aviso
Desabilitar a verificação de nome de host pode tornar sua configuração insegura. Desabilite a verificação de nome de host somente para fins de teste ou quando não houver outra alternativa.
Restringir conexões ao TLS 1,2 Apenas
Para restringir seu aplicativo para usar apenas o protocolo TLS 1,2, defina a propriedade do sistema jdk.tls.client.protocols como "TLSv1,2".
Observação
Java Runtime Environments (JREs) antes do Java 8 somente habilitam o protocolo TLS 1.2 em versões de atualização. Se o seu JRE não tiver habilitado o protocolo TLS 1.2, atualize para uma versão posterior para se conectar usando o TLS 1.2.
Personalizar configuração TLS/SSL através do Java SE SSLContext
Se sua configuração de TLS/SSL exigir personalização, você poderá definir a propriedade sslContext de seu MongoClient passando um objeto SSLContext para o construtor no lambda applyToSslSettings():
SSLContext sslContext = ... MongoClientSettings settings = MongoClientSettings.builder() .applyToSslSettings(builder -> { builder.enabled(true); builder.context(sslContext); }) .build(); MongoClient client = MongoClients.create(settings);
Personalizar configuração TLS/SSL através do Netty SslContext
Se você usar o driver com Netty para E/S de rede, você tem uma opção para conectar uma implementação alternativa de protocolo TLS/SSL fornecida pela Netty .
import com.mongodb.MongoClientSettings; import com.mongodb.client.MongoClients; import com.mongodb.client.MongoClient; import com.mongodb.connection.netty.NettyStreamFactoryFactory; import io.netty.handler.ssl.SslContext; import io.netty.handler.ssl.SslContextBuilder; import io.netty.handler.ssl.SslProvider;
Observação
O driver testa com o Netty na versão io.netty:netty-all:4.1.79.Final
Para instruir o driver a usar o método io.netty.handler.ssl.SslContext, use o método NettyStreamFactoryFactory.Builder.sslContext. Consulte a documentação do método para obter detalhes sobre as diferentes variantes do io.netty.handler.ssl.SslProvider que o driver suporta e as implicações de usá-las.
SslContext sslContext = SslContextBuilder.forClient() .sslProvider(SslProvider.OPENSSL) .build(); MongoClientSettings settings = MongoClientSettings.builder() .applyToSslSettings(builder -> builder.enabled(true)) .streamFactoryFactory(NettyStreamFactoryFactory.builder() .sslContext(sslContext) .build()) .build(); MongoClient client = MongoClients.create(settings);
Protocolo de status do certificado online (OCSP)
OCSP é um padrão usado para verificar se os certificados X.509 foram revogados. Uma autoridade de certificação pode adicionar um certificado X.509 à Lista de revogação de certificados (CRL) antes do tempo de expiração para invalidar o certificado. Quando um cliente envia um certificado X.509 durante o handshake TLS, o servidor de revogação da CA verifica a CRL e retorna um status de "bom", "revocado" ou "desconhecido".
O condutor suporta as seguintes variações de OCSP:
OCSP orientado ao cliente
Grampeamento de OCLC
As seções a seguir descrevem as diferenças entre elas e como habilitá-las para seu aplicativo.
Observação
O driver Java utiliza os argumentos JVM configurados para o aplicativo e não pode ser substituído por uma instância MongoClient específica.
OCSP orientado ao cliente
No OCSP controlado pelo cliente, o cliente envia o certificado em uma solicitação OCSP para um respondente OCSP depois de receber o certificado do servidor. O respondente do OCSP verifica o status do certificado com uma autoridade de certificação (CA) e relata se ele é válido em uma resposta enviada ao cliente.
Para habilitar o OCSP orientado ao cliente para seu aplicativo, defina as seguintes propriedades do sistema JVM:
Propriedade | Valor |
|---|---|
com.sun.net.ssl.checkRevocation | Configure esta propriedade para true para habilitar a verificação de revogação. |
ocsp.enable | Configure esta propriedade para true para habilitar OCSP orientado ao cliente. |
Aviso
Se o respondente OCSP não estiver disponível, o suporte a TLS fornecido pelo JDK relatará uma "falha rígida". Isso difere do comportamento de "falha suave" do MongoDB Shell e de alguns outros drivers.
Grampeamento de OCLC
O grampeamento OCSP é um mecanismo no qual o servidor deve obter o certificado assinado da autoridade de certificação (CA) e incluí-lo em uma resposta OCSP com carimbo de data/hora para o cliente.
Para habilitar o grampeamento OCSP para seu aplicativo, defina as seguintes propriedades do sistema JVM:
Propriedade | Descrição |
|---|---|
com.sun.net.ssl.checkRevocation | Configure esta propriedade para true para habilitar a verificação de revogação. |
jdk.tls.client.enableStatusRequestExtension | Set this property to true to enable OCSP stapling.If unset or set to false, the connection can proceed regardless of the presence or status of the certificate revocation response. |
Para mais informações sobre OCSP, consulte os seguintes recursos:
Documentação do Oracle JDK 8 sobre como habilitar o OCSP para um aplicativo