# Certificados TLS no Webship: a CA ACME Incorporada
Um certificado TLS realiza duas funções: ajuda a encriptar uma ligação e indica ao cliente com que identidade está a comunicar. A encriptação pode ser forte enquanto a decisão de confiança está errada para o público. É por isso que a automatizaçã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 utilizar um certificado ACME confiável pelo navegador, um serviço interno pode usar a autoridade de certificação privada integrada do Webship, e um site com uma PKI existente pode manter ficheiros de certificados geridos pelo operador. Todos podem partilhar um único processo do Webship sem partilhar 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 de [[sites]]. Não é um interruptor global.
| Modo | Fonte de confiança | Melhor ajuste | Caminho de validação | | --- | --- | --- | --- | | por_site | Armazenamentos de confiança públicos de navegadores e sistemas operativos | Um site público com um nome de host exato | ACME público com TLS-ALPN-01 | | frota | Armazenamentos de confiança do navegador público e do sistema operativo | Grandes conjuntos de nomes de terceiro e quarto nível sob domínios registados explícitos | ACME público com DNS-01 e fragmentos de certificados estáveis | | incorporado | Uma root Webship privada instalada pelo operador | Serviços internos, dispositivos geridos, frotas privadas e ambientes de teste | Emissão em processo; sem desafio externo | | partilhado | Repositórios de confiança públicos de navegadores e sistemas operativos | Implementações antigas que utilizam intencionalmente um grupo multi-SAN público | ACME público com TLS-ALPN-01 |
O padrão é per_site. Ele encomenda 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 utiliza 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] têm sempre prioridade sobre a emissão automática para esse site.
O que significa “ACME CA incorporado”
A secção de configuração chama-se [acme_ca], mas a CA incorporada não é um serviço ACME público ou acessível em rede. Não expõe nenhum endpoint de diretório, não aceita registo remoto, não chama nenhuma API de registo e não realiza nenhum desafio de prova de controlo.
Em vez disso, o Webship mantém todo o caminho de emissão privada num ú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 a instalar no resolvedor TLS ativo.
- O certificado está então disponível para todos os protocolos habilitados desse site.
Um desafio de rede ao estilo ACME só provaria o Webship a si próprio, por isso o caminho incorporado deliberadamente não tem protocolo de rede. A secção [acme_ca] é estado PKI privado: define onde a raiz se encontra e quanto tempo os certificados 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] ativado = 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:
- A cache ACME mantém identidades de sites geridas automaticamente.
- O diretório de estados do CA incorporado contém a identidade privada da raiz.
- A conta de serviço precisa de acesso, mas os utilizadores da aplicação não.
- Os backups devem preservar a confidencialidade e as permissões dos ficheiros.
- A produção, o desenvolvimento e os testes devem usar raízes separadas e diretórios separados.
Eliminar o diretório raiz não "reinicia o TLS." Cria uma nova âncora de confiança. Os clientes que confiam na raiz antiga irão rejeitar os certificados emitidos pelo substituto até que os seus repositórios de confiança sejam atualizados.
O trust privado é intencional
Os certificados da CA incorporada não são automaticamente confiáveis pelos navegadores públicos ou sistemas operativos. Tornam-se confiáveis apenas depois de o operador instalar o certificado raiz Webship exportado no armazenamento de confiança do cliente.
Isso torna o modo incorporado adequado para:
- portáteis e telemóveis geridos pela empresa inscritos através da gestão 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 website público comum cujos visitantes utilizem navegadores não geridos. Utilize emissão por_site pública para um nome público exato, emissão de frota para grandes conjuntos de subdomínios públicos, partilhado apenas para uma implementação deliberada de legado multi-SAN, ou ficheiros 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 registados.
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 = "reject"
[tls_automático] ativado = 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.example.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 o seu próprio certificado público ACME. control.internal.example recebe um certificado privado da CA incorporada. payments.example.com permanece sob a PKI externa do operador porque os seus ficheiros explícitos têm prioridade.
O diretório público ACME é ignorado pelos 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 resolutor de certificados para H1, H2, H3 e WebTransport
A seleção de certificado ocorre durante o handshake TLS, antes de existir um pedido HTTP. O Webship utiliza o nome do servidor ClientHello para selecionar a identidade do site e, em seguida, negocia o protocolo de aplicação.
- HTTP/1.1 e HTTP/2 utilizam TLS sobre TCP.
- O HTTP/3 e o WebTransport usam TLS dentro do QUIC sobre UDP.
- Uma identidade de site válida pode servir todos os protocolos ativados.
- O HTTP/3 também requer acessibilidade UDP; H1 e H2 utilizam o caminho TCP.
- O Alt-Svc pode anunciar H3 enquanto preserva uma alternativa TCP.
O TCP, TLS e QUIC utilizam o mesmo modelo de identidade consciente do site. Nomes exatos têm prioridade, o curinga válido mais longo prevalece onde os certificados curinga estão configurados, e SNI com nome desconhecido pode ser rejeitado em vez de receber um certificado padrão não relacionado.
Use unknown_sni = "reject" num ouvinte multi-site quando um nome de host não reconhecido deve falhar encerrando a conexão. Teste nomes reconhecidos, nomes não reconhecidos e o seu comportamento esperado sem SNI antes de implementar em produção.
Rodar identidades incorporadas sem uma lacuna de serviço
O Webship expõe o estado do certificado e mutações controladas através do seu servidor MCP autenticado e ligado em loopback:
- webship.tls.get_status reporta o resolvedor de certificados ativo e o estado de renovação.
- webship.tls.reissue_certificate reemite imediatamente um site gerido automaticamente apenas quando esse site utiliza 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, o seu diretório de estado, duração da folha, 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 a colocar em serviço. A identidade válida atual continua a servir até que a nova identidade esteja pronta. A identidade retirada é registada apenas depois de a substituição ser instalada.
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 ACME em vez de ser confundida com a assinatura privada em processo. A pertença em modo partilhado também está congelada no reinício porque alterar um grupo multi-SAN reconstrói o limite de identidade.
O MCP é uma superfície de controlo privilegiada. Mantenha-o 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 direcção correcta.
- 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 funcional.
- Ficheiros manuais explícitos impedem a atribuição automática de propriedade desse site.
- Um SNI com nome desconhecido pode ser rejeitado antes do encaminhamento HTTP.
- A CA incorporada permanece privada e não possui um ponto de inscrição remoto.
- Identidades públicas e integradas 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 preparar o diretório de estado configurado. Corrija a propriedade, as permissões, a persistência ou a disponibilidade de armazenamento antes de enviar tráfego para o site afetado. Não contorne o erro copiando a chave raiz de outro ambiente.
Lista de verificação de produção
Antes de ativar o modo incorporado:
- Identifique todas as populações de clientes que devem 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.
- Ative H1, H2 e H3 deliberadamente e verifique ambos os caminhos TCP e 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 elimina uma dependência de serviço de certificado externo para infraestruturas privadas. Não torna uma root privada globalmente confiável, 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 detém a custódia da raiz, registro 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 o TLS privado sem fingir ser uma CA pública — e os sites públicos ainda podem usar emissão por site ou por frota confiável pelo navegador no mesmo processo.
Leia a documentação versionada Webship 1.4.0 antes da implementação. O RFC 5280 define perfis e validação de certificados, o RFC 6066 define a sinalização do nome do 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 do serviço.