Saltar al contenido principal

Documentation Index

Fetch the complete documentation index at: https://certplane.kippel.org/llms.txt

Use this file to discover all available pages before exploring further.

Certplane divide la gestión de certificados en dos fases distintas. En la primera, un host demuestra su identidad ante una CA interna y recibe un certificado de identidad de larga duración. En la segunda fase, ese certificado de identidad actúa como credencial cuando el host se conecta al broker para solicitar y renovar certificados de servicio de confianza pública. Tus claves privadas nunca abandonan el host en ningún momento.

​
Los dos binarios

Certplane se compone de dos programas que se ejecutan en lugares distintos:

certplane-agent

Se ejecuta en cada host gestionado. Genera pares de claves localmente, contacta con step-ca durante el registro y se conecta al broker por mTLS para solicitar y renovar certificados de servicio. El agente es el único componente que toca claves privadas.

certplane-broker

Se ejecuta como servidor central. Acepta conexiones mTLS desde agentes, valida sus certificados de identidad, aplica el archivo de política declarativa y llama a tu CA pública mediante ACME para obtener o renovar certificados de servicio. El broker almacena en caché los certificados emitidos para evitar llamadas innecesarias a la CA.

​
Flujo de dos fases

El registro es un paso de configuración único que proporciona al host una identidad de máquina verificable. Ocurre antes de que el host pueda solicitar cualquier certificado de servicio.Lo que tú haces:
  1. Genera un token de arranque de corta duración en tu instancia step-ca para el nombre de identidad del host (por ejemplo, edge01.h.int.example.com).
  2. Escribe el token en el host en la ruta referenciada en la configuración del agente.
  3. Ejecuta certplane-agent enroll --config agent.yml.
Lo que hace el agente:
  1. Genera una clave privada (identity.key) localmente; nunca sale del host.
  2. Crea una solicitud de firma de certificado (CSR) con el nombre de identidad del host.
  3. Envía el CSR junto con el token de arranque a step-ca.
  4. step-ca valida el token, firma el CSR y devuelve identity.crt.
  5. El agente escribe identity.crt en disco. El registro está completo.
El token de arranque se consume en el primer uso. Después del registro, el agente usa identity.crt directamente para todas las futuras conexiones al broker.
Si necesitas volver a registrar un host, genera un nuevo token de arranque desde step-ca. El token anterior no se puede reutilizar.

​
Propiedades clave de seguridad

Las claves nunca abandonan el host. Tanto identity.key como service.key se generan en el host y se almacenan localmente. Solo se envían por la red los CSR (que no contienen material secreto). Autenticación mTLS. Cada conexión de un agente al broker se autentica mutuamente mediante TLS. El broker exige que el agente presente un identity.crt válido firmado por la CA interna configurada. Un agente sin certificado de identidad válido no puede conectarse al broker. Aplicación de la política. El broker comprueba cada solicitud de certificado contra el archivo de política antes de contactar con la CA pública. Si la identidad de un host no está registrada o solicita un perfil para el que no está autorizado, la solicitud se rechaza. El archivo de política es la única fuente autoritativa de lo que cada host puede recibir. Registro de auditoría. El broker escribe un registro de auditoría por cada decisión de emisión de certificado. El modo de fallo de auditoría (fail_open o fail_closed) controla el comportamiento si el propio subsistema de auditoría encuentra un error.

​
Qué ocurre en cada límite de confianza

LímiteProtocoloQué se verifica
Agente → step-ca (registro)HTTPSToken de arranque (de un solo uso); huella digital de la raíz step-ca
Agente → broker (renovación)mTLSidentity.crt del agente firmado por la CA interna
Broker → CA pública (ACME)HTTPS + dns-01Propiedad del registro DNS mediante la API de Cloudflare
Para instrucciones de configuración paso a paso, consulta Configuración del broker, Registro del agente y Ejecución del agente. Para entender cómo controlar lo que cada host puede solicitar, consulta Resumen de políticas.