Servicios de certificados (Manual de referencia de GNU Guix)

11.10.21 Servicios de certificados

El módulo (gnu services certbot) proporciona un servicio para la obtención automática de un certificado TLS válido de la autoridad de certificación Let’s Encrypt. Estos certificados pueden usarse para proporcionar contenido de forma segura sobre HTTPS u otros protocolos basados en TLS, con el conocimiento de que el cliente podrá verificar la autenticidad del servidor.

Let’s Encrypt provides the certbot tool to automate the certification process. This tool first securely generates a key on the server. It then makes a request to the Let’s Encrypt certificate authority (CA) to sign the key. The CA checks that the request originates from the host in question by using a challenge-response protocol, requiring the server to provide its response over HTTP. If that protocol completes successfully, the CA signs the key, resulting in a certificate. That certificate is valid for a limited period of time, and therefore to continue to provide TLS services, the server needs to periodically ask the CA to renew its signature.

El servicio certbot automatiza este proceso: la generación inicial de la clave, la petición inicial de certificación al servicio Let’s Encrypt, la integración del desafío/respuesta en el servidor web, la escritura del certificado en disco, las renovaciones periódicas automáticas y el despliegue de tareas asociadas con la renovación (por ejemplo la recarga de servicios y la copia de claves con diferentes permisos).

Certbot se ejecuta dos veces al día, en un minuto aleatorio dentro de la hora. No hará nada hasta que sus certificados estén pendientes de renovación o sean revocados, pero su ejecución regular propociona a su servicio la oportunidad de permanecer en línea en caso de que se produzca una revocación iniciada por Let’s Encrypt por alguna razón.

Mediante el uso de este servicio, usted acepta el acuerdo de suscripción ACME, que se puede encontrar aquí: https://acme-v01.api.letsencrypt.org/directory.

Variable: certbot-service-type

Un tipo de servicio para el cliente de Let’s Encrypt certbot. Su valor debe ser un registro certbot-configuration como en este ejemplo:

(service certbot-service-type
         (certbot-configuration
          (email "foo@example.net")
          (certificates
           (list
            (certificate-configuration
             (domains '("example.net" "www.example.net")))
            (certificate-configuration
             (domains '("bar.example.net")))))))

Véase a continuación los detalles de certbot-configuration.

Tipo de datos: certbot-configuration

Tipo de datos que representa la configuración del servicio certbot. Este tipo tiene los siguientes parámetros:

package (predeterminado: certbot)

El paquete certbot usado.

webroot (predeterminado: /var/www)

Directorio desde el que se proporcionan los archivos de desafío/respuesta de Let’s Encrypt.

certificates (predeterminados: '())

Una lista de configuraciones certificates-configuration para los cuales se generan certificados y se solicitan firmas. Cada certificado tiene un nombre (name) y varios dominios (domains).

email (predeterminado: #f)

Dirección de correo electrónico opcional usada para el registro y el contacto de recuperación. Se recomienda que proporcione un valor ya que le permite recibir importantes notificaciones acerca de la cuenta y los certificados emitidos.

server (predeterminada: #f)

URL opcional del servidor ACME. Esta configuración cambia el valor predeterminado de certbot, que es el servidor de Let’s Encrypt.

rsa-key-size (predeterminado: 2048)

Tamaño de la clave RSA.

default-location (predeterminada: véase a continuación)

La configuración nginx-location-configuration predeterminada. Debido a que certbot necesita proporcionar desafíos y respuestas, necesita ser capaz de ejecutar un servidor web. Se lleva a cabo extendiendo el servicio web nginx con una configuración nginx-server-configuration que escucha en los dominios domains en el puerto 80, y que contiene una configuración nginx-location-configuration para el subespacio de rutas URI /.well-known/ usado por Let’s Encrypt. See Servicios Web, para más información sobre estos tipos de datos de configuración de nginx.

Las peticiones a otras rutas URL se compararán contra la dirección predeterminada default-location, la cual, en caso de estar presente, se añade a todas las configuraciones nginx-server-configuration.

De manera predeterminada, la dirección predeterminada default-location emitirá una redirección http://dominio/... a https://dominio/..., lo que le permite definir qué proporcionará en su sitio web a través de https.

Proporcione #f para no emitir una dirección predeterminada.

Tipo de datos: certificate-configuration

Tipo de datos que representa la configuración de un certificado. Este tipo tiene los siguientes parámetros:

name (predeterminado: vea a continuación)

Este nombre se usa por Certbot para su mantenimiento interno y en las rutas de archivos; no afecta al contenido del certificado en sí mismo. Para ver los nombres de certificados, ejecute certbot certificates.

Su valor predeterminado es el primer dominio proporcionado.

domains (predeterminado: '())

El primer dominio proporcionado será el sujeto del nombre común (CN) del certificado, y todos los dominios serán nombres alternativos (Subject Alternative Names) en el certificado.

challenge (predeterminado: #f)

El tipo de desafío que debe ejecutar certbot. Si se especifica #f, el valor por omisión es desafío HTTP. Si se especifica un valor, el valor por omisión es el módulo manual (véase authentication-hook, cleanup-hook y la documentación en https://certbot.eff.org/docs/using.html#hooks), y concede permiso a Let’s Encrypt para registrar la IP pública de la máquina que realiza la petición.

csr (default: #f)

File name of Certificate Signing Request (CSR) in DER or PEM format. If #f is specified, this argument will not be passed to certbot. If a value is specified, certbot will use it to obtain a certificate, instead of using a self-generated CSR. The domain-name(s) mentioned in domains, must be consistent with the domain-name(s) mentioned in CSR file.

authentication-hook (predeterminado: #t)

Orden ejecutada en un shell una vez por cada desafío de certificado que debe contestarse. Durante su ejecución, la variable del shell $CERTBOT_DOMAIN contiene el dominio que se está validando, $CERTBOT_VALIDATION contiene la cadena de validación y $CERTBOT_TOKEN contiene el nombre de archivo del recurso solicitado cuando se realiza el desafío HTTP-01.

cleanup-hook (predeterminado: #f)

Orden ejecutada en un shell una vez por cada desafío de certificado que haya sido contestado por auth-hook. Durante su ejecución, las variables del shell disponibles en el script auth-hook todavía están disponibles, y adicionalmente $CERTBOT_AUTH_OUTPUT contendrá la salida estándar que produjo auth-hook.

deploy-hook (predeterminado: #f)

Orden ejecutada en un shell una vez por cada certificado emitido satisfactoriamente. Durante su ejecución, la variable del shell $RENEWED_LINEAGE apuntará al subdirectorio live de configuración (por ejemplo, ‘"/etc/letsencrypt/live/example.com"’) que contiene las nuevas claves y certificados; la variable del shell $RENEWED_DOMAINS contendrá una lista delimitada por espacios de certificados de dominio renovados (por ejemplo, ‘"example.com www.example.com"’).

start-self-signed? (default: #t)

Whether to generate an initial self-signed certificate during system activation. This option is particularly useful to allow nginx to start before certbot has run, because certbot relies on nginx running to perform HTTP challenges.

Para cada configuración certificate-configuration, el certificado se almacena /etc/certs/name/fullchain.pem y la clave se almacena en /etc/certs/name/privkey.pem.