Saltar al contenido principal
Certplane divide la gestión de certificados en dos fases. En la primera, un host prueba su identidad a una CA interna y recibe un certificado de identidad de larga duración. En la segunda, ese certificado actúa como credencial cuando el host conecta con el broker para solicitar certificados de servicio públicos. Las claves privadas de servicio nunca salen del host.

​
Los dos binarios

BinarioRol
certplane-brokerAPI HTTPS central. Autentica agentes con mTLS, aplica política, habla con el emisor ACME configurado, cachea certificados en un almacén SQLite o de archivo y registra eventos de auditoría.
certplane-agentBinario one-shot en cada host gestionado. Se registra con step-ca una vez y, en cada invocación, renueva la identidad (si toca), genera o reutiliza claves de servicio localmente, envía CSR al broker, instala los bundles devueltos y ejecuta hooks de recarga.
Ambos binarios se configuran con un único YAML pasado con -c / --config.

​
Fase 1: registro

Ocurre una vez por host. Vincula el host a su identidad de máquina.
1

Coloca un token de arranque

Un operador (o un play de Ansible) escribe un token de step-ca corto en la ruta indicada por identity.bootstrap_token.
2

Ejecuta `certplane-agent ... enroll`

El agente toma un lock en state_dir/agent.lock y:
  1. Genera una clave ECDSA P-256 en identity.key (si no existe).
  2. Construye un CSR con CN = identity.name.
  3. Llama al endpoint provisioner de step-ca en identity.step_ca.url, presentando el CSR y el token. Verifica el TLS del servidor con identity.step_ca.fingerprint o identity.step_ca.root_ca_bundle.
  4. Escribe el certificado devuelto en identity.cert y borra el archivo del token para que no pueda reutilizarse.
3

Identidad establecida

El agente posee el par (identity.key, identity.cert) firmado por step-ca. El CN es la identidad estable usada en cada llamada al broker.

​
Fase 2: bucle de renovación

Cada invocación de certplane-agent ... run hace lo siguiente:
1

Renovación de identidad

Si el certificado de identidad expira dentro de identity.renew_before (por defecto 8h), el agente renueva con step-ca y escribe un identity.crt nuevo. Si queda menos de identity.warn_before pero aún no hay que renovar, registra una advertencia.
2

Para cada certificado de servicio

Para cada entrada en certificates[]:
  1. Asegura una clave de servicio en key. La genera (ECDSA P-256) si falta y la reutiliza si existe. Las claves nunca salen del host.
  2. Comprueba el certificado existente en cert. Si parsea, coincide con la clave y aún no entra en la ventana de renew_before (por defecto 720h), registra certificate skipped, not in renewal window y continúa.
  3. Construye un CSR con exactamente los dns_names configurados.
  4. Llama al broker. Abre una conexión mTLS a broker.url, presentando identity.cert como cliente y confiando en broker.server_ca_bundle para el TLS del broker. Hace POST /v1/certificates con {profile, csr_pem}.
  5. Valida el bundle. Cuando el broker devuelve cert_pem, chain_pem y fullchain_pem, el agente verifica que la hoja coincide con la clave local y que tiene exactamente los DNS pedidos — nunca confía a ciegas en el broker.
  6. Instala atómicamente. Escribe cert, chain y fullchain en disco.
  7. Recarga. Si reload_command está definido, lo ejecuta con timeout reload_timeout (por defecto 30s) y registra la salida.

​
Qué hace el broker en /v1/certificates

Cuando recibe una solicitud de emisión:
  1. Autentica. El TLS termina con tls.RequireAndVerifyClientCert contra server.mtls.agent_ca_bundle. La identidad es el CN del certificado cliente.
  2. Autoriza. Busca la identidad en la política activa (policy.path), confirma que el profile solicitado aparece en hosts.<key>.profiles y valida los DNS del CSR contra los dns_names del perfil.
  3. Limita la tasa. Aplica límites por identidad y por (identidad, perfil) según rate_limits.
  4. Sirve desde caché o emite. Si hay un certificado cacheado para (profile, huella del CSR) fuera de la ventana de renew_before del perfil, lo devuelve. Si no, llama a ACME (Let’s Encrypt por defecto) con el tipo de desafío del perfil, obtiene el certificado, lo guarda y lo devuelve.
  5. Audita. Cada decisión — allow o deny, además de eventos de ciclo de vida del broker — se registra. Inspecciónalo con certplane-broker ... audit tail.

​
Lo que nunca cruza la red

  • Claves privadas de servicio. Siempre generadas y rotadas en el host que las usa.
  • Credenciales del proveedor DNS. Se quedan en el broker. Los agentes no saben cómo se satisface el desafío ACME.
  • Claves de cuenta ACME. Viven solo en el broker.

​
A dónde ir después