README.txt 5.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185
  1. =============
  2. Python-GSSAPI
  3. =============
  4. .. role:: python(code)
  5. :language: python
  6. .. role:: bash(code)
  7. :language: bash
  8. .. image:: https://travis-ci.org/pythongssapi/python-gssapi.svg?branch=master
  9. :target: https://travis-ci.org/pythongssapi/python-gssapi
  10. .. image:: https://badge.fury.io/gh/pythongssapi%2Fpython-gssapi.svg
  11. :target: http://badge.fury.io/gh/pythongssapi%2Fpython-gssapi
  12. .. image:: https://badge.fury.io/py/gssapi.svg
  13. :target: http://badge.fury.io/py/gssapi
  14. Python-GSSAPI provides both low-level and high level wrappers around the GSSAPI
  15. C libraries. While it focuses on the Kerberos mechanism, it should also be
  16. useable with other GSSAPI mechanisms.
  17. Documentation for the latest released version (including pre-release versions)
  18. can be found at
  19. `https://pythongssapi.github.io/python-gssapi/stable <https://pythongssapi.github.io/python-gssapi/stable>`_.
  20. Documentation for the latest commit on master can be found at
  21. `https://pythongssapi.github.io/python-gssapi/latest <https://pythongssapi.github.io/python-gssapi/latest>`_.
  22. Requirements
  23. ============
  24. Basic
  25. -----
  26. * A working implementation of GSSAPI (such as from MIT Kerberos)
  27. which includes header files
  28. * a C compiler (such as GCC)
  29. * either the `enum34` Python package or Python 3.4+
  30. * the `six` and `decorator` python packages
  31. Compiling from Scratch
  32. ----------------------
  33. To compile from scratch, you will need Cython >= 0.21.1.
  34. For Running the Tests
  35. ---------------------
  36. * the `nose` package (for tests)
  37. * the `shouldbe` package (for tests)
  38. * the `k5test` package
  39. To install test dependencies using pip:
  40. .. code-block:: bash
  41. $ pip install -r test-requirements.txt # Optional, for running test suite
  42. Installation
  43. ============
  44. Easy Way
  45. --------
  46. .. code-block:: bash
  47. $ pip install gssapi
  48. From the Git Repo
  49. -----------------
  50. After being sure to install all the requirements,
  51. .. code-block:: bash
  52. $ git clone https://github.com/pythongssapi/python-gssapi.git
  53. $ python setup.py build
  54. $ python setup.py install
  55. Tests
  56. =====
  57. The tests for for Python-GSSAPI live in `gssapi.tests`. In order to
  58. run the tests, you must have an MIT Kerberos installation (including
  59. the KDC). The tests create a self-contained Kerberos setup, so running
  60. the tests will not interfere with any existing Kerberos installations.
  61. Structure
  62. =========
  63. Python-GSSAPI is composed of two parts: a low-level C-style API which
  64. thinly wraps the underlying RFC 2744 methods, and a high-level, Pythonic
  65. API (which is itself a wrapper around the low-level API). Examples may
  66. be found in the `examples` directory.
  67. Low-Level API
  68. -------------
  69. The low-level API lives in `gssapi.raw`. The methods contained therein
  70. are designed to match closely with the original GSSAPI C methods. All
  71. relevant methods and classes may be imported directly from `gssapi.raw`.
  72. Extension methods will only be imported if they are present. The low-level
  73. API follows the given format:
  74. * Names match the RFC 2744 specification, with the :python:`gssapi_`
  75. prefix removed
  76. * Parameters which use C int constants as enums have
  77. :python:`enum.IntEnum` classes defined, and thus may be passed
  78. either the enum members or integers
  79. * In cases where a specific constant is passed in the C API to represent
  80. a default value, :python:`None` should be passed instead
  81. * In cases where non-integer constants would be used in the API (i.e.
  82. OIDs), enum-like objects have been defined containing named references
  83. to values specified in RFC 2744.
  84. * Major and minor error codes are returned by raising
  85. :python:`gssapi.raw.GSSError`. The major error codes have exceptions
  86. defined in in `gssapi.raw.exceptions` to make it easier to catch specific
  87. errors or categories of errors.
  88. * All other relevant output values are returned via named tuples.
  89. High-Level API
  90. --------------
  91. The high-level API lives directly under :python:`gssapi`. The classes
  92. contained in each file are designed to provide a more Pythonic, Object-Oriented
  93. view of GSSAPI. The exceptions from the low-level API, plus several additional
  94. exceptions, live in `gssapi.exceptions`. The rest of the classes may be
  95. imported directly from `gssapi`. Only classes are exported by `gssapi` --
  96. all functions are methods of classes in the high-level API.
  97. Please note that QoP is not supported in the high-level API, since it has been
  98. deprecated.
  99. Extensions
  100. ----------
  101. In addition to RFC 2743/2744, Python-GSSAPI also has support for:
  102. * RFC 5587 (Extended GSS Mechanism Inquiry APIs)
  103. * RFC 5588 (GSS-API Extension for Storing Delegated Credentials)
  104. * (Additional) Credential Store Extension
  105. * Services4User
  106. * Credentials import-export
  107. * RFC 6680 (GSS-API Naming Extensions)
  108. * DCE and IOV MIC extensions
  109. * `acquire_cred_with_password` and `add_cred_with_password`
  110. * GGF Extensions
  111. The Team
  112. ========
  113. (GitHub usernames in parentheses)
  114. * Solly Ross (@directxman12)
  115. * Robbie Harwood (@frozencemetery)
  116. * Simo Sorce (@simo5)
  117. * Hugh Cole-Baker (@sigmaris)
  118. Get Involved
  119. ============
  120. We welcome new contributions in the form of Issues and Pull Requests on
  121. Github. If you would like to join our discussions, you can find us on
  122. `Freenode <https://webchat.freenode.net/>`_ IRC, channel `#python-gssapi
  123. <irc://freenode.net/python-gssapi>`_.