Como corrigir o erro "Não foi possível iniciar o TLS: Falha no handshake SSL" no Zimbra

A mensagem Unable to start TLS: SSL handshake failedsignifica que um cliente e um servidor não conseguiram concluir a negociação que inicia uma conexão criptografada. No Zimbra, a mensagem pode vir de diferentes locais. Uma variação frequente aparece durante o processo de zmcontrol statusconexão e indica que a verificação do certificado falhou na conexão com o servidor LDAP. Um cliente de e-mail ou um servidor SMTP também pode relatar um problema de handshake em uma porta de e-mail pública.

A solução depende de qual conexão falhou. Comece identificando o serviço e o nome do host nas linhas de log correspondentes. Em seguida, verifique o certificado, sua cadeia de emissão, o relógio do sistema e o endpoint TLS. Evite desativar o TLS como primeira medida: isso pode mascarar o problema, ao mesmo tempo que enfraquece ou interrompe a comunicação interna com o servidor de e-mail.

O que você precisa saber antes de fazer qualquer alteração

TLS é o protocolo que criptografa uma conexão de rede. Um handshake TLS é a troca inicial na qual os dois sistemas concordam com os parâmetros de criptografia e validam o certificado do servidor. O STARTTLS inicia como uma conexão de protocolo simples e, em seguida, alterna para TLS quando ambas as partes o solicitam. Tanto LDAP quanto SMTP podem usar STARTTLS, portanto, esse erro por si só não identifica o serviço com falha.

Antes de executar comandos de reparo, registre a versão do Zimbra, se a instalação é de nó único ou de vários nós, o comando ou cliente exato que apresenta o erro e a linha de log completa. Agende a implantação de certificados ou reinicializações de serviço durante uma janela de manutenção. Mantenha um backup dos arquivos de certificado e da configuração antes de editá-los.

• Execute comandos administrativos como a conta e com as permissões exigidas pela sua versão do Zimbra.
• Não cole chaves privadas, senhas ou registros de e-mail não editados em tickets ou fóruns públicos.
• Não altere os sinalizadores de segurança LDAP nem as configurações de protocolo até saber qual endpoint apresentou falha e verificar o certificado correspondente.

Passo 1: Identifique a conexão TLS com falha

Primeiro, reproduza o problema e leia a mensagem completa. Se ela aparecer quando o Zimbra verificar o status do serviço e incluir termos como when connecting to ldap master, investigue o TLS LDAP interno. Se apenas um cliente de e-mail falhar no envio SMTP, investigue o endpoint SMTP público e o nome do host, a porta e o modo de criptografia do cliente.

su - zimbra
zmcontrol status

Analise as entradas de log recentes do Zimbra com o mesmo carimbo de data/hora. Em muitas instalações, o log principal está localizado em /var/log/zimbra.log; utilize o local de log configurado em seu servidor.

grep -Ei 'Unable to start TLS|SSL handshake|certificate|ldap|STARTTLS' /var/log/zimbra.log | tail -n 80

Procure pelo nome do processo, host remoto, porta e quaisquer detalhes mais específicos do OpenSSL, como falha na verificação do certificado, certificado expirado, emissor desconhecido ou alerta de protocolo. Esses detalhes diferenciam um problema de confiança no certificado de uma incompatibilidade de rede ou protocolo.

Para um erro LDAP interno, verifique quais hosts LDAP este servidor está configurado para usar. Consulte as chaves de configuração locais individualmente e compare seus nomes de host com o DNS e o certificado do servidor:

zmlocalconfig ldap_url
zmlocalconfig ldap_master_url
zmlocalconfig ldap_starttls_supported
zmlocalconfig ldap_starttls_required

A disponibilidade e a saída das chaves podem variar de acordo com a versão do Zimbra e a função do nó. Essas são leituras de diagnóstico; não altere um valor apenas porque ele aparece na saída. A documentação do Zimbra descreve a função das configurações LDAP STARTTLS e recomenda manter o TLS interno ativado: Valores de configuração local de TLS e STARTTLS do Zimbra .

Etapa 2: Verifique o relógio do sistema, o DNS e a acessibilidade.

A validação do certificado depende do relógio do servidor. Se o relógio estiver muito atrasado ou adiantado, um certificado válido pode aparecer como inválido ou expirado. Confirme a hora no host Zimbra e em qualquer servidor LDAP mestre ou réplica envolvido na conexão.

date -u
getent hosts ldap.example.com

Substitua ldap.example.compelo nome do host LDAP encontrado na configuração ou no log. Confirme se ele resolve para o endereço do servidor esperado e se a porta LDAP configurada está acessível através do firewall e da rede do host. Em instalações com vários nós, teste a partir do nó Zimbra que registrou a falha para o nó LDAP real — não apenas da sua estação de trabalho.

Para uma conexão SMTP STARTTLS voltada para o cliente, o guia de solução de problemas SMTP do Zimbra demonstra como testar a porta 25 com o OpenSSL. A porta 587 também é comumente usada para o envio de mensagens com STARTTLS. Use o nome do host e a porta configurados no cliente de e-mail:

openssl s_client -starttls smtp -connect mail.example.com:587 -servername mail.example.com -showcerts

Para SMTP na porta 25, substitua 587por 25. A porta 465 usa TLS implícito, portanto, não adicione -starttls smtpao testar essa porta. Uma conexão TCP bem-sucedida não prova por si só que o certificado é confiável ou que o cliente está usando o modo de segurança correto. Consulte o guia de solução de problemas de SMTP e OpenSSL do Zimbra .

Etapa 3: Inspecione o certificado que o Zimbra realmente implantou.

Um certificado é um documento de identidade assinado para um servidor. O certificado deve ser válido para o nome de host usado pelos clientes, estar dentro do prazo de validade e ser emitido por uma autoridade certificadora confiável para o componente de conexão. Um certificado pode parecer correto em um navegador, enquanto um certificado diferente pode estar implantado no LDAP, Postfix ou em um nó proxy.

Como administrador do Zimbra, visualize o certificado que o Zimbra reporta como implantado:

/opt/zimbra/bin/zmcertmgr viewdeployedcrt

Verifique o assunto ou o Nome Alternativo do Assunto (SAN), a entidade emissora, a data de expiração e os serviços de cada certificado listado. O SAN deve conter o nome do host realmente usado para a conexão LDAP ou de e-mail. Verifique também se todos os nós em uma implantação com vários servidores possuem o certificado e a cadeia esperados. O Zimbra observa que a visualização de certificados implantados é local ao servidor, portanto, execute a verificação em cada nó relevante.

Se você tiver os arquivos de certificado de origem, verifique suas datas e nomes antes da implantação:

openssl x509 -in /tmp/commercial.crt -noout -dates -subject -issuer -ext subjectAltName

Substitua o caminho de exemplo pelo arquivo de certificado que você está avaliando. A ausência de um SAN, um certificado folha ou intermediário expirado, um nome de host incorreto ou um certificado emitido para outro servidor podem causar falha na validação.

Etapa 4: Verifique a chave privada e a cadeia de certificados.

A cadeia de certificados é o conjunto de certificados emissores que permite a um cliente rastrear o certificado do servidor até uma autoridade confiável. Se o arquivo da cadeia omitir um certificado intermediário ou contiver a cadeia errada, os clientes podem rejeitar o servidor mesmo que o certificado folha esteja atualizado. O certificado e a chave privada também devem ser um par correspondente.

Para um certificado comercial, as ferramentas de certificado do Zimbra oferecem uma etapa de verificação. Adapte os caminhos dos arquivos à sua instalação e à autoridade certificadora:

/opt/zimbra/bin/zmcertmgr verifycrt comm   /opt/zimbra/ssl/zimbra/commercial/commercial.key   /tmp/commercial.crt   /tmp/ca_chain.crt

Prossiga somente se a verificação confirmar que o certificado e a chave privada correspondem e que a cadeia de certificados é válida. Não implante um certificado após uma verificação com falha. Use a cadeia intermediária fornecida pela autoridade certificadora e o formato de cadeia esperado pela sua versão do Zimbra; não monte uma cadeia por tentativa e erro ou anexando certificados raiz não relacionados.

O guia de certificados do Zimbra documenta a sequência de verificação e implantação, incluindo a cadeia de CA: Instalação de certificados Zimbra e ferramentas de linha de comando . A página de solução de problemas da cadeia de certificados também explica os erros de verificação da cadeia de emissores: Orientações sobre a cadeia de certificados do Zimbra .

Etapa 5: Corrija e implemente o certificado com segurança.

Se a verificação indicar um certificado expirado, chave incorreta, certificado intermediário ausente ou incompatibilidade de nome de host, obtenha ou gere os arquivos corretos antes da implantação. Siga o procedimento para sua versão do Zimbra e tipo de certificado. Para um certificado comercial, o comando documentado tem este formato geral:

/opt/zimbra/bin/zmcertmgr deploycrt comm /tmp/commercial.crt /tmp/ca_chain.crt

Utilize a sintaxe de comando e os privilégios exatos documentados para a sua versão instalada. A CLI do Zimbra pode instalar certificados para componentes como o MTA, LDAP e proxy, portanto, a implantação pode afetar diversos serviços. Em um ambiente com vários nós, confirme se o certificado foi implantado corretamente em todos os servidores relevantes, incluindo o servidor LDAP mestre.

Após a verificação da implantação, reinicie os serviços do Zimbra durante a janela de manutenção planejada, caso o procedimento de lançamento exija, e confirme o status do serviço e os certificados implantados:

su - zimbra
zmcontrol restart
zmcontrol status
/opt/zimbra/bin/zmcertmgr viewdeployedcrt

Uma reinicialização interrompe o acesso a e-mails e à web enquanto os serviços são parados e reiniciados. Não execute esse procedimento indiscriminadamente em um servidor de produção ocupado. O guia de certificados do Zimbra documenta o uso zmcontrol restartapós a implantação e a verificação do resultado com [comando/ferramenta] viewdeployedcrt.

Etapa 6: Verifique a configuração de confiança LDAP sem desativar o TLS

Se o próprio certificado for verificado, mas o cliente LDAP do Zimbra ainda o rejeitar, inspecione o material de confiança do LDAP e o nó com falha. A nota de solução de problemas do MTA arquivada do Zimbra lista uma cadeia de CA inválida, certificados de CA expirados e arquivos inesperados entre /opt/zimbra/conf/caas possíveis causas de falhas do LDAP STARTTLS. Considere isso como uma pista de diagnóstico, não como um motivo para excluir arquivos: compare o diretório com um backup válido ou com as orientações específicas da versão e preserve seu conteúdo antes de fazer alterações.

Para uma simples consulta LDAP STARTTLS, um cliente OpenLDAP pode exigir o StartTLS e consultar o DSE raiz sem fornecer credenciais de conta:

ldapsearch -x -ZZ -H ldap://ldap.example.com:389 -b "" -s base namingContexts

Utilize o host e a porta LDAP reais em sua implementação. Com as ferramentas OpenLDAP, -ZZas solicitações StartTLS são tratadas como erros caso a falha no estabelecimento da conexão seja considerada um erro. Se esta verificação falhar com uma mensagem de confiança ou certificado, compare o certificado retornado pelo endpoint LDAP com o certificado implementado e a confiança da Autoridade Certificadora (CA) disponível para o cliente. Se o teste for bem-sucedido em um nó, mas falhar em outro, investigue as diferenças no DNS, nos arquivos da CA ou na configuração local.

Etapa 7: Considere a compatibilidade do protocolo somente após a verificação dos certificados.

Um handshake também pode falhar se o cliente e o servidor não concordarem com a versão do protocolo TLS ou com o conjunto de cifras. Isso pode ocorrer com clientes obsoletos, configurações de segurança personalizadas ou valores padrão específicos da versão. Teste o endpoint com um cliente OpenSSL atualizado e verifique as configurações TLS do Zimbra para a versão exata do produto. Evite copiar comandos de protocolo antigos de páginas arquivadas para uma instalação mais recente; a configuração de cifras e protocolos pode mudar entre versões.

Não tente "corrigir" o erro habilitando SSLv3, enfraquecendo a verificação ou desabilitando globalmente o LDAP STARTTLS. Uma discussão no fórum do Zimbra contém uma solução alternativa antiga que desativava o LDAP STARTTLS, mas outro usuário alertou corretamente que desabilitar um recurso de segurança não é uma forma segura de reparar o certificado. As próprias notas de configuração local do Zimbra recomendam manter o TLS entre processos e o LDAP STARTTLS habilitados. Utilize essa alteração apenas como um procedimento diagnóstico temporário e rigorosamente controlado, caso o suporte do Zimbra oriente você a fazê-lo, e restaure as configurações de segurança imediatamente.

Como confirmar o reparo

• zmcontrol statusA operação é concluída sem o erro LDAP TLS, caso essa tenha sido a operação com falha.
• O endpoint LDAP ou SMTP afetado apresenta o certificado esperado, não expirado, e a cadeia de emissor completa.
• Um teste realizado a partir do mesmo host e caminho de rede foi bem-sucedido com o modo TLS pretendido.
• Os registros do Zimbra não mostram mais erros de verificação de certificado ou de handshake no momento do teste.
• Para SMTP, envie uma mensagem de teste em ambas as direções e confirme a entrega nas filas ou registros relevantes.

Se o problema persistir, colete o erro completo, a versão do Zimbra, o serviço e o nome do host afetados, as datas e o SAN dos certificados, a saída da verificação e as linhas de log relevantes. Oculte chaves privadas, credenciais, endereços de usuário e detalhes confidenciais do host antes de compartilhar. A mensagem precisa é um sintoma, não um diagnóstico completo; o nome do serviço afetado e o motivo da falha no OpenSSL determinam a solução adequada.

Nota sobre a documentação: as páginas públicas de certificados e TLS do Zimbra incluem material para várias versões, e algumas páginas de solução de problemas estão explicitamente arquivadas. Os comandos aqui refletem o padrão da CLI documentado, mas os caminhos dos certificados, privilégios e requisitos de reinicialização devem ser verificados na documentação da versão do Zimbra instalada. Revisado em 6 de outubro de 2026.