{"id":4572,"library":"idna-ssl","title":"idna-ssl","description":"The `idna-ssl` library provides a patch for Python's standard `ssl.match_hostname` function to correctly support Unicode (IDNA) domains. It aims to offer backward compatibility for older Python versions (pre-3.7) where `ssl.match_hostname` had significant issues with internationalized domain names, and to address lingering IDNA2008 compliance problems even in later Python releases. The library's current version is 1.1.0, released in July 2018. The project's GitHub repository has been archived and is read-only since October 2020, indicating it is no longer actively maintained.","status":"abandoned","version":"1.1.0","language":"en","source_language":"en","source_url":"https://github.com/aio-libs/idna-ssl","tags":["ssl","unicode","idna","match_hostname","aiohttp","asyncio","patch"],"install":[{"cmd":"pip install idna-ssl","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"This library patches SSL hostname matching for Internationalized Domain Names (IDNA). The underlying IDNA encoding/decoding is handled by the `idna` library (or the standard library's `encodings.idna`), which this package implicitly depends on for its functionality.","package":"idna","optional":false}],"imports":[{"note":"This function must be called to apply the patch globally to `ssl.match_hostname`.","symbol":"patch_match_hostname","correct":"from idna_ssl import patch_match_hostname"}],"quickstart":{"code":"from idna_ssl import patch_match_hostname\nimport asyncio\nimport aiohttp\n\n# Apply the patch globally as early as possible in your application\npatch_match_hostname()\n\n# Example usage with aiohttp accessing an IDNA domain\nURL = 'https://цфоут.мвд.рф/news/item/8065038/'\n\nasync def main():\n    async with aiohttp.ClientSession() as session:\n        async with session.get(URL) as response:\n            print(f\"Status: {response.status}\")\n            print(f\"Content-Type: {response.headers.get('Content-Type')}\")\n\nif __name__ == '__main__':\n    # This example requires Python 3.7+ for asyncio.run()\n    # For older Python versions, use loop = asyncio.get_event_loop(); loop.run_until_complete(main())\n    try:\n        asyncio.run(main())\n    except RuntimeError:\n        loop = asyncio.get_event_loop()\n        loop.run_until_complete(main())\n","lang":"python","description":"The `patch_match_hostname()` function needs to be imported and called early in your application's lifecycle to apply the necessary fix globally. The example demonstrates its use with `aiohttp` to access a Unicode domain, which would otherwise fail hostname verification on affected Python versions."},"warnings":[{"fix":"Thoroughly test your application's SSL/TLS interactions after applying the patch. Inspect call stacks if unexpected SSL errors occur to identify potential conflicts.","message":"The library applies a global monkey-patch to `ssl.match_hostname`. This can lead to unexpected behavior or conflicts if other libraries also attempt to modify `ssl.match_hostname` or rely on its unpatched behavior. Ensure compatibility with other dependencies.","severity":"breaking","affected_versions":"All versions"},{"fix":"Evaluate if the specific IDNA-related `ssl.match_hostname` issue you are facing is resolved in newer Python versions (3.7+ improved IDNA handling significantly). If possible, consider upgrading Python or finding alternative solutions for IDNA domain validation, such as explicitly using the `idna` library for encoding/decoding before passing to standard `ssl` functions where applicable.","message":"The GitHub repository for `idna-ssl` was archived on October 22, 2020, making it read-only. This indicates the project is no longer actively maintained, and no further updates, bug fixes, or security patches will be provided. Users should be aware of the risks associated with using unmaintained software.","severity":"deprecated","affected_versions":"All versions (due to project status)"},{"fix":"Understand the specific IDNA specification (IDNA2003 vs. IDNA2008, UTS #46) relevant to your use case. If strict IDNA2008 compliance is critical for `ssl.match_hostname`, this library might still be necessary, but consider the 'abandoned' status.","message":"While Python 3.7 and later versions generally improved IDNA handling in `ssl.match_hostname`, the `idna-ssl` library's motivation states that 'IDNA2008 is still broken' even in Python 3.7. This suggests that `idna-ssl` specifically addresses IDNA2008 compliance beyond what the standard library provides, which can be a subtle distinction.","severity":"gotcha","affected_versions":"Python 3.7+ (for the 'still broken' aspect)"},{"fix":"Stay informed about Python's `ssl` module updates and security advisories. If patching, consider whether the patch might interfere with future security enhancements or changes in behavior in `ssl.match_hostname`.","message":"The functionality of `ssl.match_hostname` itself has evolved, particularly concerning wildcard certificate matching, with security fixes (e.g., CVE-2013-7440). Relying on a globally patched version might obscure further security updates to the underlying `ssl` module in newer Python releases.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}