Porquê ter a tua própria CA
Olha para o que há hoje numa rede doméstica. Um NAS, Proxmox, Home Assistant, uma impressora, a página de administração de um router. Cada um deles serve HTTPS com um certificado autoassinado. Cada browser que lá vai dispara um aviso. As pessoas clicam para passar à frente. Depois clicam no seguinte, e no outro a seguir, até que passar à frente de um aviso de certificado é simplesmente o que se faz. É esse o hábito de que um atacante precisa.
Uma CA pública não resolve isto. A Let’s Encrypt não emite para localhost «because nobody uniquely owns it»1, e o mesmo vale para qualquer nome que só exista dentro de casa. Mesmo para um domínio verdadeiro, cada certificado que emite vai para os registos públicos de Certificate Transparency2. Pede um para nas.yourname.uk e o nome do teu NAS passa a ser do domínio público.
A tua própria CA resolve as duas coisas. Assina os nomes que usares lá dentro. Nada é publicado em lado nenhum. Assim que cada dispositivo confia na sua raiz, os avisos param, e um aviso volta a querer dizer alguma coisa.
O step-ca é a CA de código aberto da Smallstep, e corre num só contentor. Tudo aqui foi corrido no step-ca 0.30.2 em Podman, com o Caddy 2.11.7 e o nginx 1.30.5 como clientes.
| Caso de uso | O que o step-ca lhe dá | Secção |
|---|---|---|
| Todos os dispositivos a confiar nos teus certificados | Uma raiz para instalar, uma vez | Confiar na raiz |
| HTTPS interno para tudo o que fale ACME | O mesmo protocolo da Let’s Encrypt, para nomes internos | HTTPS interno com ACME |
| Serviços sem cliente ACME | Certificados que se renovam sozinhos com um temporizador | Serviços que não falam ACME |
| Telemóveis e outros certificados de cliente | Chaves que um dispositivo guarda para entrar, e uma forma de as revogar | Artigo próprio: as predefinições jogam contra |
| Logins SSH | Certificados em vez de authorized_keys | Artigo próprio: uma configuração diferente |
Dois destes têm artigos próprios, porque cada um é uma configuração à parte. Certificados de cliente a partir do step-ca trata dos telemóveis e do mTLS, onde há cinco predefinições a mudar. Logins SSH assinados pelo step-ca trata do SSH, que usa chaves diferentes e ficheiros diferentes em cada máquina.
Arrancar com ela
A imagem inicializa-se sozinha no primeiro arranque a partir de umas quantas variáveis de ambiente3. Duas delas decidem coisas que depois não se podem mudar sem começar de novo, por isso define-as no primeiro dia.
| Variável | Faz |
|---|---|
DOCKER_STEPCA_INIT_NAME | O nome do emissor em cada certificado |
DOCKER_STEPCA_INIT_DNS_NAMES | Os nomes em que a CA responde |
DOCKER_STEPCA_INIT_ACME=true | Acrescenta um provisionador ACME para HTTPS interno |
DOCKER_STEPCA_INIT_SSH=true | Cria também chaves de CA SSH para anfitriões e utilizadores |
Os interruptores de ACME e SSH são lidos pelo entrypoint da imagem4. Liga-os já, mesmo que hoje só queiras um deles. Acrescentar SSH mais tarde obriga a construir uma CA nova.
podman run -d --name step-ca \
-v step:/home/step \
-p 9000:9000 \
-e DOCKER_STEPCA_INIT_NAME="Home CA" \
-e DOCKER_STEPCA_INIT_DNS_NAMES="localhost,ca.home.example" \
-e DOCKER_STEPCA_INIT_ACME=true \
-e DOCKER_STEPCA_INIT_SSH=true \
docker.io/smallstep/step-ca:0.30.2
Constrói uma raiz, uma intermédia assinada por essa raiz, as chaves SSH e três provisionadores, e depois serve na porta 9000:
X.509 Root Fingerprint: cd2f8d4c60af32a0a534781cd63b4e2a9ce362e2c1ae5983b56a370bfa2c2489
SSH Host CA Key: ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAy...
SSH User CA Key: ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAy...
Serving HTTPS on :9000 ...
| Provisionador | Tipo | Assina |
|---|---|---|
admin | JWK | Tudo o que pedires com a palavra-passe dele |
acme | ACME | Certificados para clientes que provam ser donos do nome |
sshpop | SSHPOP | Renovações de certificados de anfitrião SSH |
O provisionador é a ideia que a CA tem de «quem está a pedir». Cada um tem as suas regras, e a maior parte do que se segue é definir essas regras.
Fixa a versão. latest era a 0.30.2 no dia em que isto foi escrito, e uma CA é a última coisa que queres ver mudar debaixo dos pés num pull.
Duas palavras-passe, não uma
O guia de Docker da Smallstep diz que uma única palavra-passe gerada serve para «the encrypted CA keys and the default CA provisioner», guardada em secrets/password3. Nesta imagem não é isso que acontece. Tenta emitir um certificado com essa palavra-passe e o provisionador recusa-a:
failed to decrypt JWE: invalid password
O próprio entrypoint da imagem explica porquê. Gera duas palavras-passe aleatórias, uma para as chaves da CA e outra para o provisionador. A do provisionador é escrita no log uma vez e depois destruída com shred4:
echo "👉 Your CA administrative password is: $(< $STEPPATH/provisioner_password )"
...
shred -u $STEPPATH/provisioner_password
| Palavra-passe | Desbloqueia | Onde acaba |
|---|---|---|
secrets/password | As chaves da raiz e da intermédia | No volume, usada sempre que a CA arranca |
| Palavra-passe do provisionador | O provisionador admin, que assina cada certificado que pedires | No log do primeiro arranque, e em mais lado nenhum |
Por isso lê o log no primeiro arranque e guarda essa segunda palavra-passe num sítio seguro. Perde-a e não consegues emitir mais nenhum certificado sem tirares o provisionador à mão. Define DOCKER_STEPCA_INIT_PASSWORD antes do primeiro arranque se preferires escolher tu uma; o entrypoint usa-a então para as duas4.
Confiar na raiz
Nada confia na tua CA até lhe dizeres para confiar. Uma máquina Debian a pedir ao Caddy uma página assinada pelo step-ca:
$ curl https://nas.home.example/
curl: (60) SSL certificate problem: unable to get local issuer certificate
Copia a raiz para lá, e o mesmo pedido passa:
cp root_ca.crt /usr/local/share/ca-certificates/home-ca.crt
update-ca-certificates
$ curl https://nas.home.example/
internal service, certificate from step-ca
O trabalho é só este. Uma vez por dispositivo. step certificate install faz o mesmo em qualquer sistema onde corra5. Só a raiz vai para um repositório de confiança. A intermédia viaja com cada certificado, e um telemóvel que vá apresentar um certificado de cliente também precisa dela, o que é tratado no artigo sobre certificados de cliente.
Trata a raiz como a chave da porta da rua que agora é. Qualquer coisa que tenha a chave privada da raiz pode cunhar um certificado para qualquer nome, e todos os dispositivos que confiam nela vão acreditar.
HTTPS interno com ACME
ACME é o protocolo que a Let’s Encrypt usa, e o step-ca fala-o para nomes internos6. Tudo o que tenha um cliente ACME obtém certificados internos da mesma forma que obtém os públicos, renovações incluídas. Para o Caddy são duas linhas globais:
{
acme_ca https://ca.home.example:9000/acme/acme/directory
acme_ca_root /etc/caddy/root_ca.crt
}
nas.home.example {
reverse_proxy 192.0.2.30:5000
}
O que o Caddy registou no primeiro arranque:
"msg":"trying to solve challenge","identifier":"nas.home.example","challenge_type":"tls-alpn-01"
"msg":"certificate obtained successfully","identifier":"nas.home.example"
| Verificação | Resultado |
|---|---|
| Desafio | tls-alpn-01, respondido pelo Caddy na porta 443 |
| Emissor | Home CA Intermediate CA |
| Validade | 24 horas, das 17:31 às 17:32 do dia seguinte |
| Renovação | Trabalho do próprio Caddy, nada a configurar |
Um certificado de 24 horas parece alarmante. Não é. Um cliente ACME renova bem antes de expirar, todos os dias, sem ninguém metido nisso. Uma chave roubada vale um dia. É a predefinição à volta da qual o step-ca foi construído, e aqui está exatamente certa.
O desafio precisa, isso sim, que a CA chegue ao nome que está a assinar. O step-ca tem de resolver nas.home.example e ligar-se a ele na porta 443 para tls-alpn-01, ou na porta 80 para http-01. Um DNS interno que os dois lados usem é a coisa a acertar primeiro.
Serviços que não falam ACME
Há muito equipamento sem cliente ACME: a interface web de um hipervisor, uma impressora, um aparelho antigo. Para esses, emite o certificado com o provisionador admin e renova-o com step ca renew:
step ca certificate proxmox.home.example pve.crt pve.key
step ca renew --force pve.crt pve.key
| Número de série | Válido até | |
|---|---|---|
| Emitido | 241943140971… | 2026-10-10 17:33:03 |
Depois de step ca renew | 206409156462… | 2026-10-10 17:33:06 |
Número de série novo, 24 horas frescas, e nenhuma palavra-passe pedida. O certificado atual prova quem está a pedir, e é esse o objetivo: a renovação não precisa de nenhum segredo guardado na máquina além da chave que já lá está. Precisa, isso sim, que o certificado ainda seja válido, por isso uma renovação que falhe a janela obriga a emitir de novo à mão.
Deixado a correr, renova-se sozinho. --daemon renova a dois terços da validade por predefinição, e --exec corre um comando depois de cada renovação, que é onde entra o reload7:
step ca renew --daemon --exec "systemctl reload nginx" pve.crt pve.key
Corre isso a partir de uma unidade systemd e a máquina trata de si própria. Esquece-te disso, e em 24 horas o serviço atira o mesmo aviso de que te querias livrar.
A CA é a parte fácil
Pôr o step-ca a correr levou um comando. Pôr uma máquina Debian a confiar nele levou dois. O Caddy precisou de duas linhas e nunca mais pediu nada. É a parte que as pessoas adiam durante anos, a viver com um aviso do browser em cada página interna, e é o trabalho mais barato desta lista.
O que custa é tudo o que um certificado toca depois de emitido: a raiz em cada dispositivo, as renovações que ninguém vigia, o único serviço que não fala ACME e de que alguém se tem de lembrar. Nada disto é difícil. Tudo isto é o tipo de trabalho que só fica bem feito quando alguém é dono dele.
Uma rede doméstica é uma propriedade pequena. Merece o mesmo que uma a sério recebe: uma raiz, guardada com cuidado, em que se confia de propósito, e um aviso que quer dizer alguma coisa quando aparece. Como tal, a CA não é a parte esperta. A parte esperta é nunca mais clicar para passar à frente.
Let’s Encrypt — Certificates for localhost — não pode emitir para «localhost» «because nobody uniquely owns it, and it’s not rooted in a top level domain». ↩︎
Let’s Encrypt — Certificate Transparency logs — «Let’s Encrypt submits all certificates we issue to CT logs.» ↩︎
Smallstep — Run a private CA in Docker — as variáveis
DOCKER_STEPCA_INIT_*; diz que a palavra-passe gerada serve para «the encrypted CA keys and the default CA provisioner». ↩︎ ↩︎smallstep/certificates — docker/entrypoint.sh — gera ficheiros
passwordeprovisioner_passwordseparados, escreve a palavra-passe do provisionador uma vez e destrói-a com shred; uma palavra-passe fornecida é escrita nos dois. ↩︎ ↩︎ ↩︎Smallstep — step certificate install — instala um certificado raiz no repositório de confiança do sistema. ↩︎
Smallstep — ACME basics — o provisionador ACME do step-ca e os tipos de desafio que suporta. ↩︎
Smallstep — step ca renew — com
--daemon, «By default, it will renew the certificate before 2/3 of the validity period of the certificate has elapsed»;--execpermite «certificate reloads on your services». ↩︎