ssl_.py 19 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513
  1. from __future__ import annotations
  2. import hashlib
  3. import hmac
  4. import os
  5. import socket
  6. import sys
  7. import typing
  8. import warnings
  9. from binascii import unhexlify
  10. from ..exceptions import ProxySchemeUnsupported, SSLError
  11. from .url import _BRACELESS_IPV6_ADDRZ_RE, _IPV4_RE
  12. SSLContext = None
  13. SSLTransport = None
  14. HAS_NEVER_CHECK_COMMON_NAME = False
  15. IS_PYOPENSSL = False
  16. ALPN_PROTOCOLS = ["http/1.1"]
  17. _TYPE_VERSION_INFO = typing.Tuple[int, int, int, str, int]
  18. # Maps the length of a digest to a possible hash function producing this digest
  19. HASHFUNC_MAP = {
  20. length: getattr(hashlib, algorithm, None)
  21. for length, algorithm in ((32, "md5"), (40, "sha1"), (64, "sha256"))
  22. }
  23. def _is_bpo_43522_fixed(
  24. implementation_name: str,
  25. version_info: _TYPE_VERSION_INFO,
  26. pypy_version_info: _TYPE_VERSION_INFO | None,
  27. ) -> bool:
  28. """Return True for CPython 3.8.9+, 3.9.3+ or 3.10+ and PyPy 7.3.8+ where
  29. setting SSLContext.hostname_checks_common_name to False works.
  30. Outside of CPython and PyPy we don't know which implementations work
  31. or not so we conservatively use our hostname matching as we know that works
  32. on all implementations.
  33. https://github.com/urllib3/urllib3/issues/2192#issuecomment-821832963
  34. https://foss.heptapod.net/pypy/pypy/-/issues/3539
  35. """
  36. if implementation_name == "pypy":
  37. # https://foss.heptapod.net/pypy/pypy/-/issues/3129
  38. return pypy_version_info >= (7, 3, 8) # type: ignore[operator]
  39. elif implementation_name == "cpython":
  40. major_minor = version_info[:2]
  41. micro = version_info[2]
  42. return (
  43. (major_minor == (3, 8) and micro >= 9)
  44. or (major_minor == (3, 9) and micro >= 3)
  45. or major_minor >= (3, 10)
  46. )
  47. else: # Defensive:
  48. return False
  49. def _is_has_never_check_common_name_reliable(
  50. openssl_version: str,
  51. openssl_version_number: int,
  52. implementation_name: str,
  53. version_info: _TYPE_VERSION_INFO,
  54. pypy_version_info: _TYPE_VERSION_INFO | None,
  55. ) -> bool:
  56. # As of May 2023, all released versions of LibreSSL fail to reject certificates with
  57. # only common names, see https://github.com/urllib3/urllib3/pull/3024
  58. is_openssl = openssl_version.startswith("OpenSSL ")
  59. # Before fixing OpenSSL issue #14579, the SSL_new() API was not copying hostflags
  60. # like X509_CHECK_FLAG_NEVER_CHECK_SUBJECT, which tripped up CPython.
  61. # https://github.com/openssl/openssl/issues/14579
  62. # This was released in OpenSSL 1.1.1l+ (>=0x101010cf)
  63. is_openssl_issue_14579_fixed = openssl_version_number >= 0x101010CF
  64. return is_openssl and (
  65. is_openssl_issue_14579_fixed
  66. or _is_bpo_43522_fixed(implementation_name, version_info, pypy_version_info)
  67. )
  68. if typing.TYPE_CHECKING:
  69. from ssl import VerifyMode
  70. from typing import TypedDict
  71. from .ssltransport import SSLTransport as SSLTransportType
  72. class _TYPE_PEER_CERT_RET_DICT(TypedDict, total=False):
  73. subjectAltName: tuple[tuple[str, str], ...]
  74. subject: tuple[tuple[tuple[str, str], ...], ...]
  75. serialNumber: str
  76. # Mapping from 'ssl.PROTOCOL_TLSX' to 'TLSVersion.X'
  77. _SSL_VERSION_TO_TLS_VERSION: dict[int, int] = {}
  78. try: # Do we have ssl at all?
  79. import ssl
  80. from ssl import ( # type: ignore[assignment]
  81. CERT_REQUIRED,
  82. HAS_NEVER_CHECK_COMMON_NAME,
  83. OP_NO_COMPRESSION,
  84. OP_NO_TICKET,
  85. OPENSSL_VERSION,
  86. OPENSSL_VERSION_NUMBER,
  87. PROTOCOL_TLS,
  88. PROTOCOL_TLS_CLIENT,
  89. OP_NO_SSLv2,
  90. OP_NO_SSLv3,
  91. SSLContext,
  92. TLSVersion,
  93. )
  94. PROTOCOL_SSLv23 = PROTOCOL_TLS
  95. # Setting SSLContext.hostname_checks_common_name = False didn't work before CPython
  96. # 3.8.9, 3.9.3, and 3.10 (but OK on PyPy) or OpenSSL 1.1.1l+
  97. if HAS_NEVER_CHECK_COMMON_NAME and not _is_has_never_check_common_name_reliable(
  98. OPENSSL_VERSION,
  99. OPENSSL_VERSION_NUMBER,
  100. sys.implementation.name,
  101. sys.version_info,
  102. sys.pypy_version_info if sys.implementation.name == "pypy" else None, # type: ignore[attr-defined]
  103. ):
  104. HAS_NEVER_CHECK_COMMON_NAME = False
  105. # Need to be careful here in case old TLS versions get
  106. # removed in future 'ssl' module implementations.
  107. for attr in ("TLSv1", "TLSv1_1", "TLSv1_2"):
  108. try:
  109. _SSL_VERSION_TO_TLS_VERSION[getattr(ssl, f"PROTOCOL_{attr}")] = getattr(
  110. TLSVersion, attr
  111. )
  112. except AttributeError: # Defensive:
  113. continue
  114. from .ssltransport import SSLTransport # type: ignore[assignment]
  115. except ImportError:
  116. OP_NO_COMPRESSION = 0x20000 # type: ignore[assignment]
  117. OP_NO_TICKET = 0x4000 # type: ignore[assignment]
  118. OP_NO_SSLv2 = 0x1000000 # type: ignore[assignment]
  119. OP_NO_SSLv3 = 0x2000000 # type: ignore[assignment]
  120. PROTOCOL_SSLv23 = PROTOCOL_TLS = 2 # type: ignore[assignment]
  121. PROTOCOL_TLS_CLIENT = 16 # type: ignore[assignment]
  122. _TYPE_PEER_CERT_RET = typing.Union["_TYPE_PEER_CERT_RET_DICT", bytes, None]
  123. def assert_fingerprint(cert: bytes | None, fingerprint: str) -> None:
  124. """
  125. Checks if given fingerprint matches the supplied certificate.
  126. :param cert:
  127. Certificate as bytes object.
  128. :param fingerprint:
  129. Fingerprint as string of hexdigits, can be interspersed by colons.
  130. """
  131. if cert is None:
  132. raise SSLError("No certificate for the peer.")
  133. fingerprint = fingerprint.replace(":", "").lower()
  134. digest_length = len(fingerprint)
  135. if digest_length not in HASHFUNC_MAP:
  136. raise SSLError(f"Fingerprint of invalid length: {fingerprint}")
  137. hashfunc = HASHFUNC_MAP.get(digest_length)
  138. if hashfunc is None:
  139. raise SSLError(
  140. f"Hash function implementation unavailable for fingerprint length: {digest_length}"
  141. )
  142. # We need encode() here for py32; works on py2 and p33.
  143. fingerprint_bytes = unhexlify(fingerprint.encode())
  144. cert_digest = hashfunc(cert).digest()
  145. if not hmac.compare_digest(cert_digest, fingerprint_bytes):
  146. raise SSLError(
  147. f'Fingerprints did not match. Expected "{fingerprint}", got "{cert_digest.hex()}"'
  148. )
  149. def resolve_cert_reqs(candidate: None | int | str) -> VerifyMode:
  150. """
  151. Resolves the argument to a numeric constant, which can be passed to
  152. the wrap_socket function/method from the ssl module.
  153. Defaults to :data:`ssl.CERT_REQUIRED`.
  154. If given a string it is assumed to be the name of the constant in the
  155. :mod:`ssl` module or its abbreviation.
  156. (So you can specify `REQUIRED` instead of `CERT_REQUIRED`.
  157. If it's neither `None` nor a string we assume it is already the numeric
  158. constant which can directly be passed to wrap_socket.
  159. """
  160. if candidate is None:
  161. return CERT_REQUIRED
  162. if isinstance(candidate, str):
  163. res = getattr(ssl, candidate, None)
  164. if res is None:
  165. res = getattr(ssl, "CERT_" + candidate)
  166. return res # type: ignore[no-any-return]
  167. return candidate # type: ignore[return-value]
  168. def resolve_ssl_version(candidate: None | int | str) -> int:
  169. """
  170. like resolve_cert_reqs
  171. """
  172. if candidate is None:
  173. return PROTOCOL_TLS
  174. if isinstance(candidate, str):
  175. res = getattr(ssl, candidate, None)
  176. if res is None:
  177. res = getattr(ssl, "PROTOCOL_" + candidate)
  178. return typing.cast(int, res)
  179. return candidate
  180. def create_urllib3_context(
  181. ssl_version: int | None = None,
  182. cert_reqs: int | None = None,
  183. options: int | None = None,
  184. ciphers: str | None = None,
  185. ssl_minimum_version: int | None = None,
  186. ssl_maximum_version: int | None = None,
  187. ) -> ssl.SSLContext:
  188. """Creates and configures an :class:`ssl.SSLContext` instance for use with urllib3.
  189. :param ssl_version:
  190. The desired protocol version to use. This will default to
  191. PROTOCOL_SSLv23 which will negotiate the highest protocol that both
  192. the server and your installation of OpenSSL support.
  193. This parameter is deprecated instead use 'ssl_minimum_version'.
  194. :param ssl_minimum_version:
  195. The minimum version of TLS to be used. Use the 'ssl.TLSVersion' enum for specifying the value.
  196. :param ssl_maximum_version:
  197. The maximum version of TLS to be used. Use the 'ssl.TLSVersion' enum for specifying the value.
  198. Not recommended to set to anything other than 'ssl.TLSVersion.MAXIMUM_SUPPORTED' which is the
  199. default value.
  200. :param cert_reqs:
  201. Whether to require the certificate verification. This defaults to
  202. ``ssl.CERT_REQUIRED``.
  203. :param options:
  204. Specific OpenSSL options. These default to ``ssl.OP_NO_SSLv2``,
  205. ``ssl.OP_NO_SSLv3``, ``ssl.OP_NO_COMPRESSION``, and ``ssl.OP_NO_TICKET``.
  206. :param ciphers:
  207. Which cipher suites to allow the server to select. Defaults to either system configured
  208. ciphers if OpenSSL 1.1.1+, otherwise uses a secure default set of ciphers.
  209. :returns:
  210. Constructed SSLContext object with specified options
  211. :rtype: SSLContext
  212. """
  213. if SSLContext is None:
  214. raise TypeError("Can't create an SSLContext object without an ssl module")
  215. # This means 'ssl_version' was specified as an exact value.
  216. if ssl_version not in (None, PROTOCOL_TLS, PROTOCOL_TLS_CLIENT):
  217. # Disallow setting 'ssl_version' and 'ssl_minimum|maximum_version'
  218. # to avoid conflicts.
  219. if ssl_minimum_version is not None or ssl_maximum_version is not None:
  220. raise ValueError(
  221. "Can't specify both 'ssl_version' and either "
  222. "'ssl_minimum_version' or 'ssl_maximum_version'"
  223. )
  224. # 'ssl_version' is deprecated and will be removed in the future.
  225. else:
  226. # Use 'ssl_minimum_version' and 'ssl_maximum_version' instead.
  227. ssl_minimum_version = _SSL_VERSION_TO_TLS_VERSION.get(
  228. ssl_version, TLSVersion.MINIMUM_SUPPORTED
  229. )
  230. ssl_maximum_version = _SSL_VERSION_TO_TLS_VERSION.get(
  231. ssl_version, TLSVersion.MAXIMUM_SUPPORTED
  232. )
  233. # This warning message is pushing users to use 'ssl_minimum_version'
  234. # instead of both min/max. Best practice is to only set the minimum version and
  235. # keep the maximum version to be it's default value: 'TLSVersion.MAXIMUM_SUPPORTED'
  236. warnings.warn(
  237. "'ssl_version' option is deprecated and will be "
  238. "removed in urllib3 v2.1.0. Instead use 'ssl_minimum_version'",
  239. category=DeprecationWarning,
  240. stacklevel=2,
  241. )
  242. # PROTOCOL_TLS is deprecated in Python 3.10 so we always use PROTOCOL_TLS_CLIENT
  243. context = SSLContext(PROTOCOL_TLS_CLIENT)
  244. if ssl_minimum_version is not None:
  245. context.minimum_version = ssl_minimum_version
  246. else: # Python <3.10 defaults to 'MINIMUM_SUPPORTED' so explicitly set TLSv1.2 here
  247. context.minimum_version = TLSVersion.TLSv1_2
  248. if ssl_maximum_version is not None:
  249. context.maximum_version = ssl_maximum_version
  250. # Unless we're given ciphers defer to either system ciphers in
  251. # the case of OpenSSL 1.1.1+ or use our own secure default ciphers.
  252. if ciphers:
  253. context.set_ciphers(ciphers)
  254. # Setting the default here, as we may have no ssl module on import
  255. cert_reqs = ssl.CERT_REQUIRED if cert_reqs is None else cert_reqs
  256. if options is None:
  257. options = 0
  258. # SSLv2 is easily broken and is considered harmful and dangerous
  259. options |= OP_NO_SSLv2
  260. # SSLv3 has several problems and is now dangerous
  261. options |= OP_NO_SSLv3
  262. # Disable compression to prevent CRIME attacks for OpenSSL 1.0+
  263. # (issue #309)
  264. options |= OP_NO_COMPRESSION
  265. # TLSv1.2 only. Unless set explicitly, do not request tickets.
  266. # This may save some bandwidth on wire, and although the ticket is encrypted,
  267. # there is a risk associated with it being on wire,
  268. # if the server is not rotating its ticketing keys properly.
  269. options |= OP_NO_TICKET
  270. context.options |= options
  271. # Enable post-handshake authentication for TLS 1.3, see GH #1634. PHA is
  272. # necessary for conditional client cert authentication with TLS 1.3.
  273. # The attribute is None for OpenSSL <= 1.1.0 or does not exist when using
  274. # an SSLContext created by pyOpenSSL.
  275. if getattr(context, "post_handshake_auth", None) is not None:
  276. context.post_handshake_auth = True
  277. # The order of the below lines setting verify_mode and check_hostname
  278. # matter due to safe-guards SSLContext has to prevent an SSLContext with
  279. # check_hostname=True, verify_mode=NONE/OPTIONAL.
  280. # We always set 'check_hostname=False' for pyOpenSSL so we rely on our own
  281. # 'ssl.match_hostname()' implementation.
  282. if cert_reqs == ssl.CERT_REQUIRED and not IS_PYOPENSSL:
  283. context.verify_mode = cert_reqs
  284. context.check_hostname = True
  285. else:
  286. context.check_hostname = False
  287. context.verify_mode = cert_reqs
  288. try:
  289. context.hostname_checks_common_name = False
  290. except AttributeError: # Defensive: for CPython < 3.8.9 and 3.9.3; for PyPy < 7.3.8
  291. pass
  292. # Enable logging of TLS session keys via defacto standard environment variable
  293. # 'SSLKEYLOGFILE', if the feature is available (Python 3.8+). Skip empty values.
  294. if hasattr(context, "keylog_filename"):
  295. sslkeylogfile = os.environ.get("SSLKEYLOGFILE")
  296. if sslkeylogfile:
  297. context.keylog_filename = sslkeylogfile
  298. return context
  299. @typing.overload
  300. def ssl_wrap_socket(
  301. sock: socket.socket,
  302. keyfile: str | None = ...,
  303. certfile: str | None = ...,
  304. cert_reqs: int | None = ...,
  305. ca_certs: str | None = ...,
  306. server_hostname: str | None = ...,
  307. ssl_version: int | None = ...,
  308. ciphers: str | None = ...,
  309. ssl_context: ssl.SSLContext | None = ...,
  310. ca_cert_dir: str | None = ...,
  311. key_password: str | None = ...,
  312. ca_cert_data: None | str | bytes = ...,
  313. tls_in_tls: typing.Literal[False] = ...,
  314. ) -> ssl.SSLSocket:
  315. ...
  316. @typing.overload
  317. def ssl_wrap_socket(
  318. sock: socket.socket,
  319. keyfile: str | None = ...,
  320. certfile: str | None = ...,
  321. cert_reqs: int | None = ...,
  322. ca_certs: str | None = ...,
  323. server_hostname: str | None = ...,
  324. ssl_version: int | None = ...,
  325. ciphers: str | None = ...,
  326. ssl_context: ssl.SSLContext | None = ...,
  327. ca_cert_dir: str | None = ...,
  328. key_password: str | None = ...,
  329. ca_cert_data: None | str | bytes = ...,
  330. tls_in_tls: bool = ...,
  331. ) -> ssl.SSLSocket | SSLTransportType:
  332. ...
  333. def ssl_wrap_socket(
  334. sock: socket.socket,
  335. keyfile: str | None = None,
  336. certfile: str | None = None,
  337. cert_reqs: int | None = None,
  338. ca_certs: str | None = None,
  339. server_hostname: str | None = None,
  340. ssl_version: int | None = None,
  341. ciphers: str | None = None,
  342. ssl_context: ssl.SSLContext | None = None,
  343. ca_cert_dir: str | None = None,
  344. key_password: str | None = None,
  345. ca_cert_data: None | str | bytes = None,
  346. tls_in_tls: bool = False,
  347. ) -> ssl.SSLSocket | SSLTransportType:
  348. """
  349. All arguments except for server_hostname, ssl_context, tls_in_tls, ca_cert_data and
  350. ca_cert_dir have the same meaning as they do when using
  351. :func:`ssl.create_default_context`, :meth:`ssl.SSLContext.load_cert_chain`,
  352. :meth:`ssl.SSLContext.set_ciphers` and :meth:`ssl.SSLContext.wrap_socket`.
  353. :param server_hostname:
  354. When SNI is supported, the expected hostname of the certificate
  355. :param ssl_context:
  356. A pre-made :class:`SSLContext` object. If none is provided, one will
  357. be created using :func:`create_urllib3_context`.
  358. :param ciphers:
  359. A string of ciphers we wish the client to support.
  360. :param ca_cert_dir:
  361. A directory containing CA certificates in multiple separate files, as
  362. supported by OpenSSL's -CApath flag or the capath argument to
  363. SSLContext.load_verify_locations().
  364. :param key_password:
  365. Optional password if the keyfile is encrypted.
  366. :param ca_cert_data:
  367. Optional string containing CA certificates in PEM format suitable for
  368. passing as the cadata parameter to SSLContext.load_verify_locations()
  369. :param tls_in_tls:
  370. Use SSLTransport to wrap the existing socket.
  371. """
  372. context = ssl_context
  373. if context is None:
  374. # Note: This branch of code and all the variables in it are only used in tests.
  375. # We should consider deprecating and removing this code.
  376. context = create_urllib3_context(ssl_version, cert_reqs, ciphers=ciphers)
  377. if ca_certs or ca_cert_dir or ca_cert_data:
  378. try:
  379. context.load_verify_locations(ca_certs, ca_cert_dir, ca_cert_data)
  380. except OSError as e:
  381. raise SSLError(e) from e
  382. elif ssl_context is None and hasattr(context, "load_default_certs"):
  383. # try to load OS default certs; works well on Windows.
  384. context.load_default_certs()
  385. # Attempt to detect if we get the goofy behavior of the
  386. # keyfile being encrypted and OpenSSL asking for the
  387. # passphrase via the terminal and instead error out.
  388. if keyfile and key_password is None and _is_key_file_encrypted(keyfile):
  389. raise SSLError("Client private key is encrypted, password is required")
  390. if certfile:
  391. if key_password is None:
  392. context.load_cert_chain(certfile, keyfile)
  393. else:
  394. context.load_cert_chain(certfile, keyfile, key_password)
  395. context.set_alpn_protocols(ALPN_PROTOCOLS)
  396. ssl_sock = _ssl_wrap_socket_impl(sock, context, tls_in_tls, server_hostname)
  397. return ssl_sock
  398. def is_ipaddress(hostname: str | bytes) -> bool:
  399. """Detects whether the hostname given is an IPv4 or IPv6 address.
  400. Also detects IPv6 addresses with Zone IDs.
  401. :param str hostname: Hostname to examine.
  402. :return: True if the hostname is an IP address, False otherwise.
  403. """
  404. if isinstance(hostname, bytes):
  405. # IDN A-label bytes are ASCII compatible.
  406. hostname = hostname.decode("ascii")
  407. return bool(_IPV4_RE.match(hostname) or _BRACELESS_IPV6_ADDRZ_RE.match(hostname))
  408. def _is_key_file_encrypted(key_file: str) -> bool:
  409. """Detects if a key file is encrypted or not."""
  410. with open(key_file) as f:
  411. for line in f:
  412. # Look for Proc-Type: 4,ENCRYPTED
  413. if "ENCRYPTED" in line:
  414. return True
  415. return False
  416. def _ssl_wrap_socket_impl(
  417. sock: socket.socket,
  418. ssl_context: ssl.SSLContext,
  419. tls_in_tls: bool,
  420. server_hostname: str | None = None,
  421. ) -> ssl.SSLSocket | SSLTransportType:
  422. if tls_in_tls:
  423. if not SSLTransport:
  424. # Import error, ssl is not available.
  425. raise ProxySchemeUnsupported(
  426. "TLS in TLS requires support for the 'ssl' module"
  427. )
  428. SSLTransport._validate_ssl_context_for_tls_in_tls(ssl_context)
  429. return SSLTransport(sock, ssl_context, server_hostname)
  430. return ssl_context.wrap_socket(sock, server_hostname=server_hostname)