-
Notifications
You must be signed in to change notification settings - Fork 46
/
README.txt
181 lines (120 loc) · 5.04 KB
/
README.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
=============
Python-GSSAPI
=============
.. role:: python(code)
:language: python
.. role:: bash(code)
:language: bash
.. image:: https://badge.fury.io/gh/pythongssapi%2Fpython-gssapi.svg
:target: http://badge.fury.io/gh/pythongssapi%2Fpython-gssapi
.. image:: https://badge.fury.io/py/gssapi.svg
:target: http://badge.fury.io/py/gssapi
Python-GSSAPI provides both low-level and high level wrappers around the GSSAPI
C libraries. While it focuses on the Kerberos mechanism, it should also be
useable with other GSSAPI mechanisms.
Documentation can be found at
`https://pythongssapi.github.io/python-gssapi/ <https://pythongssapi.github.io/python-gssapi/>`_.
Requirements
============
Basic
-----
* A working implementation of GSSAPI (such as from MIT Kerberos)
which supports delegation and includes header files
* a C compiler (such as GCC)
* Python 3.8+ (older releases support older versions, but are unsupported)
* the `decorator` python package
Compiling from Scratch
----------------------
To compile from scratch, you will need Cython ``>= 3.0.3, < 4.0.0`` which is automatically
installed by pip in an isolated build virtual environment.
For Running the Tests
---------------------
* the `k5test` package
To install test dependencies using pip:
.. code-block:: bash
$ pip install -r test-requirements.txt # Optional, for running test suite
Installation
============
Easy Way
--------
.. code-block:: bash
$ pip install gssapi
From the Git Repo
-----------------
After being sure to install all the requirements,
.. code-block:: bash
$ git clone https://github.com/pythongssapi/python-gssapi.git
$ pip install .
Tests
=====
The tests for for Python-GSSAPI live in `gssapi.tests`. In order to
run the tests, you must have an MIT Kerberos installation (including
the KDC). The tests create a self-contained Kerberos setup, so running
the tests will not interfere with any existing Kerberos installations.
Structure
=========
Python-GSSAPI is composed of two parts: a low-level C-style API which
thinly wraps the underlying RFC 2744 methods, and a high-level, Pythonic
API (which is itself a wrapper around the low-level API). Examples may
be found in the `examples` directory.
Low-Level API
-------------
The low-level API lives in `gssapi.raw`. The methods contained therein
are designed to match closely with the original GSSAPI C methods. All
relevant methods and classes may be imported directly from `gssapi.raw`.
Extension methods will only be imported if they are present. The low-level
API follows the given format:
* Names match the RFC 2744 specification, with the :python:`gssapi_`
prefix removed
* Parameters which use C int constants as enums have
:python:`enum.IntEnum` classes defined, and thus may be passed
either the enum members or integers
* In cases where a specific constant is passed in the C API to represent
a default value, :python:`None` should be passed instead
* In cases where non-integer constants would be used in the API (i.e.
OIDs), enum-like objects have been defined containing named references
to values specified in RFC 2744.
* Major and minor error codes are returned by raising
:python:`gssapi.raw.GSSError`. The major error codes have exceptions
defined in in `gssapi.raw.exceptions` to make it easier to catch specific
errors or categories of errors.
* All other relevant output values are returned via named tuples.
High-Level API
--------------
The high-level API lives directly under :python:`gssapi`. The classes
contained in each file are designed to provide a more Pythonic, Object-Oriented
view of GSSAPI. The exceptions from the low-level API, plus several additional
exceptions, live in `gssapi.exceptions`. The rest of the classes may be
imported directly from `gssapi`. Only classes are exported by `gssapi` --
all functions are methods of classes in the high-level API.
Please note that QoP is not supported in the high-level API, since it has been
deprecated.
Extensions
----------
In addition to RFC 2743/2744, Python-GSSAPI also has support for:
* RFC 4178 (GSS-API Negotiation Mechanism)
* RFC 5587 (Extended GSS Mechanism Inquiry APIs)
* RFC 5588 (GSS-API Extension for Storing Delegated Credentials)
* RFC 5801 (GSS-API SASL Extensions)
* (Additional) Credential Store Extension
* Services4User
* Credentials import-export
* RFC 6680 (GSS-API Naming Extensions)
* DCE and IOV MIC extensions
* `acquire_cred_with_password` and `add_cred_with_password`
* GGF Extensions
* Kerberos specific extensions
The Team
========
(GitHub usernames in parentheses)
* Jordan Borean (@jborean93) - current maintainer and developer
* Simo Sorce (@simo5) - developer
* Robbie Harwood (@frozencemetery) - author emeritus
* Solly Ross (@directxman12) - author emeritus
* Hugh Cole-Baker (@sigmaris) - author emeritus
Get Involved
============
We welcome new contributions in the form of Issues and Pull Requests on
Github. If you would like to join our discussions, you can find us on
`libera.chat <https://libera.chat/>`_ IRC, channel `#python-gssapi
<irc://libera.chat/python-gssapi>`_.