Introdução ao cliente SSL Let's Encrypt acme.sh

Acme.sh é um cliente do protocolo ACME simples, poderoso e fácil de usar, escrito puramente em Shell (linguagem de shell Unix), compatível com os shells bash, dash e sh. Ele ajuda a gerenciar a instalação, renovação e revogação de certificados SSL. Suporta os protocolos ACME versão 1 e versão 2, bem como certificados curinga ACME v2. Sendo um cliente ACME sem dependências, torna-se ainda melhor. Você não precisa baixar e instalar a internet inteira para fazê-lo funcionar. A ferramenta não requer acesso root ou sudo, mas é recomendado usar root.

Acme.sh suporta os seguintes métodos de validação que você pode usar para confirmar a propriedade do domínio:

Modo Webroot
Modo Autônomo
Modo Autônomo tls-alpn
Modo Apache
Modo Nginx
Modo DNS
Modo Alias DNS
Modo Stateless

O que é Let’s Encrypt

Let’s Encrypt (LE) é uma autoridade certificadora (CA) que oferece certificados SSL/TLS gratuitos e automatizados, com o objetivo de criptografar toda a web. Se você possui um nome de domínio e tem acesso shell ao seu servidor, pode utilizar o Let’s Encrypt para obter um certificado confiável sem custo. O Let’s Encrypt pode emitir certificados SAN para até 100 nomes de host ** e certificados curinga. Todos os certificados são válidos por um período de 90 dias.

Uso do Acme.sh e comandos básicos

Nesta seção, vou mostrar alguns dos comandos e opções mais comuns do acme.sh.

Instalação do Acme.sh

Você tem algumas opções para instalar o acme.sh.

Instalar da web via curl ou wget:

curl https://get.acme.sh | sh  
source ~/.bashrc

wget -O - https://get.acme.sh | sh  
source ~/.bashrc

Instalar do GitHub:

curl https://raw.githubusercontent.com/Neilpang/acme.sh/master/acme.sh | INSTALLONLINE=1 sh

wget -O - https://raw.githubusercontent.com/Neilpang/acme.sh/master/acme.sh | INSTALLONLINE=1 sh

Clonar o Git e instalar:

git clone https://github.com/Neilpang/acme.sh.git  
cd ./acme.sh  
./acme.sh --install  
source ~/.bashrc

O instalador realizará 3 ações:

Criar e copiar acme.sh para seu diretório home ( $HOME): ~/.acme.sh/. Todos os certificados também serão colocados nesta pasta.
Criar um alias para: acme.sh=~/.acme.sh/acme.sh.
Criar uma tarefa cron diária para verificar e renovar os certificados, se necessário.

Instalação avançada:

git clone https://github.com/Neilpang/acme.sh.git  
cd acme.sh  
./acme.sh --install \  
          --home ~/myacme \  
          --config-home ~/myacme/data \  
          --cert-home ~/mycerts \  
          --accountemail "[email protected]" \  
          --accountkey ~/myaccount.key \  
          --accountconf ~/myaccount.conf \  
          --useragent "este é meu cliente."

Você não precisa definir todas as opções, apenas aquelas que você considera importantes.

Opções explicadas:

--home é um diretório personalizado para instalar acme.sh. Por padrão, ele é instalado em ~/.acme.sh.
--config-home é uma pasta gravável, acme.sh escreverá todos os arquivos (incluindo cert/chaves, configurações) lá. Por padrão, está em --home.
--cert-home é um diretório personalizado para salvar os certificados que você emite. Por padrão, é salvo em --config-home.
--accountemail é o e-mail usado para registrar a conta no Let’s Encrypt, você receberá o e-mail de aviso de renovação aqui. O padrão é vazio.
--accountkey é o arquivo que salva sua chave privada da conta. Por padrão, é salvo em --config-home.
--useragent é o valor do cabeçalho user-agent usado para enviar ao Let’s Encrypt.

Após a conclusão da instalação, você pode verificar verificando a versão do acme.sh:

acme.sh --version  
# v2.8.1

O programa possui muitos comandos e parâmetros que podem ser usados. Para obter ajuda, você pode executar:

acme.sh --help

Emitir um certificado SSL

Se você já tem um servidor web em execução, deve usar o modo webroot. Você precisará de acesso de gravação à pasta raiz da web. Aqui estão alguns comandos de exemplo que podem ser usados para obter o certificado via modo webroot:

Domínio único + Modo Webroot:

acme.sh --issue -d example.com --webroot /var/www/example.com

Múltiplos domínios no mesmo certificado + Modo Webroot:

acme.sh --issue -d example.com -d www.example.com -d mail.example.com --webroot /var/www/example.com

Certificado ECC/ECDSA de domínio único + Modo Webroot:

acme.sh --issue -d example.com --webroot /var/www/example.com --keylength ec-256

Múltiplos domínios no mesmo certificado ECC/ECDSA + Modo Webroot:

acme.sh --issue -d example.com -d www.example.com -d mail.example.com --webroot /var/www/example.com --keylength ec-256

Valores válidos para --keylength são: 2048 (padrão), 3072, 4096, 8192 ou ec-256, ec-384.

Se você não tem um servidor web, talvez esteja em um servidor SMTP ou FTP, a porta 80 está livre, então você pode usar o modo autônomo. Se quiser usar este modo, você precisará instalar as ferramentas socat primeiro.

Domínio único + Modo Autônomo:

acme.sh --issue -d example.com --standalone

Múltiplos domínios no mesmo certificado + Modo Autônomo:

acme.sh --issue -d example.com -d www.example.com -d mail.example.com --standalone

Se você não tem um servidor web, talvez esteja em um servidor SMTP ou FTP, a porta 443 está livre. Você pode usar o modo autônomo TLS ALPN. Acme.sh possui um servidor web TLS autônomo embutido, ele pode escutar na porta 443 para emitir o certificado.

Domínio único + Modo Autônomo TLS ALPN:

acme.sh --issue -d example.com --alpn

Múltiplos domínios no mesmo certificado + Modo Autônomo TLS ALPN:

acme.sh --issue -d example.com -d www.example.com --alpn

Integração automática da API DNS

Se seu provedor de DNS possui uma API, o acme.sh pode usar a API para adicionar automaticamente o registro DNS TXT para você. Seu certificado será emitido e renovado automaticamente. Nenhum trabalho manual é necessário. Antes de solicitar os certificados, configure suas chaves de API e e-mail. Atualmente, o acme.sh possui integração automática de DNS com cerca de 60 provedores de DNS nativamente e pode utilizar a ferramenta Lexicon para aqueles que não são suportados nativamente.

Domínio único + Modo API DNS CloudFlare:

export CF_Key="sdfsdfsdfljlbjkljlkjsdfoiwje"  
export CF_Email="[email protected]"  
acme.sh --issue -d example.com --dns dns_cf

Certificado curinga + Modo API DNS CloudFlare:

export CF_Key="sdfsdfsdfljlbjkljlkjsdfoiwje"  
export CF_Email="[email protected]"  
acme.sh --issue -d example.com -d '*.example.com' --dns dns_cf

Se seu provedor de DNS não suportar nenhum acesso à API, você pode adicionar o registro TXT manualmente.

acme.sh --issue --dns -d example.com -d www.example.com -d cp.example.com

Você deve obter uma saída como abaixo:

Adicione o seguinte registro txt:
Domínio:_acme-challenge.example.com
Valor Txt:9ihDbjYfTExAYeDs4DBUeuTo18KBzwvTEjUnSwd32-c

Adicione o seguinte registro txt:
Domínio:_acme-challenge.www.example.com
Valor Txt:9ihDbjxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Por favor, adicione esses registros txt aos domínios. Aguardando o DNS ter efeito.

Então, basta executar novamente com o argumento renew:

acme.sh --renew -d example.com

Lembre-se de que este é o modo manual de DNS e você não pode renovar automaticamente seus certificados. Você terá que adicionar um novo registro TXT ao seu domínio manualmente quando for hora de renovar os certificados. Portanto, use o modo API DNS em vez disso, pois ele pode ser automatizado.

Instalar certificado SSL Let’s Encrypt

Após os certificados serem gerados, você provavelmente desejará instalar/copiar os certificados emitidos para o local correto no disco. Você deve usar este comando para copiar os certificados para os arquivos de destino, não use os arquivos de certificados na pasta ~/.acme.sh/, eles são para uso interno apenas, a estrutura da pasta pode mudar no futuro. Antes da instalação, crie um diretório sensato para armazenar seus certificados. Isso pode ser /etc/letsencrypt, /etc/nginx/ssl ou /etc/apache2/ssl, por exemplo, dependendo do seu software de servidor web e suas próprias preferências para armazenar itens relacionados ao SSL.

Exemplo Apache:

acme.sh --install-cert \  
        --domain example.com \   
        --cert-file /path/to/cert/cert.pem \  
        --key-file /path/to/keyfile/key.pem \  
        --fullchain-file /path/to/fullchain/fullchain.pem \  
        --reloadcmd "sudo systemctl reload apache2.service"

Exemplo Nginx:

acme.sh --install-cert \  
        --domain example.com \   
        --cert-file /path/to/cert/cert.pem \  
        --key-file /path/to/keyfile/key.pem \  
        --fullchain-file /path/to/fullchain/fullchain.pem \  
        --reloadcmd "sudo systemctl reload nginx.service"

Os parâmetros são armazenados no arquivo de configuração .acme.sh, então você precisa configurá-los corretamente para o seu sistema, pois este arquivo é lido quando a tarefa cron executa a renovação. “reloadcmd” depende do seu sistema operacional e sistema de inicialização.

Renovar os certificados SSL Let’s Encrypt

Você não precisa renovar os certificados manualmente. Todos os certificados serão renovados automaticamente a cada 60 dias.

No entanto, você também pode forçar a renovação de um certificado:

acme.sh --renew -d example.com --force

ou, para certificado ECC:

acme.sh --renew -d example.com --force --ecc

Como atualizar o acme.sh

Você pode atualizar o acme.sh para o código mais recente com:

acme.sh --upgrade

Você também pode habilitar a atualização automática:

acme.sh --upgrade --auto-upgrade

Então o acme.sh será mantido atualizado automaticamente.

É isso. Se você ficar preso em algo, visite a página wiki do acme.sh em https://github.com/Neilpang/acme.sh/wiki.