0
# Python GSSAPI
1

2
Python GSSAPI provides comprehensive bindings for the Generic Security Service Application Program Interface (GSSAPI), offering both low-level C-style API wrappers that closely match RFC 2744 specifications and high-level Pythonic interfaces for easier integration. The library primarily focuses on Kerberos authentication mechanisms while supporting other GSSAPI mechanisms, includes extensive RFC extensions, provides credential management, security context handling, and message protection capabilities.
3

4
## Package Information
5

6
- **Package Name**: gssapi
7
- **Language**: Python
8
- **Installation**: `pip install gssapi`
9
- **Dependencies**: decorator
10
- **Python Version**: 3.9+
11

12
## Core Imports
13

14
```python
15
import gssapi
16
```
17

18
For high-level API classes (recommended):
19

20
```python
21
from gssapi import Name, Credentials, SecurityContext, Mechanism
22
```
23

24
For low-level raw API access:
25

26
```python
27
import gssapi.raw
28
from gssapi.raw import names, creds, sec_contexts, message
29
```
30

31
## Basic Usage
32

33
```python
34
import gssapi
35

36
# Create a name from a string
37
name = gssapi.Name('service@hostname.example.com')
38

39
# Acquire credentials
40
creds = gssapi.Credentials(name=name, usage='initiate')
41

42
# Initiate a security context
43
ctx = gssapi.SecurityContext(
44
    name=gssapi.Name('target@hostname.example.com'),
45
    creds=creds,
46
    usage='initiate'
47
)
48

49
# Perform the authentication handshake
50
token = None
51
while not ctx.complete:
52
    token = ctx.step(token)
53
    if token:
54
        # Send token to acceptor and receive response
55
        pass
56

57
# Wrap and unwrap messages
58
message = b"Hello, GSSAPI!"
59
wrapped = ctx.wrap(message, encrypt=True)
60
unwrapped = ctx.unwrap(wrapped.message)
61
```
62

63
## Architecture
64

65
Python GSSAPI is structured in two primary layers:
66

67
- **High-Level API** (`gssapi`): Object-oriented Pythonic interface with automatic memory management, providing classes for Name, Credentials, SecurityContext, and Mechanism operations.
68
- **Low-Level API** (`gssapi.raw`): Direct C-style bindings matching RFC 2744 specifications, organized into modules for names, credentials, security contexts, messages, and various RFC extensions.
69

70
The high-level classes inherit from low-level classes, enabling interoperability between the two APIs. Extensions are dynamically loaded based on GSSAPI implementation support.
71

72
## Capabilities
73

74
### Names and Name Management
75

76
Name creation, canonicalization, comparison, and RFC 6680 naming extensions for attribute-based name handling and composite name operations.
77

78
```python { .api }
79
class Name:
80
    def __new__(cls, base=None, name_type=None, token=None, composite=False): ...
81
    def canonicalize(self, mech): ...
82
    def __str__(self): ...
83
    def __bytes__(self): ...
84
```
85

86
[Names and Name Management](./names.md)
87

88
### Credential Management
89

90
Credential acquisition, delegation, impersonation, import/export, and credential store operations with support for various authentication mechanisms.
91

92
```python { .api }
93
class Credentials:
94
    def __new__(cls, base=None, token=None, name=None, lifetime=None, mechs=None, usage='both', store=None): ...
95
    @classmethod
96
    def acquire(cls, name=None, lifetime=None, mechs=None, usage='both', store=None): ...
97
    def add(self, name=None, mech=None, usage='both', init_lifetime=None, accept_lifetime=None): ...
98
```
99

100
[Credential Management](./credentials.md)
101

102
### Security Context Operations
103

104
Security context initiation, acceptance, message protection (wrap/unwrap), MIC operations, and context inquiries for secure communication channels.
105

106
```python { .api }
107
class SecurityContext:
108
    def __new__(cls, base=None, token=None, name=None, creds=None, lifetime=None, flags=None, mech=None, channel_bindings=None, usage=None): ...
109
    def step(self, token=None): ...
110
    def wrap(self, message, encrypt=None): ...
111
    def unwrap(self, message, message_buffer=None): ...
112
```
113

114
[Security Context Operations](./security-contexts.md)
115

116
### Low-Level Raw API
117

118
Direct C-style GSSAPI bindings following RFC 2744 specifications, providing fine-grained control over GSSAPI operations and access to all extension functions.
119

120
```python { .api }
121
def acquire_cred(desired_name=None, lifetime=None, desired_mechs=None, cred_usage=None, store=None): ...
122
def init_sec_context(creds, context=None, target_name=None, mech=None, req_flags=None, time_req=None, channel_bindings=None, input_token=None): ...
123
def accept_sec_context(creds, context=None, input_token=None, channel_bindings=None): ...
124
```
125

126
[Low-Level Raw API](./raw-api.md)
127

128
### Mechanism Management
129

130
GSSAPI mechanism handling, inspection, and selection with support for mechanism attributes and capabilities inquiry.
131

132
```python { .api }
133
class Mechanism(gssapi.raw.oids.OID):
134
    def __new__(cls, cpy=None, elements=None): ...
135
    @property
136
    def name_types(self): ...
137
    @property
138
    def sasl_name(self): ...  # requires RFC 5801
139
    @property
140
    def description(self): ...  # requires RFC 5801
141
    @property
142
    def known_attrs(self): ...  # requires RFC 5587
143
    @property
144
    def attrs(self): ...  # requires RFC 5587
145
    @classmethod
146
    def all_mechs(cls): ...
147
    @classmethod
148
    def from_name(cls, name): ...
149
    @classmethod
150
    def from_sasl_name(cls, name): ...  # requires RFC 5801
151
    @classmethod
152
    def from_attrs(cls, desired_attrs=None, except_attrs=None, critical_attrs=None): ...  # requires RFC 5587
153
```
154

155
### Extensions and RFCs
156

157
Support for numerous GSSAPI extensions including RFC 4178 (Negotiation), RFC 5587 (Mechanism Inquiry), RFC 5588 (Credential Store), RFC 5801 (SASL), RFC 6680 (Naming Extensions), Services4User, DCE/IOV operations, and Kerberos-specific extensions.
158

159
```python { .api }
160
# Extension availability varies by GSSAPI implementation
161
from gssapi.raw.ext_s4u import acquire_cred_impersonate_name
162
from gssapi.raw.ext_rfc5588 import store_cred
163
from gssapi.raw.ext_rfc6680 import display_name_ext, get_name_attribute
164
```
165

166
[Extensions and RFCs](./extensions.md)
167

168
## Types
169

170
```python { .api }
171
from gssapi.raw.types import NameType, RequirementFlag, AddressType, MechType, IntEnumFlagSet
172
from gssapi.raw.oids import OID
173

174
class NameType:
175
    hostbased_service: OID
176
    user: OID  # user_name
177
    machine_uid: OID  # machine_uid_name  
178
    string_uid: OID  # string_uid_name
179
    anonymous: OID
180
    export: OID
181
    composite_export: OID  # RFC 6680 extension
182
    kerberos_principal: OID  # Kerberos-specific principal name
183

184
class RequirementFlag(IntEnumFlagSet):
185
    delegate_to_peer: int
186
    mutual_authentication: int
187
    replay_detection: int
188
    out_of_sequence_detection: int  # sequence_detection
189
    confidentiality: int
190
    integrity: int
191
    anonymity: int  # anonymous
192
    protection_ready: int
193
    transferable: int  # transfer_ready
194
    ok_as_delegate: int  # deleg_policy_flag
195
    channel_bound: int
196

197
class MechType:
198
    kerberos: OID
199
    spnego: OID
200
```