Como Gerar um CSR no Qmail

Este guia mostra como gerar um CSR (Certificate Signing Request) no qmail usando a linha de comando do OpenSSL. O qmail (e seu fork ativamente mantido, notqmail) não inclui uma ferramenta de CSR integrada. Você usa o OpenSSL para criar dois arquivos de uma só vez: uma chave privada que permanece no servidor e o CSR que você envia à sua Autoridade Certificadora (CA).

O CSR codifica o nome de host de e-mail que seu servidor apresenta durante o STARTTLS, os detalhes da sua organização e a metade pública da chave. A chave privada correspondente nunca sai do servidor. Se você a perder, o certificado emitido se torna inutilizável e você terá que gerar um novo par.

Uma observação sobre qmail vs. notqmail: o qmail original foi congelado por Daniel J. Bernstein em 1998 e não recebeu atualizações oficiais desde então. O notqmail (última versão: 1.09, maio de 2024) é o fork mantido pela comunidade que adiciona correções de segurança, compatibilidade de compilação atual e trabalho contínuo de portabilidade. O TLS não faz parte dele: no notqmail, assim como no qmail original, o STARTTLS vem de um patch externo, e as notas de lançamento da versão 1.09 registram que o patch smtp-tls existente não se aplica a essa versão e que um novo patch oficial é necessário. Verifique o status do patch para a versão que você executa antes de solicitar um certificado. O processo de geração do CSR é idêntico para ambos, pois usa o OpenSSL em vez de qualquer binário do qmail. Se você ainda estiver executando o qmail original, considere migrar para o notqmail ou Postfix para suporte contínuo de segurança.

Pré-requisitos

• Acesso root ou sudo ao servidor que executa o qmail (ou notqmail).
• OpenSSL instalado. Ele já vem no sistema base de todas as distribuições Linux e BSD principais. Verifique com openssl version.
• O nome de host de e-mail totalmente qualificado que você deseja no certificado, por exemplo mail.example.com. Ele deve corresponder ao registro MX ao qual os clientes se conectam via STARTTLS, e não ao domínio raiz simples.

Etapa 1: Prepare um diretório para a chave e o CSR

O qmail-smtpd lê seu certificado TLS em /var/qmail/control/servercert.pem, o caminho que o patch TLS fixa diretamente no código. Crie um subdiretório para o material de chave e restrinja-o ao root:

sudo mkdir -p /var/qmail/control/ssl
sudo chmod 700 /var/qmail/control/ssl
cd /var/qmail/control/ssl

Você gerará a chave e o CSR dentro deste diretório. Depois que a CA emitir o certificado, você combinará os arquivos no servercert.pem que o qmail-smtpd lê na inicialização.

Etapa 2: Gere a chave privada e o CSR

Execute o comando abaixo. Ele cria a chave privada e o CSR em uma única etapa e inclui o Subject Alternative Name (SAN) que os clientes de e-mail e as CAs modernas exigem. O SAN deve listar o nome de host de e-mail (aquele para o qual seu registro MX aponta):

sudo openssl req -new -newkey rsa:2048 -nodes 
-keyout /var/qmail/control/ssl/mail.example.com.key 
-out /var/qmail/control/ssl/mail.example.com.csr 
-subj "/C=US/ST=YourState/L=YourCity/O=YourCompany/CN=mail.example.com" 
-addext "subjectAltName=DNS:mail.example.com"

Veja o que cada parte faz:

• req -new cria uma nova solicitação de assinatura de certificado.
• -newkey rsa:2048 gera uma nova chave privada RSA de 2048 bits. 2048 bits é o mínimo atual para certificados públicos; você pode usar rsa:4096 para uma chave maior.
• -nodes deixa a chave privada sem criptografia (sem senha), para que o qmail-smtpd possa carregá-la na inicialização sem solicitar dados.
• -keyout grava a chave privada. Mantenha este arquivo privado e nunca o envie a ninguém, incluindo a CA.
• -out grava o CSR que você envia à CA.
• -subj preenche os campos do assunto diretamente no comando, para que ele seja executado sem solicitações interativas. Defina o CN (Common Name) como seu nome de host de e-mail.
• -addext “subjectAltName=…” adiciona a entrada SAN. As CAs emitem certificados com base na lista SAN, portanto o nome de host de e-mail deve aparecer aqui.

Substitua mail.example.com pelo nome de host real ao qual os clientes se conectam (geralmente o mesmo nome do seu registro MX), e edite os valores de -subj para corresponder à sua organização. O código de país de duas letras (C) deve ser maiúsculo, por exemplo US ou GB. Para um certificado de validação de domínio (DV), os campos da organização não são verificados, mas o comando ainda precisa de valores válidos. O OpenSSL moderno assina o CSR com SHA-256 por padrão, que é o que toda CA pública exige.

Se preferir preencher os campos interativamente em vez de usar -subj, retire essa opção e o OpenSSL solicitará cada valor:

sudo openssl req -new -newkey rsa:2048 -nodes 
-keyout /var/qmail/control/ssl/mail.example.com.key 
-out /var/qmail/control/ssl/mail.example.com.csr 
-addext "subjectAltName=DNS:mail.example.com"

Quando solicitado, deixe a senha de desafio e o nome de empresa opcional em branco pressionando Enter. As CAs ignoram esses campos, e uma senha de desafio causa problemas mais tarde.

Cobrindo mais de um nome de host

Se a mesma instância do qmail responder por mais de um nome (por exemplo, tanto mail.example.com quanto smtp.example.com), liste cada nome de host no valor SAN, separados por vírgulas:

-addext "subjectAltName=DNS:mail.example.com,DNS:smtp.example.com"

O Common Name deve continuar sendo o nome de host de e-mail principal. Adicionar o domínio raiz simples ao SAN só é útil se os clientes de e-mail se conectarem diretamente a ele; se seu registro MX aponta para um subdomínio, você não precisa incluir o domínio raiz no certificado.

Prefere uma chave ECDSA?

As chaves ECDSA são menores e mais rápidas que as RSA no mesmo nível de segurança e são suportadas por todos os clientes de e-mail e CAs atuais. Para gerar uma chave e um CSR P-256 (prime256v1), substitua o argumento -newkey:

sudo openssl req -new -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 -pkeyopt ec_param_enc:named_curve -nodes 
-keyout /var/qmail/control/ssl/mail.example.com.key 
-out /var/qmail/control/ssl/mail.example.com.csr 
-subj "/C=US/ST=YourState/L=YourCity/O=YourCompany/CN=mail.example.com" 
-addext "subjectAltName=DNS:mail.example.com"

Observe que o qmail original com os patches TLS do DJB pode não suportar ECDSA. Se você executa o notqmail com um OpenSSL atual, o ECDSA funciona sem problemas.

Etapa 3: Proteja a chave privada

Restrinja a chave privada para que apenas o root possa lê-la. O arquivo de chave bruta só é necessário quando você monta o servercert.pem combinado mais tarde, portanto a propriedade root e o modo 600 são corretos:

sudo chown root:root /var/qmail/control/ssl/mail.example.com.key
sudo chmod 600 /var/qmail/control/ssl/mail.example.com.key

O arquivo CSR não é secreto (contém apenas a chave pública e os detalhes do assunto), mas mantê-lo no mesmo diretório restrito ajuda a manter a organização.

Etapa 4: Verifique o CSR

Antes de enviar a solicitação, confirme se ela contém o nome de host e o SAN corretos e se sua assinatura é válida:

openssl req -noout -text -verify -in /var/qmail/control/ssl/mail.example.com.csr

Procure por verify OK na saída, verifique se a linha Subject mostra seu nome de host de e-mail como Common Name e confirme se a seção X509v3 Subject Alternative Name lista todos os nomes de host esperados. Se um SAN estiver faltando, gere novamente o CSR com o valor correto de -addext: uma CA não pode adicionar nomes de host após a emissão. Você também pode colar o CSR em nosso CSR Decoder online para verificar esses campos em um navegador.

Etapa 5: Envie o CSR

Abra o arquivo CSR e copie todo o seu conteúdo, incluindo as linhas BEGIN e END:

cat /var/qmail/control/ssl/mail.example.com.csr

O bloco se parece com isto. Copie tudo, da primeira à última linha, incluindo os cinco hífens de cada lado dos marcadores BEGIN e END:

-----BEGIN CERTIFICATE REQUEST-----
MIIC...base64-encoded data...AB
-----END CERTIFICATE REQUEST-----

Cole esse bloco no formulário de pedido do seu SSL. Depois que a CA validar o CSR e emitir o certificado, siga nosso guia de instalação do SSL para qmail para implantá-lo. Mantenha o arquivo .key no servidor: você precisa dele junto com o certificado emitido para ativar o STARTTLS, e nunca deve enviá-lo à CA ou a qualquer outra pessoa.

Se preferir não usar a linha de comando, monte a solicitação com nosso CSR Generator e cole o resultado no seu pedido. O gerador retorna uma chave privada correspondente que você coloca no mesmo caminho no servidor.

Onde os arquivos ficam no qmail

Para contextualizar, é assim que os arquivos que você acabou de gerar são integrados ao qmail depois que a CA retorna o certificado e o intermediário (pacote da CA). O qmail-smtpd lê seu material TLS de um único arquivo PEM combinado em /var/qmail/control/servercert.pem. Este arquivo deve conter a chave privada, o certificado do servidor e os certificados intermediários, concatenados nessa ordem:

cat mail.example.com.key mail.example.com.crt intermediate.pem 
> /var/qmail/control/servercert.pem
sudo chown root:nofiles /var/qmail/control/servercert.pem
sudo chmod 640 /var/qmail/control/servercert.pem

O grupo nofiles é o grupo padrão do usuário qmaild, sob o qual o qmail-smtpd é executado. O modo 640 permite que o qmaild leia o arquivo por meio da associação ao grupo, mantendo-o ilegível para outros usuários. Se o seu sistema usar um grupo diferente para o qmaild, substitua esse nome de grupo no comando chown.

O qmail-smtpd oferece STARTTLS apenas quando foi compilado com suporte a TLS, o que nem o qmail original nem o notqmail incluem por padrão. O caminho usual em ambos é o patch qmail-tls de Frederik Vermeulen: é ele que faz o qmail-smtpd ler o servercert.pem e anunciar o STARTTLS assim que esse arquivo estiver no lugar. O outro caminho é o s/qmail de Erwin Hoffmann com ucspi-ssl, no qual o sslserver exporta a variável de ambiente UCSPITLS em /service/qmail-smtpd/run e a chave fica em um serverkey.pem separado, portanto o layout de arquivo único acima não se aplica nesse caso. Depois de colocar o arquivo PEM combinado, reinicie o serviço qmail-smtpd:

sudo svc -t /service/qmail-smtpd

O passo a passo completo da instalação, incluindo a verificação da cadeia de certificados com o OpenSSL, está em nosso guia de instalação do SSL para qmail.

Verifique o STARTTLS após a instalação

Depois que o certificado for instalado, confirme se o seu servidor anuncia o STARTTLS e fornece uma cadeia válida:

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

Procure por Verify return code: 0 (ok) e confirme se o assunto e o emissor correspondem ao seu certificado. Você também pode escanear o servidor com nosso SSL Checker para obter um relatório visual da cadeia de certificados e da data de expiração.

Gerar um CSR em outras plataformas de e-mail

Está usando um servidor de e-mail diferente? Veja nossos outros guias de CSR:

• Courier IMAP Server
• Kerio Connect
• Postfix
• Proxmox
• SurgeMail
• Zimbra
• Todos os tutoriais de geração de CSR