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 usoO que o step-ca lhe dáSecção
Todos os dispositivos a confiar nos teus certificadosUma raiz para instalar, uma vezConfiar na raiz
HTTPS interno para tudo o que fale ACMEO mesmo protocolo da Let’s Encrypt, para nomes internosHTTPS interno com ACME
Serviços sem cliente ACMECertificados que se renovam sozinhos com um temporizadorServiços que não falam ACME
Telemóveis e outros certificados de clienteChaves que um dispositivo guarda para entrar, e uma forma de as revogarArtigo próprio: as predefinições jogam contra
Logins SSHCertificados em vez de authorized_keysArtigo 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ávelFaz
DOCKER_STEPCA_INIT_NAMEO nome do emissor em cada certificado
DOCKER_STEPCA_INIT_DNS_NAMESOs nomes em que a CA responde
DOCKER_STEPCA_INIT_ACME=trueAcrescenta um provisionador ACME para HTTPS interno
DOCKER_STEPCA_INIT_SSH=trueCria 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 ...
ProvisionadorTipoAssina
adminJWKTudo o que pedires com a palavra-passe dele
acmeACMECertificados para clientes que provam ser donos do nome
sshpopSSHPOPRenovaçõ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.

Uma CA, cinco usoscontentor step-caRaiz, intermédiauma raiz em que confiaracmeadminsshpopCRLprovisionadoresCada dispositivoconfia na raiz, uma vezCaddy, ACME24 h, renova-se sozinhoSem ACMEstep ca renew --daemonTelemóveis1 ano, revogado por CRLSSHartigo próprio
Uma raiz, em que se confia uma vez, e um provisionador para cada forma de entrar. Os clientes ACME e os serviços renovados vivem bem com a predefinição de 24 horas; os telemóveis precisam que ela mude; o SSH tem artigo próprio.

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-passeDesbloqueiaOnde acaba
secrets/passwordAs chaves da raiz e da intermédiaNo volume, usada sempre que a CA arranca
Palavra-passe do provisionadorO provisionador admin, que assina cada certificado que pediresNo 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çãoResultado
Desafiotls-alpn-01, respondido pelo Caddy na porta 443
EmissorHome CA Intermediate CA
Validade24 horas, das 17:31 às 17:32 do dia seguinte
RenovaçãoTrabalho 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érieVálido até
Emitido241943140971…2026-10-10 17:33:03
Depois de step ca renew206409156462…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.


  1. 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». ↩︎

  2. Let’s Encrypt — Certificate Transparency logs — «Let’s Encrypt submits all certificates we issue to CT logs.» ↩︎

  3. 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». ↩︎ ↩︎

  4. smallstep/certificates — docker/entrypoint.sh — gera ficheiros password e provisioner_password separados, escreve a palavra-passe do provisionador uma vez e destrói-a com shred; uma palavra-passe fornecida é escrita nos dois. ↩︎ ↩︎ ↩︎

  5. Smallstep — step certificate install — instala um certificado raiz no repositório de confiança do sistema. ↩︎

  6. Smallstep — ACME basics — o provisionador ACME do step-ca e os tipos de desafio que suporta. ↩︎

  7. 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»; --exec permite «certificate reloads on your services». ↩︎