PKG-INFO 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381
  1. Metadata-Version: 1.1
  2. Name: requests-gssapi
  3. Version: 1.2.2
  4. Summary: A GSSAPI authentication handler for python-requests
  5. Home-page: https://github.com/pythongssapi/requests-gssapi
  6. Author: Ian Cordasco, Cory Benfield, Michael Komitee, Robbie Harwood
  7. Author-email: rharwood@redhat.com
  8. License: UNKNOWN
  9. Description: requests GSSAPI authentication library
  10. ===============================================
  11. Requests is an HTTP library, written in Python, for human beings. This library
  12. adds optional GSSAPI authentication support and supports mutual
  13. authentication.
  14. It provides a fully backward-compatible shim for the old
  15. python-requests-kerberos library: simply replace ``import requests_kerberos``
  16. with ``import requests_gssapi``. A more powerful interface is provided by the
  17. HTTPSPNEGOAuth component, but this is of course not guaranteed to be
  18. compatible. Documentation below is written toward the new interface.
  19. Basic GET usage:
  20. .. code-block:: python
  21. >>> import requests
  22. >>> from requests_gssapi import HTTPSPNEGOAuth
  23. >>> r = requests.get("http://example.org", auth=HTTPSPNEGOAuth())
  24. ...
  25. The entire ``requests.api`` should be supported.
  26. Setup
  27. -----
  28. In order to use this library, there must already be a Kerberos Ticket-Granting
  29. Ticket (TGT) in a credential cache (ccache). Whether a TGT is available can
  30. be easily determined by running the ``klist`` command. If no TGT is
  31. available, then it first must be obtained (for instance, by running the
  32. ``kinit`` command, or pointing the $KRB5CCNAME to a credential cache with a
  33. valid TGT).
  34. In short, the library will handle the "negotiations" of Kerberos
  35. authentication, but ensuring that a credentials are available and valid is the
  36. responsibility of the user.
  37. Authentication Failures
  38. -----------------------
  39. Client authentication failures will be communicated to the caller by returning
  40. a 401 response. A 401 response may also be the result of expired credentials
  41. (including the TGT).
  42. Mutual Authentication
  43. ---------------------
  44. Mutual authentication is a poorly-named feature of the GSSAPI which doesn't
  45. provide any additional security benefit to most possible uses of
  46. requests_gssapi. Practically speaking, in most mechanism implementations
  47. (including krb5), it requires another round-trip between the client and server
  48. during the authentication handshake. Many clients and servers do not properly
  49. handle the authentication handshake taking more than one round-trip. If you
  50. encounter a MutualAuthenticationError, this is probably why.
  51. So long as you're running over a TLS link whose security guarantees you trust,
  52. there's no benefit to mutual authentication. If you don't trust the link at
  53. all, mutual authentication won't help (since it's not tamper-proof, and GSSAPI
  54. isn't being used post-authentication. There's some middle ground between the
  55. two where it helps a small amount (e.g., passive adversary over
  56. encrypted-but-unverified channel), but for Negotiate (what we're doing here),
  57. it's not generally helpful.
  58. For a more technical explanation of what mutual authentication actually
  59. guarantees, I refer you to rfc2743 (GSSAPIv2), rfc4120 (krb5 in GSSAPI),
  60. rfc4178 (SPNEGO), and rfc4559 (HTTP Negotiate).
  61. DISABLED
  62. ^^^^^^^^
  63. By default, there's no need to explicitly disable mutual authentication.
  64. However, for compatability with older versions of request_gssapi or
  65. requests_kerberos, you can explicitly request it not be attempted:
  66. .. code-block:: python
  67. >>> import requests
  68. >>> from requests_gssapi import HTTPSPNEGOAuth, DISABLED
  69. >>> gssapi_auth = HTTPSPNEGOAuth(mutual_authentication=DISABLED)
  70. >>> r = requests.get("https://example.org", auth=gssapi_auth)
  71. ...
  72. REQUIRED
  73. ^^^^^^^^
  74. This was historically the default, but no longer is. If requested,
  75. ``HTTPSPNEGOAuth`` will require mutual authentication from the server, and if
  76. a server emits a non-error response which cannot be authenticated, a
  77. ``requests_gssapi.errors.MutualAuthenticationError`` will be raised. (See
  78. above for what this means.) If a server emits an error which cannot be
  79. authenticated, it will be returned to the user but with its contents and
  80. headers stripped. If the response content is more important than the need for
  81. mutual auth on errors, (eg, for certain WinRM calls) the stripping behavior
  82. can be suppressed by setting ``sanitize_mutual_error_response=False``:
  83. .. code-block:: python
  84. >>> import requests
  85. >>> from requests_gssapi import HTTPSPNEGOAuth, REQUIRED
  86. >>> gssapi_auth = HTTPSPNEGOAuth(mutual_authentication=REQUIRED, sanitize_mutual_error_response=False)
  87. >>> r = requests.get("https://windows.example.org/wsman", auth=gssapi_auth)
  88. ...
  89. OPTIONAL
  90. ^^^^^^^^
  91. This will cause ``requests_gssapi`` to attempt mutual authentication if the
  92. server advertises that it supports it, and cause a failure if authentication
  93. fails, but not if the server does not support it at all. This is probably not
  94. what you want: link tampering will either cause hard failures, or silently
  95. cause it to not happen at all. It is retained for compatability.
  96. .. code-block:: python
  97. >>> import requests
  98. >>> from requests_gssapi import HTTPSPNEGOAuth, OPTIONAL
  99. >>> gssapi_auth = HTTPSPNEGOAuth(mutual_authentication=OPTIONAL)
  100. >>> r = requests.get("https://example.org", auth=gssapi_auth)
  101. ...
  102. Opportunistic Authentication
  103. ----------------------------
  104. ``HTTPSPNEGOAuth`` can be forced to preemptively initiate the GSSAPI
  105. exchange and present a token on the initial request (and all
  106. subsequent). By default, authentication only occurs after a
  107. ``401 Unauthorized`` response containing a Negotiate challenge
  108. is received from the origin server. This can cause mutual authentication
  109. failures for hosts that use a persistent connection (eg, Windows/WinRM), as
  110. no GSSAPI challenges are sent after the initial auth handshake. This
  111. behavior can be altered by setting ``opportunistic_auth=True``:
  112. .. code-block:: python
  113. >>> import requests
  114. >>> from requests_gssapi import HTTPSPNEGOAuth
  115. >>> gssapi_auth = HTTPSPNEGOAuth(opportunistic_auth=True)
  116. >>> r = requests.get("https://windows.example.org/wsman", auth=gssapi_auth)
  117. ...
  118. Hostname Override
  119. -----------------
  120. If communicating with a host whose DNS name doesn't match its
  121. hostname (eg, behind a content switch or load balancer),
  122. the hostname used for the GSSAPI exchange can be overridden by
  123. passing in a custom name (string or ``gssapi.Name``):
  124. .. code-block:: python
  125. >>> import requests
  126. >>> from requests_gssapi import HTTPSPNEGOAuth
  127. >>> gssapi_auth = HTTPSPNEGOAuth(target_name="internalhost.local")
  128. >>> r = requests.get("https://externalhost.example.org/", auth=gssapi_auth)
  129. ...
  130. Explicit Principal
  131. ------------------
  132. ``HTTPSPNEGOAuth`` normally uses the default principal (ie, the user for whom
  133. you last ran ``kinit`` or ``kswitch``, or an SSO credential if
  134. applicable). However, an explicit credential can be in instead, if desired.
  135. .. code-block:: python
  136. >>> import gssapi
  137. >>> import requests
  138. >>> from requests_gssapi import HTTPSPNEGOAuth
  139. >>> name = gssapi.Name("user@REALM", gssapi.NameType.hostbased_service)
  140. >>> creds = gssapi.Credentials(name=name, usage="initiate")
  141. >>> gssapi_auth = HTTPSPNEGOAuth(creds=creds)
  142. >>> r = requests.get("http://example.org", auth=gssapi_auth)
  143. ...
  144. Explicit Mechanism
  145. ------------------
  146. ``HTTPSPNEGOAuth`` normally lets the underlying ``gssapi`` library decide which
  147. negotiation mechanism to use. However, an explicit mechanism can be used instead
  148. if desired. The ``mech`` parameter will be passed straight through to ``gssapi``
  149. without interference. It is expected to be an instance of ``gssapi.mechs.Mechanism``.
  150. .. code-block:: python
  151. >>> import gssapi
  152. >>> import requests
  153. >>> from requests_gssapi import HTTPSPNEGOAuth
  154. >>> try:
  155. ... spnego = gssapi.mechs.Mechanism.from_sasl_name("SPNEGO")
  156. ... except AttributeError:
  157. ... spnego = gssapi.OID.from_int_seq("1.3.6.1.5.5.2")
  158. >>> gssapi_auth = HTTPSPNEGOAuth(mech=spnego)
  159. >>> r = requests.get("http://example.org", auth=gssapi_auth)
  160. ...
  161. Delegation
  162. ----------
  163. ``requests_gssapi`` supports credential delegation (``GSS_C_DELEG_FLAG``).
  164. To enable delegation of credentials to a server that requests delegation, pass
  165. ``delegate=True`` to ``HTTPSPNEGOAuth``:
  166. .. code-block:: python
  167. >>> import requests
  168. >>> from requests_gssapi import HTTPSPNEGOAuth
  169. >>> r = requests.get("http://example.org", auth=HTTPSPNEGOAuth(delegate=True))
  170. ...
  171. Be careful to only allow delegation to servers you trust as they will be able
  172. to impersonate you using the delegated credentials.
  173. Logging
  174. -------
  175. This library makes extensive use of Python's logging facilities.
  176. Log messages are logged to the ``requests_gssapi`` and
  177. ``requests_gssapi.gssapi`` named loggers.
  178. If you are having difficulty we suggest you configure logging. Issues with the
  179. underlying GSSAPI libraries will be made apparent. Additionally, copious debug
  180. information is made available which may assist in troubleshooting if you
  181. increase your log level all the way up to debug.
  182. History
  183. =======
  184. 1.2.2: 2020-08-07
  185. -----------------
  186. - Use USER_NAME instead of HOSTBASED_SERVICE for user principals
  187. - Remove unused imports in example code
  188. - Fix typo in explicit mech example
  189. 1.2.1: 2020-03-31
  190. -----------------
  191. - Include tests in sdist tarball
  192. - Don't limit contexts to a single server name
  193. 1.2.0: 2020-02-18
  194. -----------------
  195. - Add support for specifing an explicit GSSAPI mech
  196. 1.1.1: 2020-02-18
  197. -----------------
  198. - Fix DOS bug around Negotiate regular expressoin
  199. - Update README to include section on setup
  200. 1.1.0: 2019-05-21
  201. -----------------
  202. - Disable mutual authentication by default
  203. - Add more documentation on MutualAuthenticationError
  204. 1.0.1: 2019-04-10
  205. -----------------
  206. - Fix example in README
  207. - Fix license detection for PyPI
  208. - Fix a problem with regex escaping
  209. - Add COPR Makefile target
  210. 1.0.0: 2017-12-14
  211. -----------------
  212. - Fork project to requests-gssapi
  213. - Replace pykerberos with python-gssapi
  214. - Add HTTPSPNEGOAuth interface. HTTPKerberosAuth is retained as a shim, but
  215. bump the major version anyway for clarity.
  216. 0.11.0: 2016-11-02
  217. ------------------
  218. - Switch dependency on Windows from kerberos-sspi/pywin32 to WinKerberos.
  219. This brings Custom Principal support to Windows users.
  220. 0.10.0: 2016-05-18
  221. ------------------
  222. - Make it possible to receive errors without having their contents and headers
  223. stripped.
  224. - Resolve a bug caused by passing the ``principal`` keyword argument to
  225. kerberos-sspi on Windows.
  226. 0.9.0: 2016-05-06
  227. -----------------
  228. - Support for principal, hostname, and realm override.
  229. - Added support for mutual auth.
  230. 0.8.0: 2016-01-07
  231. -----------------
  232. - Support for Kerberos delegation.
  233. - Fixed problems declaring kerberos-sspi on Windows installs.
  234. 0.7.0: 2015-05-04
  235. -----------------
  236. - Added Windows native authentication support by adding kerberos-sspi as an
  237. alternative backend.
  238. - Prevent infinite recursion when a server returns 401 to an authorization
  239. attempt.
  240. - Reduce the logging during successful responses.
  241. 0.6.1: 2014-11-14
  242. -----------------
  243. - Fix HTTPKerberosAuth not to treat non-file as a file
  244. - Prevent infinite recursion when GSSErrors occurs
  245. 0.6: 2014-11-04
  246. ---------------
  247. - Handle mutual authentication (see pull request 36_)
  248. All users should upgrade immediately. This has been reported to
  249. oss-security_ and we are awaiting a proper CVE identifier.
  250. **Update**: We were issued CVE-2014-8650
  251. - Distribute as a wheel.
  252. .. _36: https://github.com/requests/requests-kerberos/pull/36
  253. .. _oss-security: http://www.openwall.com/lists/oss-security/
  254. 0.5: 2014-05-14
  255. ---------------
  256. - Allow non-HTTP service principals with HTTPKerberosAuth using a new optional
  257. argument ``service``.
  258. - Fix bug in ``setup.py`` on distributions where the ``compiler`` module is
  259. not available.
  260. - Add test dependencies to ``setup.py`` so ``python setup.py test`` will work.
  261. 0.4: 2013-10-26
  262. ---------------
  263. - Minor updates in the README
  264. - Change requirements to depend on requests above 1.1.0
  265. 0.3: 2013-06-02
  266. ---------------
  267. - Work with servers operating on non-standard ports
  268. 0.2: 2013-03-26
  269. ---------------
  270. - Not documented
  271. 0.1: Never released
  272. -------------------
  273. - Initial Release
  274. Platform: UNKNOWN
  275. Classifier: License :: OSI Approved :: ISC License (ISCL)