0
# Names and Name Management
1

2
GSSAPI names represent principals (users, services, or entities) in the authentication system. The Name class provides both creation and manipulation of names, with support for various name types and RFC 6680 naming extensions.
3

4
## Capabilities
5

6
### Name Creation and Import
7

8
Create names from strings, tokens, or existing name objects with support for different name types and composite names.
9

10
```python { .api }
11
class Name(gssapi.raw.names.Name):
12
    def __new__(cls, base=None, name_type=None, token=None, composite=False):
13
        """
14
        Create a new Name object.
15
        
16
        Parameters:
17
        - base: str, bytes, or existing Name object
18
        - name_type: OID specifying the name type (default: hostbased_service)
19
        - token: bytes, exported name token for import
20
        - composite: bool, whether to import as composite name (requires RFC 6680)
21
        
22
        Returns:
23
        Name object
24
        """
25
```
26

27
Usage example:
28

29
```python
30
import gssapi
31

32
# Create from string (hostbased service)
33
name = gssapi.Name('service@hostname.example.com')
34

35
# Create with specific name type
36
name = gssapi.Name('user@REALM.EXAMPLE.COM', name_type=gssapi.NameType.user_name)
37

38
# Import from exported token
39
exported_token = b'...'  # from previous export_name() call
40
name = gssapi.Name(token=exported_token)
41

42
# Create composite name (RFC 6680)
43
name = gssapi.Name(token=composite_token, composite=True)
44
```
45

46
### Name Display and String Conversion
47

48
Convert names to human-readable strings with proper encoding handling.
49

50
```python { .api }
51
def __str__(self):
52
    """Get string representation of the name."""
53

54
def __bytes__(self):
55
    """Get bytes representation of the name."""
56

57
def __unicode__(self):
58
    """Get unicode representation of the name."""
59
```
60

61
### Name Canonicalization
62

63
Canonicalize names to their standard form for a specific mechanism.
64

65
```python { .api }
66
def canonicalize(self, mech):
67
    """
68
    Canonicalize the name for a specific mechanism.
69
    
70
    Parameters:
71
    - mech: OID of the mechanism
72
    
73
    Returns:
74
    Name: Canonicalized name
75
    """
76
```
77

78
Usage example:
79

80
```python
81
import gssapi
82

83
name = gssapi.Name('service@hostname')
84
canonical_name = name.canonicalize(gssapi.MechType.kerberos)
85
```
86

87
### Name Display and Type Conversion
88

89
Display names using different name type syntaxes and access name properties.
90

91
```python { .api }
92
def display_as(self, name_type):
93
    """
94
    Display the name using a specific name type syntax.
95
    
96
    Parameters:
97
    - name_type: OID of the name type to use for display
98
    
99
    Returns:
100
    str: Name displayed in the requested syntax
101
    
102
    Requires RFC 6680 extension.
103
    Warning: May segfault with MIT krb5 < 1.13.3 in certain conditions.
104
    """
105

106
@property
107
def name_type(self):
108
    """The name type (OID) of this name."""
109

110
@property
111
def is_mech_name(self):
112
    """True if this is a mechanism name (requires RFC 6680)."""
113

114
@property
115
def mech(self):
116
    """The mechanism associated with this name (requires RFC 6680)."""
117
```
118

119
### Name Comparison and Operations
120

121
Compare names for equality and perform various name operations.
122

123
```python { .api }
124
def __eq__(self, other):
125
    """Compare names for equality."""
126

127
def __ne__(self, other):
128
    """Compare names for inequality."""
129

130
def __hash__(self):
131
    """Get hash value for the name."""
132
```
133

134
### Name Export
135

136
Export names to tokens for transport or storage.
137

138
```python { .api }
139
def export(self, composite=False):
140
    """
141
    Export the name to a token.
142
    
143
    Parameters:
144
    - composite: bool, export as composite name (requires RFC 6680)
145
    
146
    Returns:
147
    bytes: Exported name token
148
    """
149
```
150

151
### Name Duplication
152

153
Create copies of name objects.
154

155
```python { .api }
156
def duplicate(self):
157
    """
158
    Create a duplicate of the name.
159
    
160
    Returns:
161
    Name: Duplicated name object
162
    """
163
```
164

165
### RFC 6680 Name Attributes (Extension)
166

167
Access and manipulate name attributes when RFC 6680 support is available.
168

169
```python { .api }
170
@property
171
def attributes(self):
172
    """Get list of available name attributes (requires RFC 6680)."""
173

174
def get_attribute(self, attr):
175
    """
176
    Get values for a specific name attribute.
177
    
178
    Parameters:
179
    - attr: str or bytes, attribute name
180
    
181
    Returns:
182
    GetNameAttributeResult: Attribute values and metadata
183
    
184
    Requires RFC 6680 extension.
185
    """
186

187
def set_attribute(self, attr, values, complete=True):
188
    """
189
    Set values for a name attribute.
190
    
191
    Parameters:
192
    - attr: str or bytes, attribute name  
193
    - values: list of str/bytes, attribute values
194
    - complete: bool, whether the attribute value is complete
195
    
196
    Requires RFC 6680 extension.
197
    """
198

199
def delete_attribute(self, attr):
200
    """
201
    Delete a name attribute.
202
    
203
    Parameters:
204
    - attr: str or bytes, attribute name to delete
205
    
206
    Requires RFC 6680 extension.
207
    """
208
```
209

210
Usage example for RFC 6680 extensions:
211

212
```python
213
import gssapi
214

215
name = gssapi.Name('user@REALM.EXAMPLE.COM')
216

217
# Get all available attributes
218
attrs = name.attributes
219

220
# Get specific attribute values
221
if b'mail' in attrs:
222
    mail_info = name.get_attribute('mail')
223
    email_addresses = mail_info.values
224
    
225
# Set attribute values
226
name.set_attribute('department', ['Engineering', 'Security'])
227

228
# Delete an attribute
229
name.delete_attribute('temporary_role')
230
```
231

232
## Low-Level Raw API Functions
233

234
Direct access to the underlying C-style GSSAPI name functions.
235

236
```python { .api }
237
# From gssapi.raw.names module
238
def import_name(name_buffer, name_type=None):
239
    """Import a name from a buffer."""
240

241
def display_name(name, name_type=False):
242
    """Display a name in human-readable form."""
243

244
def compare_name(name1, name2):
245
    """Compare two names for equality."""
246

247
def canonicalize_name(input_name, mech_type):
248
    """Canonicalize a name for a mechanism."""
249

250
def export_name(name):
251
    """Export a name to a token."""
252

253
def duplicate_name(name):
254
    """Duplicate a name."""
255
```
256

257
## Name Types
258

259
```python { .api }
260
from gssapi.raw.types import NameType
261

262
class NameType:
263
    hostbased_service: OID      # service@hostname format
264
    user: OID                   # user@realm format (user_name)
265
    machine_uid: OID            # machine UID (machine_uid_name)
266
    string_uid: OID             # string UID (string_uid_name)
267
    anonymous: OID              # anonymous name
268
    export: OID                 # exported name format
269
    composite_export: OID       # composite exported name (RFC 6680)
270
    kerberos_principal: OID     # Kerberos-specific principal name
271
```
272

273
Usage example:
274

275
```python
276
import gssapi
277

278
# Different name types
279
service_name = gssapi.Name('http@web.example.com', name_type=gssapi.NameType.hostbased_service)
280
user_name = gssapi.Name('alice@EXAMPLE.COM', name_type=gssapi.NameType.user)
281
anon_name = gssapi.Name('', name_type=gssapi.NameType.anonymous)
282
```