Logo
Nuevos usuarios de RPC: 35% de descuento el primer mesVer oferta
OnFinality Learn
Solución de problemas9 min de lectura

Error de verificación de certificados en Python: diagnosticar y corregir errores TLS

Determina la causa de los errores de verificación de certificados en Python y restablece conexiones HTTPS confiables sin desactivar las comprobaciones TLS.

TL;DR

Un error de verificación de certificados en Python significa que el cliente TLS no pudo establecer que el certificado presentado para una conexión fuera válido y confiable para el nombre de host solicitado. Comienza con el mensaje de error completo, el intérprete de Python y la biblioteca cliente utilizados, además de la ruta de red; después, corrige el reloj, el nombre de host, la cadena de certificados del servidor o la configuración de la CA de confianza que indiquen las evidencias. Para infraestructura privada o un proxy de inspección autorizado, configura un paquete de CA obtenido de un administrador de confianza en lugar de desactivar la verificación. Esta guía proporciona diagnósticos reproducibles para HTTPS de la biblioteca estándar, requests y pip, incluido cómo confirmar la solución.

Primera respuesta y alcance del diagnóstico

Cuando veas [SSL: CERTIFICATE_VERIFY_FAILED], conserva la excepción completa, especialmente el texto posterior a certificate verify failed. Un certificado caducado, una discrepancia del nombre de host y la falta del emisor pueden producir la misma excepción general, pero requieren soluciones diferentes. Comprueba la fecha, la hora y la zona horaria del equipo; confirma que la URL utiliza el nombre de host previsto; e identifica si el error se produce en urllib, requests, pip u otro cliente.

Reproduce el error con el mismo intérprete, entorno, URL y ruta de red que utiliza la aplicación. Para un endpoint RPC de blockchain mediante HTTPS, no pegues una clave de API ni una URL completa que contenga credenciales en registros o tickets de soporte. Este artículo cubre la verificación del certificado del servidor; la autenticación mediante certificado de cliente es un problema de configuración independiente.

Que un navegador funcione correctamente no demuestra que Python también lo haga: el navegador y el cliente de Python pueden utilizar almacenes de confianza, configuraciones de proxy o certificados intermedios en caché diferentes. Del mismo modo, una conexión TLS correcta solo establece un canal cifrado autenticado; no demuestra que un método RPC o una credencial de aplicación sean correctos.

  • Registra el nombre de host exacto, los detalles de la excepción, la biblioteca cliente, la versión de Python, el sistema operativo o contenedor y si interviene un proxy.
  • Si solo falla un servicio, investiga su certificado y su cadena; si fallan muchos servicios no relacionados en el mismo entorno, investiga la confianza local, la hora y la interceptación de red.
  • Mantén activada la verificación durante el diagnóstico. Nunca consideres verify=False ni un contexto SSL global sin verificación como una solución para producción.

Requisitos previos e inventario del entorno

Utiliza un terminal en el entorno que realmente falla: un entorno virtual, contenedor, worker remoto o kernel de notebook puede no compartir los paquetes ni los certificados del Python del sistema. El siguiente script de la biblioteca estándar no requiere acceso a la red. Ejecútalo con el intérprete que inicia tu aplicación; en Windows, utiliza el iniciador py correspondiente si es necesario.

Las rutas predeterminadas que informa ssl describen la configuración predeterminada de OpenSSL, no necesariamente el paquete de CA que utiliza cada biblioteca HTTP. Las variables de entorno pueden modificar el comportamiento del cliente y la configuración explícita de la aplicación puede anular los valores predeterminados. Considera el resultado como un punto de partida, no como una prueba de qué certificado verificó una conexión concreta.

  • Inspecciona la configuración del proxy por separado sin imprimir credenciales: HTTPS_PROXY, HTTP_PROXY y NO_PROXY pueden afectar a la ruta.
  • Para pip, ejecuta python -m pip --version con el mismo intérprete. En un notebook, inspecciona sys.executable dentro del kernel.
  • Las rutas, las variables de entorno y los paquetes de CA instalados pueden diferir entre un host y su contenedor o trabajo de CI.
import os
import ssl
import sys

print('Python executable:', sys.executable)
print('Python version:', sys.version)
print('OpenSSL:', ssl.OPENSSL_VERSION)
print('Default verify paths:', ssl.get_default_verify_paths())
for name in ('SSL_CERT_FILE', 'SSL_CERT_DIR', 'REQUESTS_CA_BUNDLE', 'CURL_CA_BUNDLE', 'PIP_CERT'):
    print(f'{name}:', os.environ.get(name, '<unset>'))
try:
    import requests
    print('requests version:', requests.__version__)
    print('requests default bundle:', requests.certs.where())
except ImportError:
    print('requests is not installed in this interpreter')

Verificación de certificados y almacenes de confianza

Durante un handshake TLS, el servidor presenta un certificado y normalmente proporciona los certificados intermedios necesarios para construir una cadena hasta una autoridad certificadora (CA) raíz de confianza. El cliente comprueba esa cadena, los periodos de validez de los certificados y el nombre de host solicitado. Un error puede significar que el servidor omitió un certificado intermedio, que el paquete de confianza local no contiene la raíz correspondiente o que el certificado presentado no es válido para el nombre de host.

Un proxy corporativo de inspección TLS puede terminar y volver a emitir certificados HTTPS utilizando una CA controlada por la organización. Si el proxy está autorizado, el cliente de Python debe confiar en la CA de organización adecuada, además de en las raíces públicas necesarias para otros destinos. Obtén la CA o el paquete aprobado mediante el proceso autenticado de distribución de tu organización; no confíes ciegamente en un certificado descargado de la conexión que está fallando.

El módulo estándar ssl de Python puede cargar valores predeterminados del sistema o configurados por OpenSSL. Requests suele utilizar un paquete de CA proporcionado mediante la configuración de sus dependencias, a menudo certifi, mientras que el comportamiento de pip depende de su versión y de la versión de Python. Instalar o importar certifi por sí solo no configura todos los clientes para que lo utilicen. Consulta la documentación de SSL de Python y la documentación de Requests sobre la verificación de certificados para conocer el comportamiento del cliente correspondiente.

Reproducción con la biblioteca estándar

Define RPC_URL con la URL HTTPS que falla y ejecuta este script con el intérprete afectado. Para un servicio web general, la misma prueba funciona con su URL HTTPS. El script envía una solicitud GET, así que utiliza un endpoint en el que esa solicitud sea aceptable; no necesita una respuesta correcta de la aplicación para probar el handshake TLS. Evita mostrar o compartir la variable si contiene una clave.

Un error HTTP como 401, 404 o 405 se informa por separado a continuación: indica que TLS se completó y que el servidor devolvió una respuesta HTTP, no que la solicitud de la aplicación se haya realizado correctamente. Una excepción de verificación muestra el mensaje de verificación de OpenSSL cuando está disponible.

  • Compara el resultado dentro y fuera del contenedor o proxy solo cuando la política lo permita; una diferencia acota la investigación, pero no identifica por sí sola la causa.
  • La biblioteca estándar puede respetar las variables de entorno del proxy. Una prueba de conexión directa y una solicitud de aplicación mediante proxy pueden llegar a presentadores de certificados diferentes.
  • Los tiempos de espera, los errores de DNS y los rechazos de conexión no son errores de verificación de certificados; diagnostica esos problemas de red por separado.
import os
import ssl
import urllib.error
import urllib.request

url = os.environ['RPC_URL']
if not url.lower().startswith('https://'):
    raise SystemExit('RPC_URL must use HTTPS')
try:
    with urllib.request.urlopen(url, timeout=10) as response:
        print('TLS succeeded; HTTP status:', response.status)
except urllib.error.HTTPError as exc:
    print('TLS succeeded; HTTP error status:', exc.code)
except urllib.error.URLError as exc:
    reason = exc.reason
    if isinstance(reason, ssl.SSLCertVerificationError):
        print('Certificate verification failed:', reason.verify_message)
    else:
        print('Connection failed:', type(reason).__name__, str(reason))

Interpretación de los detalles del error de certificado

Utiliza el mensaje más específico y el inventario de tu entorno para elegir una solución. La redacción de los errores varía según las versiones de Python y OpenSSL; un error relacionado únicamente con el emisor no permite distinguir entre una cadena incompleta del servidor, un ancla de confianza ausente en el cliente o un proxy de inspección.

Si administras el servicio, inspecciona los certificados hoja e intermedios presentados en la ruta real, incluido SNI para el nombre de host solicitado. Por ejemplo, openssl s_client -connect HOST:443 -servername HOST -showcerts muestra los certificados presentados por una conexión directa; sustituye HOST por el nombre de host, no por una URL. Este comando no reproduce automáticamente una ruta mediante proxy HTTP, y los certificados mostrados no demuestran por sí solos que la cadena sea de confianza. No compartas datos de conexión confidenciales.

  • certificate has expired o not yet valid: comprueba el reloj del sistema y las fechas de validez del certificado; renueva o sustituye un certificado de servidor no válido.
  • hostname mismatch o una discrepancia de dirección IP: utiliza el nombre de host DNS previsto o pide al operador del servidor que emita un certificado cuyos nombres alternativos del sujeto cubran la dirección utilizada.
  • unable to get local issuer certificate o self-signed certificate in certificate chain: investiga los certificados intermedios servidos, el paquete de CA del cliente y el proxy autorizado antes de modificar la confianza.
  • Una implementación privada o autofirmada necesita un certificado o una CA privada en los que se confíe explícitamente, distribuidos y rotados mediante un proceso controlado.

Configuración del paquete de CA para clientes de Python

Como primera opción, corrige en el servidor la cadena incompleta de un servidor público y actualiza los paquetes de CA compatibles del entorno afectado. Para una CA privada autorizada o un proxy de inspección, obtén un paquete PEM de tu administrador y verifica su procedencia antes de utilizarlo. Un paquete explícito puede sustituir las raíces habituales del cliente en lugar de añadirlas, así que proporciona un paquete aprobado que contenga todas las anclas de confianza requeridas por los destinos de la aplicación. Confiar en una raíz adicional amplía los emisores que pueden autenticar esos destinos; limita el alcance de los accesos y los cambios en consecuencia.

El siguiente ejemplo carga un paquete aprobado en el contexto predeterminado de la biblioteca estándar y realiza una solicitud HTTPS. Define CA_BUNDLE con la ruta absoluta a un archivo PEM y RPC_URL con el endpoint previsto. Proporcionar cafile aquí utiliza ese paquete en lugar de cargar implícitamente los certificados de CA predeterminados; la verificación del nombre de host sigue activada.

En Requests, la configuración equivalente por solicitud es requests.get(url, verify='/path/to/approved-bundle.pem', timeout=10). Una sesión puede utilizar session.verify como valor predeterminado limitado a ese ámbito. REQUESTS_CA_BUNDLE puede configurar Requests mediante el entorno; los valores predeterminados basados en OpenSSL pueden utilizar en su lugar SSL_CERT_FILE. Estas variables no ofrecen garantías intercambiables para todas las bibliotecas y la configuración explícita puede tener prioridad. Consulta la documentación del cliente específico.

import os
import ssl
import urllib.error
import urllib.request

url = os.environ['RPC_URL']
if not url.lower().startswith('https://'):
    raise SystemExit('RPC_URL must use HTTPS')
context = ssl.create_default_context(cafile=os.environ['CA_BUNDLE'])
try:
    with urllib.request.urlopen(url, context=context, timeout=10) as response:
        print('TLS succeeded; HTTP status:', response.status)
except urllib.error.HTTPError as exc:
    print('TLS succeeded; HTTP error status:', exc.code)
except urllib.error.URLError as exc:
    print('Connection failed:', type(exc.reason).__name__, str(exc.reason))

pip, sistemas operativos y entornos aislados

Si falla python -m pip install, verifica primero el intérprete, la versión de pip, el nombre de host del índice, la ruta del proxy y el reloj. Pip admite un paquete de CA para un solo uso mediante python -m pip install --cert /path/to/approved-bundle.pem PACKAGE; sustituye ambos marcadores de posición. La configuración PIP_CERT es otra opción. Un paquete utilizado para instalar paquetes debe cubrir los índices de paquetes y cualquier otro host HTTPS al que pip se conecte.

El comportamiento del almacén de certificados de pip depende de la versión. Según la documentación de certificados HTTPS de pip, pip 24.2 y posteriores en Python 3.10 o posteriores utilizan de forma predeterminada los certificados del sistema, además de certifi. Las combinaciones anteriores son diferentes. Actualiza pip o los paquetes de CA a través de un canal que ya sea de confianza cuando corresponda; un intento de actualización no puede corregir una descarga si esa misma descarga está bloqueada por el mismo error de confianza.

En Python instalado desde python.org en macOS, la instalación puede incluir un Install Certificates.command para esa versión concreta de Python. Utiliza el script suministrado con la instalación y revisa su comportamiento; no es una solución universal para Python de Homebrew, del sistema o de un contenedor. En Linux y en contenedores, comprueba el paquete de certificados de CA de la distribución y su mecanismo de actualización. En Windows, determina qué almacén utiliza el cliente real en lugar de asumir que todas las bibliotecas de Python utilizan automáticamente el almacén de confianza de Windows.

Un entorno virtual, entorno de conda, imagen de contenedor o kernel de notebook puede tener su propio intérprete y configuración de confianza. Reconstruye o actualiza el entorno mediante su flujo normal de despliegue y reinicia los procesos afectados después de cambiar variables de entorno o archivos de certificados montados. En conda, consulta su propia configuración de SSL y proxy en lugar de asumir que se aplican los ajustes de pip.

Verificación y resultados reproducibles

Después de realizar un cambio específico, vuelve a ejecutar la operación original que fallaba en el mismo entorno y mediante la misma ruta de red. Después, repite la prueba de la biblioteca estándar o la prueba específica de la biblioteca correspondiente. Una conexión reparada debería completar la verificación del certificado con la comprobación del nombre de host activada; la aplicación aún puede devolver un error HTTP de autorización o un error RPC que requiera una investigación independiente.

Registra observaciones en lugar de suponer que todo funciona. La siguiente tabla es una plantilla: completa cada resultado con tus propios datos y omite los secretos. Mantén comparables las condiciones anteriores y posteriores, incluido el intérprete, el nombre de host del endpoint, la ruta del proxy y el paquete de CA.

ComprobaciónAntes del cambioDespués del cambio
Versión del intérprete y del clienteRegístrala localmenteRegístrala localmente
Ruta de red y configuración de CARegístrala localmenteRegístrala localmente
Resultado de la verificación TLS y detalles del errorRegístralo localmenteRegístralo localmente
Resultado HTTP o RPC, si se alcanzóRegístralo localmenteRegístralo localmente

Para una integración RPC, continúa la comprobación TLS con un método no destructivo compatible con tu red y tu cliente. No deduzcas el estado del endpoint únicamente a partir de una respuesta GET y no registres claves de API, encabezados de autorización ni URL completas que contengan credenciales.

Errores persistentes, compensaciones y próximos pasos

Si el error persiste, confirma que el proceso en ejecución realmente lee el paquete actualizado y que el archivo se puede leer dentro de su entorno de ejecución. Comprueba si existe una configuración explícita obsoleta de verify o del contexto SSL, si un proxy presenta un certificado diferente y si la cadena del servidor está incompleta. Compara las evidencias con el operador del servicio o el administrador de red; proporciona el nombre de host, el error sin datos sensibles, las versiones del cliente y los detalles relevantes del emisor del certificado, no secretos.

Un archivo de CA explícito hace que la confianza sea auditable y portable, pero requiere distribución y rotación. Utilizar un almacén del sistema puede simplificar la confianza administrada de forma centralizada, pero solo si el cliente y la versión concretos realmente lo utilizan. Una CA privada debe limitarse a los entornos que la necesiten. Desactivar la verificación omite tanto las comprobaciones de la cadena como del nombre de host, lo que expone las credenciales y las respuestas a la interceptación; no es una solución provisional adecuada.

Para una integración con OnFinality, consulta el servicio de API, comprueba las redes disponibles y utiliza la guía de endpoints RPC para conocer los conceptos relacionados con los endpoints. Consulta los precios de RPC y las opciones de nodos dedicados al planificar la infraestructura, y explora la biblioteca Learn para obtener orientación relacionada con la implementación. Estos recursos no sustituyen el diagnóstico del certificado que se presenta realmente en tu conexión.

RPC Assistant

Recursos relacionados de RPC Assistant

Nunca te preocupes por la infraestructura nuevamente

OnFinality elimina la carga pesada de DevOps para que puedas construir de forma más inteligente y rápida.

Comenzar