# Certificados TLS no Webship: A CA ACME Incorporada
Um certificado TLS realiza duas funções: ele ajuda a criptografar uma conexão e informa ao cliente com qual identidade está se comunicando. A criptografia pode ser forte enquanto a decisão de confiança está errada para o público. É por isso que a automação de certificados deve começar com uma pergunta: quem deve confiar neste site?
O Webship 1.4.0 faz essa escolha de forma independente para cada site configurado. Um site público pode usar um certificado ACME confiável pelo navegador, um serviço interno pode usar a autoridade certificadora privada incorporada do Webship, e um site com uma PKI existente pode manter arquivos de certificado gerenciados pelo operador. Todos eles podem compartilhar um processo do Webship sem compartilhar uma chave privada ou um limite de confiança.
Quatro modos automáticos de certificado, selecionados por site
O campo certificate_mode pertence a cada entrada [[sites]]. Ele não é um interruptor global.
| Modo | Fonte confiável | Melhor ajuste | Caminho de validação | | --- | --- | --- | --- | | per_site | Armazenamentos de confiança de navegador e sistema operacional públicos | Um site público com um hostname exato | ACME público com TLS-ALPN-01 | | frota | Armazenamentos de confiança do navegador público e do sistema operacional | Grandes conjuntos de nomes de terceiro e quarto nível sob domínios registrados explícitos | ACME público com DNS-01 e fragmentos de certificado estáveis | | incorporado | Um root Webship privado instalado pelo operador | Serviços internos, dispositivos gerenciados, frotas privadas e ambientes de teste | Emissão em processo; sem desafio externo | | compartilhado | Armazenamentos de confiança públicos de navegadores e sistemas operacionais | Implantações legadas que usam intencionalmente um grupo público multi-SAN | ACME público com TLS-ALPN-01 |
O padrão é per_site. Ele solicita um certificado público para o nome exato do site. O modo Fleet é a opção pública escalável para muitos subdomínios profundos. O modo Embedded usa a CA privada em processo do Webship. O modo Shared continua disponível para compatibilidade, mas não é o padrão.
Um certificado e chave completos sob [sites.tls] sempre têm prioridade sobre a emissão automática para esse site.
O que significa “ACME CA incorporado”
A seção de configuração é chamada [acme_ca], mas a CA incorporada não é um serviço ACME público ou acessível pela rede. Não expõe nenhum endpoint de diretório, não aceita inscrição remota, não chama nenhuma API de registrador e não realiza nenhum desafio de prova de controle.
Em vez disso, o Webship mantém todo o caminho de emissão privada em um único processo:
- O site seleciona certificate_mode = "embedded".
- O Webship carrega ou cria a identidade raiz privada no diretório de estado configurado.
- O Webship gera uma nova chave privada para o site.
- O root incorporado assina um certificado de folha para esse nome exato.
- O Webship valida a identidade concluída antes de instalá-la no resolvedor TLS ao vivo.
- O certificado está então disponível para todos os protocolos habilitados para esse site.
Um desafio de rede no estilo ACME só provaria o Webship para si mesmo, então o caminho incorporado deliberadamente não possui protocolo de rede. A seção [acme_ca] é um estado privado de PKI: ela define onde a raiz está localizada e por quanto tempo os certificados folha emitidos permanecem válidos.
Configure um certificado incorporado para um site
Esta é a forma mínima para um site privado:
~~~toml listen = "0.0.0.0:443"
[tls] unknown_sni = "rejeitar"
[tls_automático] habilitado = verdadeiro cache_dir = "/var/lib/webship/acme"
[acme_ca] state_dir = "/var/lib/webship/acme-ca" leaf_validity_days = 90
[[sites]] domínio = "service.internal.example" root = "/srv/service" certificate_mode = "embedded"
[sites.protocolos] h1 = verdadeiro h2 = verdadeiro h3 = verdadeiro ~~~
A identidade raiz é criada de forma preguiçosa quando um site incorporado precisa dela pela primeira vez. O Webship persiste a chave raiz com permissões restritivas em state_dir. O certificado raiz tem uma validade de dez anos; a validade da folha é controlada por leaf_validity_days.
Trate ambos os locais de armazenamento como estado de produção:
- O cache ACME mantém identidades de site gerenciadas automaticamente.
- O diretório de estados do CA incorporado contém a identidade raiz privada.
- A conta de serviço precisa de acesso, mas os usuários do aplicativo não.
- Os backups devem preservar a confidencialidade e as permissões de arquivos.
- Produção, desenvolvimento e testes devem usar raízes separadas e diretórios separados.
Excluir o diretório raiz não "reinicia o TLS." Isso cria uma nova âncora de confiança. Clientes que confiam na raiz antiga rejeitarão certificados emitidos pelo substituto até que seus repositórios de confiança sejam atualizados.
Fidúcia privada é intencional
Certificados da CA incorporada não são confiáveis automaticamente por navegadores públicos ou sistemas operacionais. Eles se tornam confiáveis somente depois que o operador instala o certificado raiz Webship exportado no armazenamento de confiança do cliente.
Isso torna o modo incorporado uma boa opção para:
- laptops e telefones gerenciados pela empresa cadastrados através do gerenciamento de dispositivos;
- tráfego interno de serviço para serviço com um pacote CA explícito;
- aparelhos privados e frotas de borda controladas;
- ambientes de desenvolvimento e teste que devem exercitar o comportamento real do TLS;
- redes desconectadas que não podem depender de uma CA pública.
Não é o modo correto para um site público comum cujos visitantes usam navegadores não gerenciados. Use emissão por_site pública para um nome público exato, emissão de frota para grandes conjuntos de subdomínios públicos, compartilhado apenas para uma implantação deliberada legada de múltiplos SAN, ou arquivos manuais de uma PKI já confiável.
Distribua apenas o certificado raiz aos clientes. Nunca distribua a chave privada raiz. A posse dessa chave dá ao seu detentor autoridade para emitir identidades confiáveis por todos os clientes cadastrados.
Certificados públicos e privados podem coexistir
O Webship 1.4.0 pode misturar estratégias de certificado no mesmo listener:
~~~toml listen = "0.0.0.0:443"
[tls] unknown_sni = "rejeitar"
[tls_automático] habilitado = verdadeiro directory_url = "https://acme-v02.api.letsencrypt.org/directory" cache_dir = "/var/lib/webship/acme" contatos = ["mailto:ops@example.com"] aceitar_termos_de_serviço = true
[acme_ca] state_dir = "/var/lib/webship/acme-ca" leaf_validity_days = 90
[[sites]] domínio = "www.exemplo.com" root = "/srv/public" certificate_mode = "por_site"
[[sites]] domínio = "control.internal.example" root = "/srv/control" certificate_mode = "embedded"
[[sites]] domínio = "payments.example.com" root = "/srv/pagamentos"
[sites.tls] cert = "/etc/webship/payments-fullchain.pem" key = "/etc/webship/payments-private-key.pem" ~~~
Aqui, www.example.com recebe seu próprio certificado ACME público. control.internal.example recebe um certificado privado da CA incorporada. payments.example.com permanece sob a PKI externa do operador porque seus arquivos explícitos têm prioridade.
O diretório público ACME é ignorado por sites incorporados. A raiz incorporada nunca assina o site público. O site manual nunca é inscrito silenciosamente em nenhum dos fluxos de trabalho automáticos.
Um resolvedor de certificado para H1, H2, H3 e WebTransport
A seleção de certificado acontece durante o handshake TLS, antes que uma solicitação HTTP exista. O Webship usa o nome do servidor ClientHello para selecionar a identidade do site e, em seguida, negocia o protocolo da aplicação.
- HTTP/1.1 e HTTP/2 usam TLS sobre TCP.
- HTTP/3 e WebTransport usam TLS dentro do QUIC sobre UDP.
- Uma identidade de site válida pode servir para todos os protocolos habilitados.
- O HTTP/3 também requer acessibilidade via UDP; H1 e H2 usam o caminho TCP.
- Alt-Svc pode anunciar H3 enquanto preserva um fallback TCP.
TCP, TLS e QUIC usam o mesmo modelo de identidade sensível ao site. Nomes exatos têm precedência, o curinga válido mais longo prevalece onde certificados curinga estão configurados, e o SNI de nome desconhecido pode ser rejeitado em vez de receber um certificado padrão não relacionado.
Use unknown_sni = "reject" em um listener multi-site quando um hostname não reconhecido deve falhar fechado. Teste nomes reconhecidos, nomes não reconhecidos e seu comportamento esperado sem SNI antes do lançamento em produção.
Girar identidades incorporadas sem uma lacuna de serviço
O Webship expõe o estado do certificado e mutações controladas através de seu servidor MCP autenticado e vinculado ao loopback:
- webship.tls.get_status informa o resolvedor de certificado ativo e o estado de renovação.
- webship.tls.reissue_certificate reemite imediatamente um site gerenciado automaticamente apenas quando esse site usa o modo incorporado.
- webship.tls.reload recarrega o estado do certificado através do caminho TLS protegido normal.
- webship.acme_ca.status relata se a CA privada está selecionada, seu diretório de estado, tempo de vida das folhas, contagem de emissões, contagem de revogações e amostra recente de domínios.
- webship.sites.apply adiciona ou remove sites em relação a uma versão de configuração fixada.
Para uma reemissão incorporada, o Webship cria e valida a substituição antes de colocá-la em serviço. A identidade válida atual continua sendo usada até que a nova identidade esteja pronta. A identidade aposentada só é registrada após a instalação da substituição.
A operação de reemissão imediata rejeita intencionalmente certificados públicos por_site. A renovação pública deve permanecer dentro do ciclo de vida público do ACME, em vez de ser confundida com a assinatura privada em processo. A participação em modo compartilhado também está congelada para reinício porque alterar um grupo multi-SAN reconstrói o limite de identidade.
MCP é uma superfície de controle privilegiada. Mantenha-a em loopback, exija TLS e um token de portador forte, use um túnel autenticado para administração remota e audite cada mutação.
Limites de falha que importam
Um sistema de certificados seguro deve falhar na direção correta.
- Um site incorporado recém-configurado não recebe a identidade de outro site enquanto a emissão estiver pendente.
- Uma substituição inválida não é instalada sobre um certificado em funcionamento.
- Arquivos manuais explícitos impedem a propriedade automática desse site.
- SNI com nome desconhecido pode ser rejeitada antes do roteamento HTTP.
- A CA incorporada permanece privada e não possui ponto de inscrição remoto.
- Identidades públicas e incorporadas usam caminhos de cache separados dentro do estado TLS automático.
Um aviso de que a CA incorporada não está inicializada significa que o Webship não conseguiu ativar o diretório de estado configurado. Corrija a propriedade, permissões, persistência ou disponibilidade de armazenamento antes de enviar tráfego para o site afetado. Não contorne o erro copiando a chave root de outro ambiente.
Lista de verificação de produção
Antes de ativar o modo incorporado:
- Identifique toda população de clientes que deve confiar no site.
- Crie um processo controlado para exportar e instalar o certificado raiz.
- Use um estado raiz separado para produção, desenvolvimento e testes.
- Persistir e proteger o diretório de estado da CA incorporada e o cache TLS automático.
- Execute o Webship sob uma conta de serviço dedicada com acesso apenas ao material de chave necessário.
- Selecione certificate_mode em cada site cujo limite de confiança deve ser explícito.
- Defina e teste a política de SNI desconhecido.
- Habilite H1, H2 e H3 deliberadamente e verifique tanto os caminhos TCP quanto UDP.
- Exercício de reemissão, reinício, backup, restauração e validação de confiança do cliente fora da produção.
- Execute webship --check-config antes do lançamento, depois verifique emissor, nomes, validade, cadeia e protocolos negociados a partir de um cliente real.
Escolha a confiança primeiro, a automação segundo
A CA incorporada remove uma dependência de serviço de certificado externo para infraestrutura privada. Isso não faz com que uma raiz privada seja confiável globalmente, e não remove as responsabilidades de PKI do operador.
O Webship automatiza a geração de chaves, assinatura, validação, instalação, rotação e seleção de certificados em todo o protocolo. O operador ainda possui a custódia da raiz, inscrição de clientes, separação de ambientes, backup, recuperação e a decisão de usar um caminho de confiança público ou privado.
Essa separação é a característica. Um servidor autônomo pode automatizar TLS privado sem fingir ser uma CA pública — e sites públicos ainda podem usar emissão por site ou por grupo confiável pelos navegadores no mesmo processo.
Leia a documentação do Webship 1.4.0 versionada antes do lançamento. O RFC 5280 define perfis de certificados e validação, o RFC 6066 define a sinalização de nome de servidor TLS, o RFC 8446 define o TLS 1.3, o RFC 8555 define o ACME público, e o RFC 9525 define a verificação de identidade de serviço.