{"id":1579,"library":"ndg-httpsclient","title":"ndg-httpsclient: Enhanced HTTPS with PyOpenSSL","description":"ndg-httpsclient provides enhanced HTTPS support for Python's standard library modules `httplib` and `urllib2` (Python 2) or `http.client` and `urllib.request` (Python 3) using PyOpenSSL. It allows for advanced SSL/TLS features like Server Name Indication (SNI) and robust peer certificate verification, extending capabilities beyond the default standard library implementation. The current version is 0.5.1, with a relatively slow release cadence focused on compatibility and critical fixes.","status":"active","version":"0.5.1","language":"python","source_language":"en","source_url":"https://github.com/cedadev/ndg_httpsclient/","tags":["https","ssl","tls","pyopenssl","httplib","urllib2","urllib.request","http.client","security"],"install":[{"cmd":"pip install ndg-httpsclient","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core functionality relies on PyOpenSSL for SSL/TLS operations.","package":"pyopenssl"},{"reason":"A transitive dependency of PyOpenSSL.","package":"cryptography","optional":true}],"imports":[{"symbol":"open_url","correct":"from ndg.httpsclient.utils import open_url"},{"symbol":"ServerSSLCertVerification","correct":"from ndg.httpsclient.ssl_peer_verification import ServerSSLCertVerification"},{"symbol":"SubjectAlternativeNameMatcher","correct":"from ndg.httpsclient.ssl_peer_verification import SubjectAlternativeNameMatcher"}],"quickstart":{"code":"import sys\nimport ssl\n# PyOpenSSL is a dependency that ndg-httpsclient leverages\nfrom OpenSSL import SSL\n\n# ndg-httpsclient patches these modules, so they should benefit from its enhancements\nif sys.version_info[0] >= 3:\n    import urllib.request as request_mod\n    import http.client as http_client_mod\nelse:\n    import urllib2 as request_mod\n    import httplib as http_client_mod\n\n# The primary utility for direct use is open_url\nfrom ndg.httpsclient.utils import open_url\n\n# For this example, we'll try a common HTTPS URL.\n# In a real-world scenario, you might pass specific client certificates (c, k)\n# or a custom CA bundle (ca) for peer verification.\ntarget_url = \"https://www.google.com\"\n\nprint(f\"Attempting to connect to {target_url} using ndg-httpsclient's open_url...\")\n\ntry:\n    # open_url utilizes the PyOpenSSL-backed HTTPS handling provided by ndg-httpsclient\n    # For more robust verification, you'd provide `ca='path/to/ca-bundle.pem'`\n    response = open_url(target_url)\n\n    print(f\"Connection successful!\")\n    print(f\"HTTP Status Code: {response.getcode()}\")\n    print(f\"Content-Type: {response.info()['Content-Type']}\")\n    # Read and decode a small part of the content to demonstrate success\n    # Do not read full content for quickstart to avoid large output\n    content_snippet = response.read(200).decode('utf-8', errors='ignore')\n    print(f\"Partial Content: {content_snippet}...\")\n\nexcept SSL.Error as e:\n    print(f\"SSL Error during connection: {e}\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")","lang":"python","description":"This quickstart demonstrates using `ndg-httpsclient`'s `open_url` utility to make an HTTPS request. This function internally leverages the PyOpenSSL-enhanced `HTTPSHandler` that the library integrates into Python's standard HTTP client modules. For more advanced use, like client certificate authentication or custom CA bundles, additional arguments can be passed to `open_url`."},"warnings":[{"fix":"Upgrade Python to a supported version (e.g., Python 3.6+) or pin `ndg-httpsclient<0.5.1`.","message":"Support for Python 2.6 and Python 3.3 was dropped in version 0.5.1. Users on these End-of-Life Python versions must use an older `ndg-httpsclient` version or upgrade their Python environment.","severity":"breaking","affected_versions":">=0.5.1"},{"fix":"Understand that this library is a low-level enhancement for specific SSL/TLS requirements, not a replacement for higher-level HTTP client libraries.","message":"ndg-httpsclient primarily enhances Python's lower-level `httplib`/`urllib2` (Python 2) or `http.client`/`urllib.request` (Python 3) modules with PyOpenSSL. It is not a general-purpose HTTP client like `requests` and requires understanding of the underlying standard library modules for effective use. It's often used in scenarios needing fine-grained SSL/TLS control.","severity":"gotcha","affected_versions":"All"},{"fix":"If relying on `ndg.httpsclient.utils.open_url`, ensure you are on version 0.4.3 or higher.","message":"Version 0.4.2 introduced a bug in the `ndg.httpsclient.utils.open_url` function (a duplicate open call). This bug was fixed in version 0.4.3. Importantly, this specific bug *did not affect* the core `httplib` and `urllib2` interfaces that the package patches, only the higher-level `open_url` utility.","severity":"gotcha","affected_versions":"0.4.2"},{"fix":"For most new HTTP-related projects, consider `requests`. Use `ndg-httpsclient` when explicit PyOpenSSL control or compatibility with existing standard library code is a strict requirement.","message":"While `ndg-httpsclient` provides Python 3 compatibility, the standard library modules it enhances (`urllib.request`, `http.client`) are often superseded by higher-level, more user-friendly libraries like `requests` for general-purpose HTTP communication. This library remains relevant for niche applications requiring deep PyOpenSSL integration.","severity":"deprecated","affected_versions":"All"},{"fix":"Update calls to `ndg.httpsclient.utils.open_url` to provide the `config` argument, or pin `ndg-httpsclient<0.5.0` if the older signature is required.","message":"The `ndg.httpsclient.utils.open_url` function's signature changed in version 0.5.0, now requiring a `config` argument. Calls to `open_url()` without this argument will raise a `TypeError`.","severity":"breaking","affected_versions":">=0.5.0"}],"env_vars":null,"search_vec":"'0.5.1':62 '2':25 '3':31 'advanc':37 'allow':35 'beyond':52 'cadenc':68 'capabl':51 'certif':48 'compat':71 'critic':73 'current':59 'default':54 'enhanc':4,12 'extend':50 'featur':39 'fix':74 'focus':69 'http.client':27,82 'httplib':21,79 'https':5,13,75 'httpsclient':3,10 'implement':57 'indic':43 'librari':19,56 'like':40 'modul':20 'name':42 'ndg':2,9 'ndg-httpsclient':1,8 'peer':47 'provid':11 'pyopenssl':7,33,78 'python':16,24,30 'relat':65 'releas':67 'robust':46 'secur':83 'server':41 'slow':66 'sni':44 'ssl':76 'ssl/tls':38 'standard':18,55 'support':14 'tls':77 'urllib.request':29,81 'urllib2':23,80 'use':32 'verif':49 'version':60","created_at":"2026-04-09T03:54:11.883266+00:00","updated_at":"2026-04-16T17:20:27.894359+00:00","problems":[{"fix":"Ensure `pyOpenSSL`, `ndg-httpsclient`, and `pyasn1` are installed and up-to-date using `pip install --upgrade pyOpenSSL ndg-httpsclient pyasn1` to provide more robust SSL/TLS capabilities, especially for SNI and certificate verification. Updating system CA certificates may also be necessary.","cause":"This error indicates that the client could not verify the server's SSL certificate, often due to missing or outdated CA certificates, hostname mismatch, or an insufficient SSL/TLS configuration in older Python environments that ndg-httpsclient aims to enhance.","error":"SSLError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed"},{"fix":"Install `pyOpenSSL`, `ndg-httpsclient`, and `pyasn1` using `pip install pyOpenSSL ndg-httpsclient pyasn1` to provide enhanced SSL/TLS capabilities, including SNI support, for older Python environments.","cause":"This warning (often accompanied by `SNIMissingWarning`) occurs on Python versions older than 2.7.9/2.7.10, where the standard library's SSL module lacks full features like Server Name Indication (SNI) or a true `SSLContext` object, leading to potential security vulnerabilities or connection failures.","error":"InsecurePlatformWarning: A true SSLContext object is not available. This prevents urllib3 from configuring SSL appropriately and may cause certain SSL connections to fail."},{"fix":"Install `pyOpenSSL` using pip: `pip install pyOpenSSL`. On some systems, development headers for OpenSSL (`libssl-dev` on Debian/Ubuntu, `openssl-devel` on Fedora) and `libffi-dev` might be required before installing `pyOpenSSL` and its dependencies.","cause":"This error means the `pyOpenSSL` library, a fundamental dependency for `ndg-httpsclient` to function by providing advanced SSL/TLS features, is either not installed or not accessible in the current Python environment.","error":"ImportError: No module named OpenSSL"},{"fix":"Ensure `pyOpenSSL`, `ndg-httpsclient`, and `pyasn1` are installed and up-to-date (`pip install --upgrade pyOpenSSL ndg-httpsclient pyasn1`) to provide robust SSL/TLS capabilities and SNI support. Verify the server's SSL/TLS configuration for compatibility and ensure the client platform's OpenSSL libraries are correctly configured.","cause":"This general error indicates that the initial negotiation between the client (using `ndg-httpsclient` for enhanced SSL) and the server to establish a secure SSL/TLS connection failed, which can be due to various reasons like protocol mismatches, unsupported ciphers, server misconfiguration, or lack of proper SNI support from the client.","error":"SSL handshake failed"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.5.1","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/cedadev/ndg_httpsclient","docs":null,"changelog":null,"pypi":"https://pypi.org/project/ndg-httpsclient/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["http-networking","auth-security"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-27","next_check":"2026-07-28","install_tag":null}}