linux-system-roles.certificate

Descripción general Versiones Perspectivas

Rol del Sistema de Certificados

ansible-lint.yml ansible-test.yml codeql.yml markdownlint.yml python-unit-test.yml tft.yml tft_citest_bad.yml woke.yml

Rol para gestionar la emisión y renovación de certificados TLS/SSL

Rol de sistema Linux para emitir y renovar certificados SSL.

Uso básico:

---
- hosts: servidor-web

  vars:
    certificate_requests:
      - name: mi_certificado
        dns: www.ejemplo.com
        ca: auto-firmado

  roles:
    - linux-system-roles.certificate

En un sistema basado en RPM, esto colocará el certificado en /etc/pki/tls/certs/mi_certificado.crt y la clave en /etc/pki/tls/private/mi_certificado.key.

Requisitos

Ver abajo

Requisitos de la colección

El rol requiere colecciones externas solo para la gestión de nodos rpm-ostree. Por favor, ejecute el siguiente comando para instalarlas si necesita gestionar nodos rpm-ostree:

ansible-galaxy collection install -vv -r meta/collection-requirements.yml

Variables

Parámetro Descripción Tipo Requerido Por defecto
certificate_wait Si la tarea debe esperar a que se emita el certificado. bool no sí
certificate_requests Una lista de diccionarios representando cada certificado a emitir. Ver certificate_requests. list no -

certificate_requests

Nota: Campos como common_name, country, state, locality, organization, organizational_unit, email, key_usage y extended_key_usage que se pueden incluir en la solicitud de certificado están definidos por el RFC 5280.

Nota: Tenga en cuenta que la CA podría no honrar todos los campos solicitados. Por ejemplo, incluso si una solicitud incluye country: US, la CA podría emitir el certificado sin country en su sujeto.

Nota: Los campos dns, email e ip se utilizan para definir los Nombres Alternativos del Sujeto (SAN).

Parámetro Descripción Tipo Requerido Por defecto
name Nombre del certificado. Se puede usar una ruta completa para elegir el directorio donde se almacenarán los archivos. str sí -
ca CA que emitirá el certificado. Ver CAs y Proveedores. str sí -
dns Dominio (o lista de dominios) que se incluirá en el certificado. También puede proporcionar el valor por defecto para common_name. str o list no -
email Correo electrónico (o lista de correos) que se incluirá en el certificado. str o list no -
ip IP, o lista de IPs, que se incluirán en el certificado. Las IPs pueden ser IPv4, IPv6 o ambas. También puede proporcionar el valor por defecto para common_name. str o list no -
auto_renew Indica si el certificado debe renovarse automáticamente antes de que expire. bool no sí
owner Nombre de usuario (o ID de usuario) para los archivos de certificado y clave. str no Usuario que ejecuta Ansible
group Nombre de grupo (o ID de grupo) para los archivos de certificado y clave. str no Grupo que ejecuta Ansible
mode Los permisos del sistema de archivos para los archivos de certificado y clave. raw no -
key_size Generar claves con un tamaño de clave específico en bits. int no 2048 - Ver key_size
common_name Nombre común solicitado para el sujeto del certificado. str no Ver common_name
country Código de país solicitado para el sujeto del certificado. str no -
state Estado solicitado para el sujeto del certificado. str no -
locality Localidad solicitada para el sujeto del certificado (usualmente ciudad). str no -
organization Organización solicitada para el sujeto del certificado. str no -
organizational_unit Unidad organizacional solicitada para el sujeto del certificado. str no -
contact_email Correo electrónico de contacto solicitado para el sujeto del certificado. str no -
key_usage Uso de clave permitido para el certificado. Para valores válidos ver: key_usage. list no Ver key_usage
extended_key_usage Atributos de uso de clave extendido que deben estar presentes en la solicitud de certificado. list no Ver extended_key_usage
run_before Comando que debe ejecutarse antes de guardar el certificado. Ver run hooks. str no -
run_after Comando que debe ejecutarse después de guardar el certificado. Ver run hooks. str no -
principal Principal de Kerberos. str no -
provider El método subyacente utilizado para solicitar y gestionar el certificado. str no Varía según CA

common_name

Si common_name no está configurado, el rol intentará usar el primer valor de dns o ip, respectivamente, como el valor por defecto. Si dns e ip tampoco están configurados, common_name no se incluirá en el certificado.

key_size

Los valores mínimos recomendados para el tamaño de la clave de un certificado, de diferentes organizaciones, varían a lo largo del tiempo. En el intento de proporcionar configuraciones seguras, el valor mínimo por defecto para key_size será incrementado con el tiempo.

Si desea que sus certificados mantengan siempre el mismo key_size al ser renovados, establezca esta variable en el valor deseado.

key_usage

Los valores válidos para key_usage son:

  • digitalSignature
  • nonRepudiation
  • keyEncipherment
  • dataEncipherment
  • keyAgreement
  • keyCertSign
  • cRLSign
  • encipherOnly
  • decipherOnly

Los valores por defecto para key_usage son:

  • digitalSignature
  • keyEncipherment

extended_key_usage

Cualquier oid válido se puede usar para establecer uno o más extended_key_usage. Además de eso, también hay una lista de alias conocidos que serán reconocidos por el rol:

  • id-kp-serverAuth
  • id-kp-clientAuth
  • id-kp-codeSigning
  • id-kp-emailProtection
  • id-kp-timeStamping
  • id-kp-OCSPSigning
  • id-kp-ipsecEndSystem
  • id-kp-ipsecTunnel
  • id-kp-ipsecUser

Si extended_key_usage no está configurado, el rol usará por defecto:

  • id-kp-serverAuth
  • id-kp-clientAuth

run hooks

A veces, necesita ejecutar un comando justo antes de que un certificado sea renovado y otro comando justo después. Para hacer esto, use run_before y run_after.

El valor proporcionado a run_before y run_after se envolverá y almacenará en archivos de script que luego serán ejecutados por el proveedor.

CAs y Proveedores

CA Proveedores Descripción de CA Requisitos
auto-firmado certmonger* Emitir certificados auto-firmados de una CA local.
ipa certmonger* Emitir certificados usando la CA de FreeIPA. El host debe estar inscrito en un servidor FreeIPA.

* Proveedor por defecto.

CA representa los certificados de CA que se utilizarán para emitir y firmar el certificado solicitado. El proveedor representa el método utilizado para enviar la solicitud de certificado a la CA y luego recuperar el certificado firmado.

Si un usuario elige CA auto-firmado, con certmonger como proveedor y, más tarde, decide cambiar el proveedor a openssl, los certificados de CA utilizados en ambos casos deben ser los mismos. Tenga en cuenta que openssl no es aún un proveedor soportado y se menciona aquí solo como un ejemplo.

Certmonger y SELinux

Si SELinux está en vigor, el servicio certmonger solo puede escribir o editar archivos en directorios donde esté presente el contexto cert_t.

Además, si los scripts ejecutados por los parámetros run_before y run_after necesitan escribir o editar archivos, esos scripts también requieren que el contexto cert_t esté presente antes de la ejecución del rol.

Puede usar el Rol del Sistema selinux para gestionar los contextos de SELinux.

Para más información sobre certmonger y los requisitos de SELinux, consulte las páginas de man certmonger_selinux(8).

Ejemplos

Emitir un certificado auto-firmado

Emita un certificado para *.ejemplo.com y colóquelo en el directorio estándar para la distribución.

---
- hosts: servidor-web

  vars:
    certificate_requests:
      - name: mi_certificado
        dns: *.ejemplo.com
        ca: auto-firmado

  roles:
    - linux-system-roles.certificate

Puede encontrar los directorios para cada distribución en las siguientes ubicaciones:

  • Debian/Ubuntu:

    • Certificados: /etc/ssl/localcerts/certs/
    • Claves: /etc/ssl/localcerts/private/

  • RHEL/CentOS/Fedora:

    • Certificados: /etc/pki/tls/certs/
    • Claves: /etc/pki/tls/private/

Elegir dónde colocar los certificados

Emita un certificado y clave y colóquelos en la ubicación especificada. El siguiente ejemplo crea un archivo de certificado en /otra/ruta/mi_certificado.crt y un archivo de clave en /otra/ruta/mi_certificado.key.

---
- hosts: servidor-web
  vars:
    certificate_requests:
      - name: /otra/ruta/mi_certificado
        dns: *.ejemplo.com
        ca: auto-firmado

  roles:
    - linux-system-roles.certificate

Emitir certificados con múltiples DNS, IP y Correo Electrónico

---
- hosts: servidor-web
  vars:
    certificate_requests:
      - name: mi_certificado
        dns:
          - www.ejemplo.com
          - sub1.ejemplo.com
          - sub2.ejemplo.com
          - sub3.ejemplo.com
        ip:
          - 192.0.2.12
          - 198.51.100.65
          - 2001:db8::2:1
        email:
          - [email protected]
          - [email protected]
        ca: auto-firmado

  roles:
    - linux-system-roles.certificate

Establecer opciones comunes del sujeto

---
- hosts: servidor-web
  vars:
    certificate_requests:
      - name: mi_certificado
        dns: www.ejemplo.com
        common_name: www.ejemplo.com
        ca: auto-firmado
        country: US
        state: NY
        locality: Nueva York
        organization: Red Hat
        organizational_unit: plataforma
        email: [email protected]
  roles:
    - linux-system-roles.certificate

Establecer el tamaño de la clave del certificado

---
- hosts: servidor-web
  vars:
    certificate_requests:
      - name: mi_certificado
        dns: www.ejemplo.com
        ca: auto-firmado
        key_size: 4096
  roles:
    - linux-system-roles.certificate

Establecer el "Uso de Clave" y "Uso de Clave Extendida" (EKU)

---
- hosts: servidor-web
  vars:
    certificate_requests:
      - name: mi_certificado
        dns: www.ejemplo.com
        ca: auto-firmado
        key_usage:
          - digitalSignature
          - nonRepudiation
          - keyEncipherment
        extended_key_usage:
          - id-kp-clientAuth
          - id-kp-serverAuth
  roles:
    - linux-system-roles.certificate

No esperar a que se emita el certificado

La emisión del certificado puede tomar varios minutos dependiendo de la CA. Por lo tanto, también es posible solicitar el certificado pero no esperar realmente a que se emita.

Esta configuración afecta todos los certificados: si certificate_wait está configurado en no, el rol no espera a que se emita ningún certificado.

---
- hosts: servidor-web
  vars:
    certificate_wait: false
    certificate_requests:
      - name: mi_certificado
        dns: www.ejemplo.com
        ca: auto-firmado
  roles:
    - linux-system-roles.certificate

Establecer un principal

---
- hosts: servidor-web
  vars:
    certificate_requests:
      - name: mi_certificado
        dns: www.ejemplo.com
        ca: auto-firmado
        principal: HTTP/[email protected]

  roles:
    - linux-system-roles.certificate

Elegir no renovarle automáticamente un certificado

Por defecto, los certificados generados por el rol están configurados para la renovación automática. Para desactivar ese comportamiento, establezca auto_renew: no.

---
- hosts: servidor-web
  vars:
    certificate_requests:
      - name: mi_certificado
        dns: www.ejemplo.com
        ca: auto-firmado
        auto_renew: no

  roles:
    - linux-system-roles.certificate

Usar FreeIPA para emitir un certificado

Si su host está inscrito en un servidor FreeIPA, también tiene la opción de usar su CA para emitir su certificado. Para hacer esto, establezca ca: ipa.

---
- hosts: servidor-web
  vars:
    certificate_requests:
      - name: mi_certificado
        dns: www.ejemplo.com
        principal: HTTP/[email protected]
        ca: ipa

  roles:
    - linux-system-roles.certificate

Ejecutar un comando antes o después de que se emita un certificado

A veces, necesita ejecutar un comando justo antes de que se renueve un certificado y otro comando justo después. Para hacer esto, use run_before y run_after.

---
- hosts: servidor-web
  vars:
    certificate_requests:
      - name: mi_certificado
        dns: www.ejemplo.com
        ca: auto-firmado
        run_before: systemctl stop servicio-webserver.service
        run_after: systemctl start servicio-webserver.service

  roles:
    - linux-system-roles.certificate

Establecer el propietario y grupo del certificado

Si está usando un certificado para un servicio, por ejemplo httpd, necesita establecer el propietario y el grupo que serán dueños del certificado. En el siguiente ejemplo, tanto el propietario como el grupo se establecen en httpd.

---
- hosts: servidor-web
  vars:
    certificate_requests:
      - name: mi_certificado
        dns: www.ejemplo.com
        ca: auto-firmado
        owner: httpd
        group: httpd

  roles:
    - linux-system-roles.certificate

Tenga en cuenta que también puede usar UID y GID en lugar de nombres de usuario y grupos.

Compatibilidad

Actualmente compatible con CentOS 7+, RHEL 7+, Fedora. Se ha probado con Debian 10.

rpm-ostree

Ver README-ostree.md

Licencia

MIT

Información del Autor

Sergio Oliveira Campos (@seocam)

Acerca del proyecto

Role for managing TLS/SSL certificate issuance and renewal

role centos certificate certmonger el7 el8 el9 el10 fedora redhat rhel ssl system tls
Instalar
ansible-galaxy install linux-system-roles.certificate
GitHub repositorio
32 estrellas
23 bifurcaciones
11 problemas abiertos
Licencia
mit
Descargas
14.4k
Propietario