Como Instalar um Certificado SSL no Qmail

Este tutorial mostra como instalar um certificado SSL/TLS no Qmail, o agente de transferência de correio criado originalmente por D. J. Bernstein. O processo é o mesmo que o Qmail utiliza há anos: criar um único ficheiro PEM que contém a chave privada, o certificado do servidor e a cadeia intermédia, colocá-lo em /var/qmail/control/servercert.pem e reiniciar o Qmail.

Antes de começar: o Qmail é um MTA legado

O próprio Qmail não é atualizado desde o lançamento original do qmail-1.03 em 1998. D. J. Bernstein colocou o código em domínio público em 2007, mas não retomou o desenvolvimento. O conhecido fork da comunidade netqmail atingiu a sua versão final 1.06 em 2007 e não é mantido há mais de uma década. O sucessor moderno ativo é o notqmail (versão atual 1.09, maio de 2024), que dá continuidade às correções de erros e à compatibilidade com sistemas modernos, mantendo-se compatível “drop-in” com o original.

Também importante para este guia: o qmail de origem não tem suporte nativo para SSL/TLS. O TLS é adicionado através de uma de duas vias de terceiros:

• O patch qmail-tls de Frederik Vermeulen, que adiciona STARTTLS ao qmail-smtpd e lê o certificado a partir de um caminho fixo: /var/qmail/control/servercert.pem. A maioria dos pacotes qmail modernos (incluindo as compilações netqmail e notqmail, a distribuição s/qmail e muitos pacotes de fornecedores) incluem este patch ou um equivalente.
• stunnel à frente do qmail-smtpd para encapsular a ligação em TLS na porta 465 (SMTPS). Isto funciona com qualquer compilação do qmail, porque a terminação TLS ocorre fora do Qmail.

Se mantém uma implementação existente do qmail, os passos abaixo continuam a aplicar-se. Se está a criar um novo servidor de correio de raiz, considere antes o Postfix ou o OpenSMTPD: ambos têm suporte TLS nativo e bem mantido, além de equipas de segurança ativas. Temos um tutorial separado sobre como instalar um certificado SSL no Postfix.

Gerar um código CSR para o Qmail

Se já gerou o seu CSR e recebeu os ficheiros SSL da sua CA, avance para Instalar o certificado SSL no Qmail.

CSR significa Certificate Signing Request (Pedido de Assinatura de Certificado): um bloco de texto codificado que contém os detalhes do seu domínio e organização. Submete-o à Autoridade de Certificação (CA) para que esta possa validar o seu pedido e emitir o certificado. Ao gerar o CSR também é criada a chave privada correspondente, que permanece no seu servidor e é necessária para a instalação. Tem duas opções:

• Utilize o nosso Gerador de CSR para criar o CSR automaticamente.
• Siga o nosso tutorial passo a passo sobre como gerar um CSR para o Qmail.

Abra o ficheiro CSR em qualquer editor de texto simples e copie o bloco inteiro, incluindo as linhas BEGIN CERTIFICATE REQUEST e END CERTIFICATE REQUEST, para o campo CSR do seu formulário de encomenda. Guarde o ficheiro da chave privada em local seguro: irá integrá-lo no ficheiro PEM na secção seguinte.

Instalar o certificado SSL no Qmail

Após a validação, a CA envia-lhe por email um arquivo ZIP com os seus ficheiros SSL: o certificado primário (do servidor) e um ou mais certificados intermédios (da CA). Extraia o arquivo no seu servidor e siga os passos abaixo.

Passo 1: Combine a chave, o certificado e a cadeia num único ficheiro PEM

O patch qmail-tls (e os equivalentes no netqmail, notqmail e s/qmail) lê tudo o que precisa para terminar o TLS a partir de um único ficheiro PEM. Concatene os ficheiros por esta ordem: primeiro a chave privada, depois o certificado do servidor e, por fim, a cadeia intermédia (CA). O certificado raiz não é necessário (os clientes já confiam nele). A partir do diretório que contém os seus ficheiros extraídos, execute:

cat yourdomain.key yourdomain.crt yourdomain.ca-bundle > servercert.pem

Se a sua CA entregou os certificados intermédios como ficheiros separados em vez de um único .ca-bundle, liste cada um após o certificado do servidor, com o certificado folha primeiro e o intermédio emissor de raiz por último:

cat yourdomain.key yourdomain.crt intermediate1.crt intermediate2.crt > servercert.pem

Abra o ficheiro resultante num editor de texto para confirmar a estrutura. Deve ter este aspeto, com marcadores reais de cinco hífens em torno de cada bloco:

-----BEGIN RSA PRIVATE KEY-----
(the text of your private key)
-----END RSA PRIVATE KEY-----
-----BEGIN CERTIFICATE-----
(the text of your primary SSL certificate)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
(the text of the intermediate CA certificate)
-----END CERTIFICATE-----

As chaves mais recentes podem estar identificadas como BEGIN PRIVATE KEY em vez de BEGIN RSA PRIVATE KEY; qualquer uma delas é válida. A chave não pode estar encriptada com uma frase-passe, porque o qmail-smtpd carrega-a no arranque sem pedir confirmação. Se a sua CA emitiu um certificado ECDSA, o bloco da chave será BEGIN EC PRIVATE KEY; nada mais se altera.

Passo 2: Mova o ficheiro para o diretório de controlo do Qmail

O nome e o caminho do ficheiro estão fixados pelo patch qmail-tls. Mova o PEM combinado para o diretório de controlo do Qmail e reforce as suas permissões, pois contém a sua chave privada:

sudo mv servercert.pem /var/qmail/control/servercert.pem
sudo chmod 600 /var/qmail/control/servercert.pem
sudo chown root:qmail /var/qmail/control/servercert.pem

O proprietário e o grupo dependem de qual utilizador executa o qmail-smtpd no seu sistema. Numa instalação padrão de netqmail ou notqmail, esse utilizador é normalmente qmaild ou o grupo qmail, pelo que root:qmail com o modo 600 funciona bem. Numa configuração baseada em vpopmail, o qmail-smtpd é executado como vpopmail, pelo que deve usar:

sudo chown vpopmail:vchkpw /var/qmail/control/servercert.pem
sudo chmod 640 /var/qmail/control/servercert.pem

De qualquer forma, o objetivo é o mesmo: o processo qmail-smtpd tem de conseguir ler o ficheiro, e mais nada deve poder fazê-lo.

Passo 3: Ajuste para compilações personalizadas

A maioria das variantes do qmail procura na localização padrão, mas algumas usam variáveis de ambiente. Verifique qual corresponde à sua compilação:

• Qmail padrão com o patch qmail-tls (netqmail / notqmail / pacotes de fornecedores): não é necessária configuração adicional. O qmail-smtpd lê automaticamente /var/qmail/control/servercert.pem. Para que o qmail-smtpd anuncie STARTTLS na resposta EHLO, a variável de ambiente UCSPITLS deve estar definida no script de execução do qmail-smtpd (normalmente /var/qmail/supervise/qmail-smtpd/run): exporte UCSPITLS=”” antes da linha do qmail-smtpd. Para exigir encriptação antes da autenticação, defina também FORCE_TLS=1.
• s/qmail com ucspi-ssl: o caminho do certificado não está fixado. Defina estas variáveis de ambiente no seu script de execução do qmail-smtpd (ou no wrapper tcpserver / sslserver correspondente): CERTFILE para o certificado do servidor, KEYFILE para a chave privada (ambas podem apontar para o mesmo ficheiro PEM combinado) e CERTCHAINFILE para os certificados intermédios. Consulte a documentação do s/qmail para os nomes exatos das diretivas na sua versão.
• Frontend stunnel (SMTPS na porta 465): aponte a diretiva cert do stunnel para /var/qmail/control/servercert.pem e faça com que a diretiva exec lance o qmail-smtpd. Este caminho não precisa de todo do patch qmail-tls; o TLS termina no stunnel.

Se não souber com que patch o seu qmail-smtpd foi compilado, verifique o binário:

strings /var/qmail/bin/qmail-smtpd | grep -iE 'tls|starttls|servercert'

Se vir referências a STARTTLS, servercert.pem ou UCSPITLS, o binário tem o patch qmail-tls compilado.

Passo 4: Reinicie o Qmail

O Qmail lê o certificado no arranque do processo, pelo que é necessário reiniciar o qmail-smtpd. Na maioria das instalações que utilizam os scripts de controlo fornecidos:

sudo qmailctl restart

Se a sua distribuição encapsular o Qmail num serviço systemd, utilize:

sudo systemctl restart qmail

Numa configuração daemontools / runit, envie um TERM ao qmail-smtpd através do svc:

sudo svc -t /service/qmail-smtpd

Observe o registo (normalmente /var/log/qmail/smtpd/current) para verificar se há erros durante o arranque. Um PEM mal formatado ou uma propriedade incorreta é a razão mais comum para o qmail-smtpd recusar ativar o TLS.

Teste a sua instalação SSL

Confirme que o Qmail está a oferecer STARTTLS e a servir o certificado correto com o OpenSSL. Substitua mail.yourdomain.com pelo nome de anfitrião do seu servidor de correio:

openssl s_client -starttls smtp -connect mail.yourdomain.com:25 -servername mail.yourdomain.com </dev/null 
| openssl x509 -noout -issuer -subject -dates

A saída deve apresentar o titular (nome comum), o emissor (a CA) e as datas de validade do seu certificado. Se configurou SMTPS através do stunnel na porta 465, remova -starttls smtp e ligue-se diretamente à porta 465:

openssl s_client -connect mail.yourdomain.com:465 -servername mail.yourdomain.com

Procure por Verify return code: 0 (ok) no final do handshake. Se vir um erro de cadeia, os certificados intermédios estão em falta no servercert.pem: acrescente-os e reinicie o qmail-smtpd. Para obter um relatório completo sobre o certificado, a cadeia e o suporte de protocolos, execute o nosso SSL Checker no nome de anfitrião do seu servidor de correio.

Perguntas Frequentes