Configuração do HTTPS no Engine

O HTTPS (Hypertext Transfer Protocol Secure) é uma implementação do protocolo HTTP sobre uma camada TLS. Essa camada adicional permite que os dados sejam transmitidos através de uma conexão criptografada e garante a autenticidade do servidor para os usuários do sistema. A porta TCP usada por norma para o protocolo HTTPS é a 443. Mais informações podem ser encontradas aqui.

Para configurar o Engine para utilizar o HTTPS são necessários 2 arquivos:

Certificado digital e sua cadeia intermediária de certificados.
Chave privada.

Os certificados digitais devem ser emitidos por uma autoridade certificadora de escolha do cliente, levando em consideração o custo da emissão e renovação do certificado, a compatibilidade com os navegadores e a idoneidade da empresa. A única exigência do sistema é que a chave privada e o certificado digital sejam gerados no formato textual PEM. Abaixo algumas certificadoras conhecidas no mercado:

As chaves privadas e certificados podem ser gerados de forma automática por um cliente que implemente o protocolo ACME, como o Certbot, ou manualmente, seguindo as instruções de uma autoridade certificadora. A seguir são apresentados detalhes de cada uma dessas abordagens.

Emissão automática via Certbot

O Certbot é um aplicativo auxiliar que deve ser instalado no mesmo servidor do Engine com o objetivo de automatizar a emissão e renovação de certificados da autoridade certificadora Let’s Encrypt.

Instalação do Certbot

Para instalar o Certbot, devem ser seguidas as instruções de instalação do site https://certbot.eff.org/instructions. Nele, devem ser informados “Other” como software do Web Site e o sistema operacional utilizado no servidor do Engine. Uma vez instalado, o aplicativo certbot estará disponível no terminal. A instalação pode ser confirmada com o comando abaixo:

certbot --version

Para não interromper o uso do sistema, o Certbot deve ser utilizado no modo “webroot”, no qual a integração entre ele e o Engine ocorrerá por meio de arquivos. Para utilizar esse modo, deve ser habilitada a integração do Engine por meio de uma das opções abaixo:

No Manage, marcando a opção “Configuration > General > Certbot Integration Enabled”.
Adicionando a flag --EnableCertbot nos argumentos da linha de comando do Engine.
Informando a variável de ambiente NGIN_CERTBOT_ENABLED com o valor 1.

Independentemente da forma escolhida de configuração, o Engine deve ser reiniciado após a configuração para que ela entre em vigor. Após o reinício, o Engine criará um diretório “certbot” no diretório de dados configurado no Engine. No Windows, por padrão o diretório de dados é o de instalação do Engine. O diretório “certbot” criado deverá ser utilizado como o caminho do “webroot” nos comandos do Certbot. O caminho completo desse diretório também pode ser observado no arquivo “engine.log” logo após o reinício do Engine, conforme exemplo abaixo:

10/03 15:42:11 00006900 [INFO] ngin.http.certbot - Certbot integration is enabled. Webroot 
path: D:\Engines\EXAMPLE\certbot

Por uma exigência do Let’s Encrypt, a integração deve ser realizada por um Engine que atenda o protocolo HTTP na porta padrão 80. Portanto, mesmo que haja outros Engines no mesmo servidor, a integração deve ser habilitada apenas no Engine que está servindo a porta 80 e todos os certificados gerenciados pelo Certbot, inclusive os dos outros Engines, devem utilizar o diretório “certbot” do Engine na porta 80 como caminho do “webroot”.

Criação de um novo certificado digital

Para criar um novo certificado, deve ser executado o seguinte comando:

certbot certonly --webroot -w "<diretório de dados do Engine>\certbot" -d app.example.com

Caso seja o primeiro uso do comando, deverá ser informado um email para receber informações sobre renovações urgentes de certificados e avisos de segurança, além de também ser necessário aceitar os termos de uso do Certbot. Podem ser informados um ou vários nomes de domínios que serão incluídos no certificado. Os nomes informados não devem conter indicativo de protocolo ou porta do serviço. Os domínios informados já devem estar registrados no DNS e devem apontar para o endereço IP público de acesso ao Engine. Mais detalhes das opções de linha de comando do certbot podem ser obtidos no manual de utilização do Certbot.

O resultado do comando indicará os caminhos da chave privada e do certificado gerados, similar ao exemplo abaixo:

Successfully received certificate.
Certificate is saved at: C:\Certbot\live\app.example.com\fullchain.pem
Key is saved at:         C:\Certbot\live\app.example.com\privkey.pem

Configuração do certificado digital no Engine

Uma vez gerado o certificado, ele deve ser configurado no Engine. Para isso, deve ser adicionada uma entrada na configuração “Manage > Configuration > Ports” com os seguintes valores:

Port: porta que irá atender as conexões HTTPS. Por padrão, utilize 443 para que o usuário não tenha que informar uma porta na URL de acesso ao sistema.
Protocol: HTTPS.
Certificate File: caminho completo do arquivo contendo o certificado gerado pelo Certbot. No exemplo acima, seria “C:\Certbot\live\app.example.com\fullchain.pem”.
Private Key File: caminho completo do arquivo contendo a chave privada. No exemplo acima, seria “C:\Certbot\live\app.example.com\privkey.pem”.
Enable: deve estar marcado.

Importante: devem ser informados os caminhos para os arquivos contidos no diretório “live” do Certbot, garantindo que o Engine utilize as versões válidas do certificado digital e da chave privada após a renovação automática do certificado.

Renovação automática do certificado digital

Os certificados gerados têm uma validade de 90 dias e por padrão o Certbot automaticamente tentará renovar os certificados 30 dias antes da expiração. Após a renovação do certificado é necessário que o Engine seja reiniciado para que a renovação do certificado seja efetivada.

Para garantir que o processo de renovação ocorra de forma automática, é importante que seja agendado o reinício do Engine em um período inferior ao de renovação do Certbot, como um intervalo de 29 dias ou menos. Caso seja necessário reiniciar o Engine em uma periodicidade maior, deve ser ajustado o parâmetro de configuração renew_before_expiry do Certbot para a o valor desejado de periodicidade de reinício do Engine, acrescido de uma margem de segurança de pelo menos um dia.

As validades dos certificados gerenciados pelo Certbot podem ser consultadas pelo comando abaixo:

certbot certificates

Emissão manual via autoridades certificadoras

O procedimento manual de criação de um certificado digital pode ser resumido nos seguintes passos:

Criação da chave privada.
Criação da solicitação de assinatura do certificado (CSR).
Aquisição do certificado, a partir do CSR.
Emissão do certificado digital.

Estes passos são explicados em maiores detalhes pelas certificadoras. Elas normalmente possuem um passo a passo de acordo com o servidor HTTP utilizado. Devem ser seguidas as instruções dadas para o servidor HTTP Apache, pois o formato dos arquivos gerados para esse servidor são compatíveis com o Engine. Apenas a configuração final do Apache terá que ser ignorada, visto que o procedimento de configuração do certificado no Engine é diferente e explicado a seguir.

A chave privada e a solicitação de assinatura do certificado (CSR) são realizadas normalmente no servidor onde será instalado o certificado utilizando o aplicativo openssl, uma ferramenta externa ao sistema. Uma vez gerado o CSR, ele é enviado para a autoridade certificadora por meio de um formulário e, após as verificações dos dados da empresa, a certificadora disponibiliza um link para o download do certificado digital e dos certificados intermediários. A chave privada, gerada no início do processo, não é enviada à autoridade certificadora durante o processo, pois o seu sigilo é o que garante a segurança do certificado digital. Por esse motivo, é recomendado que o acesso ao arquivo contendo a chave privada seja restrito apenas ao Engine.

Se o certificado for gerado com sucesso, deverão existir os seguintes arquivos:

Chave privada.
Certificado digital da empresa.
Um ou vários certificados intermediários.

O arquivo do certificado digital esperado pelo Engine deve conter o certificado digital da empresa, seguido dos certificados intermediários na ordem de dependência deles. Algumas certificadoras já disponibilizam um arquivo nesse formato, normalmente com o nome “fullchain.pem”. Caso a certificadora não tenha disponibilizado esse arquivo, ele deve ser criado manualmente concatenando os certificados na seguinte ordem:

Certificado digital da empresa.
Certificado digital intermediário que assina o certificado digital da empresa.
Opcionalmente, o certificado intermediário que assina o certificado anterior.

Um exemplo de um certificado concatenado:

Atenção: para criar e copiar o conteúdo dos arquivos de certificados, utilize um editor de textos simples como o Bloco de Notas ou o Nano. Não utilize editores que insiram caracteres de controle dentro do arquivo.

Se todos os passos foram executados com sucesso, deverão ter sido criados os dois arquivos que serão necessários na configuração do Engine:

Chave privada.
Certificado concatenado.

Para concluir, deve ser adicionada uma entrada na configuração “Manage > Configuration > Ports” com os seguintes valores:

Port: porta que irá atender as conexões HTTPS. Por padrão, utilize 443 para que o usuário não tenha que informar uma porta na URL de acesso ao sistema.
Protocol: HTTPS.
Certificate File: caminho completo do arquivo contendo o certificado concatenado.
Private Key File: caminho completo do arquivo contendo a chave privada.
Passphrase: senha do arquivo da chave privada. Deve ser informada apenas se a chave privada tiver sido criada com proteção de senha.
Enable: deve estar marcado.

O Engine deve ser reiniciado para que a nova configuração entre em vigor. É recomendado que o acesso via HTTPS seja testado em vários navegadores.

Configurações avançadas de portas

Na interface de configuração das portas, em “Manage > Configuration > Ports”, há algumas opções avançadas que são utilizadas para atender casos específicos de uso e que normalmente são deixadas em branco. A seguir são detalhadas essas opções e os cenários de uso em que elas são úteis:

Server Address: abre a porta TCP em um endereço IP específico do servidor. Essa opção é útil quando o servidor possui vários Engines instalados e para cada um deles é associado a um endereço IP público distinto. Ao restringir a porta para um IP específico, passa a ser possível que mais de um Engine atenda a mesma porta 443, possibilitando que os usuários acessem o sistema utilizando o endereço https do sistema sem a necessidade de indicar uma porta.
Cipher List: restringe os algoritmos de criptografias aceitos na conexão HTTPS. O formato da configuração atual é descrito no manual Ciphers do OpenSSL. É o mesmo formato empregado nos parâmetros SSLCipherSuite do Apache e ssl_ciphers do nginx, portanto, orientações de configurações para esses servidores podem ser aplicadas no Engine. Caso não seja informado, será utilizada uma lista padrão definida pelo sistema, que busca seguir as práticas recomendadas do mercado. Essa configuração deve ser utilizada quando for necessário utilizar uma lista de algoritmos mais restrita que a definida pelo sistema, com o objetivo de atender algum requisito técnico específico do ambiente, ou para eliminar o uso de algum algoritmo que tenha sido comprometido e que por algum motivo o Engine não possa ser atualizado para uma versão que tenha a configuração padrão revista.
Disable On Startup: indica que a porta deve ser desativada enquanto o Engine estiver carregando o cache local. Por padrão, o Engine exibe uma interface com o progresso da inicialização do cache local. Ao ativar essa opção, essa interface não será exibida e o Engine se comportará como se estivesse offline. Essa opção é útil quando o Engine está sob um balanceador de carga e deseja-se evitar que essa instância seja utilizada pelo balanceador enquanto ela não estiver de fato apta a atender os clientes. Dessa forma, evita-se que os usuários finais visualizem a interface de progresso de construção do cache local, pois eles serão redirecionados para uma outra instância já inicializada.

Dúvidas frequentes

O que fazer se a autoridade certificadora emitir um certificado no formato PFX?

Caso a chave privada e o certificado tenham sido combinadas em um arquivo binário PFX, eles podem ser extraídos utilizando a ferramenta openssl com os comandos abaixo:

# Extrai a chave privada
openssl pkcs12 -in filename.pfx -nocerts -out key.pem

# Extrai o certificado digital
openssl pkcs12 -in filename.pfx -clcerts -nokeys -out cert.pem

# Opcionalmente, remove o passphrase
openssl rsa -in key.pem -out server.key

Última atualização em 11 Mar 2022