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.
El broker es el componente central de Certplane. Valida los certificados de identidad de los agentes por mTLS, aplica tu política de emisión, solicita certificados a Let’s Encrypt mediante ACME y devuelve paquetes firmados a los agentes. Esta página te guía para configurar e iniciar el broker desde cero.
Requisitos previos
Antes de configurar el broker, ten preparado lo siguiente:
- CA interna — una instancia de step-ca en ejecución que emitirá certificados de identidad de máquina a los agentes.
- Certificado y clave TLS del broker — un certificado emitido por tu CA interna para el listener HTTPS del broker (por ejemplo,
broker.int.example.com), junto con su clave privada.
- Bundle de CA del agente — el certificado raíz de la CA interna (PEM) que firmó y firmará los certificados de identidad de los agentes. El broker lo usa para verificar las conexiones mTLS entrantes de los agentes.
- Email de cuenta ACME — la dirección de correo a registrar en Let’s Encrypt.
- Clave de cuenta ACME — una clave privada EC o RSA codificada en PEM para la cuenta ACME. Genera una con
openssl ecparam -name prime256v1 -genkey -noout -out account.key.
- Credenciales del proveedor DNS — credenciales de API para tu proveedor DNS (actualmente
cloudflare), usadas para el desafío ACME dns-01. Ponlas a disposición como variables de entorno en el host del broker.
Crea broker.yml
Crea /etc/certplane/broker.yml con el siguiente contenido. Cada campo mostrado corresponde a una clave de configuración real; no añadas campos no listados a continuación.# broker.yml
server:
# Dirección y puerto en los que escucha el broker. Por defecto :8443.
address: ":8443"
tls:
# Ruta al certificado TLS del servidor del broker (PEM), emitido por tu CA interna.
cert: /etc/certplane/broker.crt
# Ruta a la clave privada TLS del broker (PEM).
key: /etc/certplane/broker.key
# Versión mínima de TLS aceptada. Debe ser "1.2" o "1.3". Por defecto "1.2".
min_version: "1.2"
mtls:
# Ruta al bundle de CA (PEM) usado para validar los certificados de identidad de los agentes entrantes.
agent_ca_bundle: /etc/certplane/agent-ca.crt
policy:
# Ruta a tu archivo policy.yml.
path: /etc/certplane/policy.yml
# Pon a true para recargar policy.yml automáticamente cuando cambie el archivo.
watch: false
store:
# Driver de persistencia. Solo se admiten "sqlite" y "file".
driver: sqlite
# Ruta al archivo de base de datos SQLite. Se crea automáticamente si no existe.
path: /var/lib/certplane/broker.db
audit:
# Habilita el log de auditoría. Por defecto true.
enabled: true
# Qué hacer si falla el subsistema de auditoría. "fail_open" sigue emitiendo;
# "fail_closed" rechaza todas las solicitudes hasta que el sistema de auditoría se recupere.
failure_mode: fail_open
# Refleja los eventos de auditoría en el flujo de log estructurado.
mirror_to_log: true
logging:
# Nivel de log: debug | info | warn | error. Por defecto info.
level: info
# Formato de log: json | text. Por defecto json.
format: json
# Destino del log. Por defecto stdout.
destination: stdout
issuer:
# El único proveedor admitido es "acme".
provider: acme
acme:
# URL del directorio ACME. Usa la URL de staging mientras pruebas (ver advertencia abajo).
directory_url: https://acme-staging-v02.api.letsencrypt.org/directory
# Dirección de correo registrada en la CA ACME.
account_email: admin@example.com
# Ruta a la clave privada de la cuenta ACME (PEM).
account_key: /etc/certplane/acme/account.key
# Proveedor DNS para el desafío dns-01. Actualmente solo se admite "cloudflare".
dns_provider: cloudflare
secrets:
# Cómo resuelve el broker las referencias a secretos en la configuración.
# "env" — los nombres de secreto son nombres de variables de entorno (predeterminado).
# "file" — los nombres de secreto son rutas de archivo.
# "vault" / "openbao" — los nombres de secreto son rutas KV de Vault.
provider: env
rate_limits:
# Máximo de solicitudes de certificado por identidad de agente por hora. Por defecto 50.
per_identity_per_hour: 50
# Máximo de solicitudes por identidad de agente por perfil de certificado por hora. Por defecto 20.
per_identity_profile_per_hour: 20
El broker escucha en :8443 por defecto. Para enlazar a una interfaz específica, define server.address con una dirección completa como 0.0.0.0:8443 o 192.168.1.10:8443.
Usa el directorio ACME de staging (https://acme-staging-v02.api.letsencrypt.org/directory) mientras pruebas tu configuración. Los certificados de staging no son de confianza para los navegadores ni el sistema operativo, pero por lo demás son idénticos a los de producción. Cambia a https://acme-v02.api.letsencrypt.org/directory solo después de confirmar que el broker puede completar correctamente el desafío dns-01.
Crea un archivo de política
El broker requiere un archivo de política en la ruta definida en policy.path. El archivo de política define qué perfiles de certificado existen y qué identidades de agente pueden solicitarlos.Crea /etc/certplane/policy.yml para empezar. Consulta Resumen de políticas para la referencia completa de políticas.Si configuras policy.watch: true, el broker recarga policy.yml automáticamente cada vez que cambia el archivo en disco; sin necesidad de reinicio. Esto es útil cuando gestionas la política con una herramienta de gestión de configuración que escribe el archivo en su sitio.
Inicia el broker
Ejecuta el broker, pasando la ruta a tu archivo de configuración:certplane-broker --config /etc/certplane/broker.yml
