ACME con Certbot

EMPRESA Esta es una característica de EJBCA Enterprise.

A continuación se explica cómo instalar y utilizar el cliente ACME Certbot.

Para obtener información general sobre ACME (Entorno de gestión automática de certificados), consulte ACME .

    Certbot solía ser el cliente oficial de Let's Encrypt, pero ahora lo mantiene la Electronic Frontier Foundation. Es uno de los clientes ACME más utilizados, compatible con operaciones de emisión, renovación y revocación, todas ellas compatibles con EJBCA. Para más información, consulte la documentación de Certbot .

    Instalación y funcionamiento

    Versiones compatibles

    EJBCA Enterprise admite Certbot versión 1.20.0 o superior.

    La última versión probada con EJBCA es Certbot 1.30.0 en Ubuntu 20.04.3 LTS.

    Funciones compatibles

    A continuación se enumeran las características y limitaciones admitidas:

    • Certbot no admite las aprobaciones EJBCA para la gestión de cuentas ACME porque no reutiliza una clave de cuenta existente para el registro de cuentas.

    • Certbot no admite la inscripción de certificados para identificadores de IP (pero se supone que se agregará soporte pronto).

    • Certbot no admite la actualización ni la desactivación de cuentas con EAB (Enlace de Cuentas Externas). Como solución alternativa, debe desactivarse temporalmente para usar esta función.

    • Tenga en cuenta que Certbot asocia la cuenta ACME generada con el endpoint utilizado. Esto podría provocar un comportamiento inesperado de Certbot si se solicitan varias instancias EJBCA desde la misma configuración.

    Prerrequisitos

    Permisos de superusuario.

    No se requieren permisos de superusuario si Certbot tiene acceso de lectura/escritura a su directorio de trabajo (generalmente /etc/letsencrypt, configurado con --work-dir) y al directorio de desafío del servidor web.

    Instalación

    Si usa un sistema operativo Linux, use gestores de paquetes como apt (solo versiones anteriores) o snap para instalar la versión actual de Certbot (1.30). Para más información, consulte https://certbot.eff.org/ o vaya a https://github.com/certbot/certbot para compilar Certbot desde el código fuente. Si tiene Python 3 instalado en su sistema, puede que prefiera el gestor de paquetes pip3 de Python para instalar Certbot.

    Para instalar usando apt:

    $ apt-get install certbot

    Para instalar usando snap:

    $ snap install certbot --classic

    Para instalar usando Python 3:

    $ pip3 install certbot== 1.30
    #(leave out ==${version} to install the latest version)

    Postinstalación

    Configurar Certbot para HTTPS

    Agregue la cadena de confianza del certificado del servidor EJBCA al almacén de confianza local.

    $ mkdir -p /usr/share/ca-certificates/extra
    $ cp <path to Management.cacert.pem> /usr/share/ca-certificates/extra
    $ update-ca-certificates

    Como alternativa, agregue " no-verify-ssl = true" a /etc/letsencrypt/cli.ini después de la instalación. De lo contrario, las invocaciones del contenedor certbot-auto que incluya --no-verifiy-ssl fallarán con el error "Error de verificación del certificado" de la biblioteca de URL de Python, incluso si importó ManagementCA.cacert.pem en 'Certifi' o en el almacén de confianza de la CA del sistema (/usr/local/lib/python3.6/dist-packages/certifi/cacert.pem o /etc/ssl/certs/ca-certificates.crt).

    $ echo -e "no-verify-ssl = true" >> /etc/letsencrypt/cli.ini

    Cree un directorio de desafíos para su servidor web

    Si desea utilizar la validación de desafío http-01, asegúrese de que Certbot pueda escribir en la carpeta de desafío del servidor web, generalmente ubicada en /var/www/html/.well-known/acme-challenge.

    El servidor web debe abrir el puerto 80 para servir el token de desafío con HTTP: http://<nombre de host>/.well-known/acme-challenge/<nombre de archivo>.

    $ mkdir -p /var/www/html/.well-known/acme-challenge

    Restablecer Certbot

    Para restablecer certbot , mueva o elimine todas las carpetas debajo de /etc/letsencrypt o debajo del directorio de trabajo especificado con la opción --work-dir del CMD.

    $ rm -rf /etc/letsencrypt/*

    Mostrar ayuda con Certbot -h [TEMA]

    Utilice la ayuda de Certbot para obtener información detallada.

    $ certbot -h [TOPIC]

    Ejecutar comandos de conveniencia de Certbot

    Certbot admite comandos de función única, como solicitar el recurso de directorio, registrar o desactivar una cuenta, crear un pedido de certificado o inscribir un certificado, así como comandos de conveniencia que procesan un flujo de trabajo ACME completo con una sola llamada CLI.

    Registro de cuenta e inscripción de certificados

    Flujo de trabajo del comando certonly de Certbot:

    1. Si no hay ninguna cuenta ACME registrada, Certbot genera localmente un par de claves de cuenta para registrar una nueva en el servidor de la CA. De lo contrario, Certbot intenta recuperar una cuenta existente utilizando la clave de cuenta almacenada en el sistema.

    2. Certbot solicita el recurso de pedido del servidor CA y recibe el objeto de pedido recién creado, incluidas todas las autorizaciones y desafíos necesarios para inscribir el certificado para los identificadores dados.

    3. Certbot coloca el token de desafío en el directorio de desafío del servidor web local.

    4. Certbot solicita el recurso de desafío de los servidores de CA.

    5. La CA verifica la respuesta al desafío con el desafío http-01.

    6. Certbot elimina el token de desafío.

    7. Certbot genera un par de claves y publica el CSR generado para que el certificado se inscriba en el recurso de finalización de los servidores de CA.

    8. El servidor CA inscribe y almacena el certificado.

    9. Certbot descarga el certificado solicitando el recurso de certificado recibido con el objeto de pedido en la respuesta de recurso de finalización.

      $ certbot certonly --no-verify-ssl --webroot -w /var/www/html --server https: //localhost:8442/ejbca/acme/directory --email <e-mail-address[,e-mail-address]> --domain example.com

    10. Si existen cadenas de certificados cruzados para la CA designada en EJBCA, se puede usar el argumento de cadena preferida para seleccionar la cadena deseada. El valor es el nombre común (CN) de la CA raíz deseada. Tenga en cuenta que EJBCA solo admite cadenas de certificados cruzados completadas que terminen en una CA raíz con un certificado autofirmado.

      $ certbot certonly --no-verify-ssl --webroot -w /var/www/html --server https: //localhost:8442/ejbca/acme/directory --email <e-mail-address[,e-mail-address]> --domain example.com --preferred-chain MySuperLegacyCa

    Registro de cuenta e inscripción de certificado con desafío dns-01

    De forma predeterminada, Certbot utiliza la validación de desafío http-01 para verificar la propiedad del identificador. Utilice el comando de conveniencia para inscribir el certificado mediante el desafío dns-01.

    $ certbot certonly --no-verify-ssl --manual --preferred-challenges dns certonly --server https: //localhost:8442/ejbca/acme/directory --email <e-mail-address[,e-mail-address]> --domain example.com

    Certbot detendrá la ejecución del flujo de trabajo antes de la validación del desafío. Coloque el token recibido por Certbot como valor en un registro DNS TXT llamado _acme-challenge.example.com y continúe con la inscripción del certificado. Use un TTL corto y asegúrese de que su sistema reciba las entradas DNS actualizadas. Es decir, `dig e xample.com txt +answer +recurse` debe contener el token del desafío.

    Registro de cuenta e inscripción de certificados con EAB

    Utilice el comando Certbot certonly como en el ejemplo anterior para el registro de cuenta y la inscripción de certificado, pero con EAB (enlace de cuenta externa).

    $ certbot certonly --no-verify-ssl --webroot -w /var/www/html --server https: //localhost:8442/ejbca/acme/directory --domain example.com --eab-kid <keyIdFromCa> --eab-hmac-key <symmetrickeyFromCa>

    Tenga en cuenta que la CA envía --eab-kid y --ab-hmac-key a los titulares de cuentas ACME.

    Ejecutar comandos de Certbot

    Registro de cuenta

    Registre una nueva cuenta ACME.

    Opcionalmente, puede registrar un nuevo ACME con EAB si es necesario, utilizando --eab-kid <kid> y --eab-hmac-key <key>.

    Si se registró una cuenta ACME con EAB, --eab-kid y --eab-hmac-key no son efectivos para actualizaciones de cuentas, cancelaciones de registros o inscripción de certificados y no es necesario especificarlos.

    $ certbot register --no-verify-ssl --server https: //localhost:8442/ejbca/acme/directory

    Actualización de cuenta

    Actualizar la información de contacto de una cuenta ACME.

    $ certbot update_account --no-verify-ssl --server https: //localhost:8442/ejbca/acme/directory --email <e-mail-address[,e-mail-address]>

    Cancelación del registro de cuenta (irreversible)

    EJBCA no revoca ni elimina los certificados registrados para esta cuenta.

    $ certbot unregister --no-verify-ssl --server https: //localhost:8442/ejbca/acme/directory

    Revocación de certificado

    Las razones de revocación aceptadas son: no especificadas (predeterminado), compromiso de clave, cambio de afiliación, reemplazo o cese de operación.

    $ certbot revoke --no-verify-ssl --reason keycompromise --server https: //localhost:8442/ejbca/acme/directory --cert-path /etc/letsencrypt/live/example.com/cert.pem --no-delete-after-revoke

    Renovación de certificado

    No elimine el certificado antes de la renovación


    $ certbot renew --no-verify-ssl --server https: //localhost:8442/ejbca/acme/directory --cert-name example.com --cert-path /etc/letsencrypt/live/example.com/cert.pem

    Alternativamente, puede repetir el comando certonly para renovar un certificado.

    Eliminación de certificado

    El certificado se elimina únicamente en el cliente.

    $ certbot delete --no-verify-ssl --cert-name example.com --server https: //localhost:8442/ejbca/acme/directory

    Manejo de errores

    Registro de Certbot

    El archivo de registro de Certbot normalmente se encuentra en la siguiente ubicación: /var/log/letsencrypt/letsencrypt.log.

    También puedes elegir que se muestre en la CLI una salida detallada adicional.

    $ certbot [SUBCOMMAND] -v [otherOptions] [-d DOMAIN1] [-d DOMAIN2]

    A veces se necesita el registro EJBCA para encontrar la causa raíz de un problema. Para más información, consulte Registro .

    Errores y soluciones

    A continuación se enumeran errores comunes y soluciones.

    Restricción de DN de sujeto único de CA

    El archivo de registro y salida de la CLI de Certbot registra un mensaje de advertencia después de limpiar los tokens de desafío.

    An unexpected error occurred:
    The server experienced an internal error :: The server experienced an internal error

    Tanto la causa raíz como la solución se pueden encontrar en el registro del servidor EJBCA. Para obtener más información sobre los niveles de registro, consulte Registro .

    [...] INFO [org.cesecore.audit.impl.log4j.Log4jDevice] (default task-2) [...] User 'user2' is not allowed to use same subject DN as the user(s) 'user1' is/are using while issued by the same CA [...] See setting for 'Enforce unique DN' in the section Certification Authorities.

    Puede deshabilitar la restricción de DN de sujeto único de las CA o usar el esquema de generación de nombres de RA para asignar sus identificadores a entidades finales.

    Tipo de clave privada no compatible con la cuenta ACME

    Tras actualizar Certbot o EJBCA, es posible que su clave de cuenta ACME ya no se reconozca como válida. En ese caso, deberá registrar una nueva cuenta ACME. Elimine la clave de cuenta de Certbot y la configuración en /etc/letsencrypt/accounts y registre una nueva cuenta. Certbot generará una nueva clave de cuenta.

    El archivo de registro y la salida CLI de Certbot informan una solicitud mal formada.

    An unexpected error occurred:
    The server experienced an internal error :: The server experienced an internal error

    La causa raíz se puede encontrar en el registro del servidor EJBCA en modo DEBUG. Para obtener más información sobre los niveles de registro, consulte Registro .

    [...] DEBUG [org.ejbca.core.protocol.acme.util.AcmeJwsHelper] (default task-1) Unsupported private key type. [...] Responding to request with problem report of type urn:ietf:params:acme:error:malformed and detail 'The request message was malformed'.

    No se pudo actualizar el usuario debido a la generación por lotes de contraseña en la configuración del perfil de la entidad final

    El informe de salida y el archivo de registro de la CLI de Certbot informan una solicitud mal formada durante la inscripción del certificado.

    An unexpected error occurred:
    The server experienced an internal error :: Unable to process the request. Could not update user.

    La causa raíz se puede encontrar en el registro del servidor EJBCA en modo INFO. Para obtener más información sobre los niveles de registro, consulte Registro .

    [...] WARN [org.ejbca.ui.web.protocol.acme.logic.AcmeOrderSessionBean] [...] org.ejbca.core.model.ra.raadmin.EndEntityProfileValidationException: Clearpassword (used in batch processing) cannot be used.

    Habilite la opción Generación por lotes (almacenamiento de contraseñas en texto sin cifrar) en la configuración del Perfil de entidad final. Para obtener más información, consulte Configuración del Perfil de entidad final en ACME .

    Atributos DN del sujeto o SAN faltantes u otros problemas en la configuración del perfil de la entidad final

    La inscripción del certificado puede fallar porque no se cumplen las restricciones del perfil de entidad final, es decir, debido a atributos de DN de sujeto faltantes, muy pocos DNS de sujeto AN u otras restricciones de perfil.

    Informe de archivo de registro y salida de CLI de Certbot sobre un CSR mal formado.

    An unexpected error occurred:
    The CSR is unacceptable (eg, due to a short key) :: Wrong number of DNSNAME fields in Subject Alternative Name.

    La causa raíz se puede encontrar en el registro del servidor EJBCA en modo DEBUG. Para obtener más información sobre los niveles de registro, consulte Registro .

    [...] DEBUG [org.ejbca.ui.web.protocol.acme.logic.AcmeOrderSessionBean] (default task-1) [...] Request does not fulfill end entity profile (1430683098): Wrong number of DNSNAME fields in Subject Alternative Name.

    Cambie la configuración del perfil de la entidad final según corresponda o genere su propio CSR y agréguelo al comando Certbot con la opción --csr .

    Tipo de clave privada no compatible o EKU insuficiente u otros problemas en la configuración del perfil del certificado

    La inscripción del certificado puede fallar porque no se cumplen las restricciones del perfil del certificado, es decir, debido a una clave corta, un EKU insuficiente (debe ser autenticación del servidor) u otras restricciones de perfil.

    Informe de archivo de registro y salida de CLI de Certbot sobre un CSR mal formado.

    An unexpected error occurred:
    The CSR is unacceptable (eg, due to a short key) :: Key bit length was not one of '[8192]'.

    La causa raíz se puede encontrar en el registro del servidor EJBCA en modo INFO. Para obtener más información sobre los niveles de registro, consulte Registro .

    [...] INFO [org.ejbca.ui.web.protocol.acme.web.AcmeProblemExceptionMapper] (default task-1) Responding to request with problem report of type urn:ietf:params:acme:error:badCSR and detail 'Key bit length was not one of '[8192]'.'

    Cambie la configuración del perfil del certificado según corresponda o genere su propio CSR y agréguelo al comando Certbot con la opción --csr .