Skip to content

Commit 35af55c

Browse files
DirectXMan12DirectXMan12
committed
Low-Level: Document Specific Errors
Now that we have specific errors (found in `gssapi.raw.exceptions`), we should document which errors can be thrown. This commit does so for the low-level API. In the case where no errors were documented, the only error documented was the generic GSSError, otherwise, GSSError was removed, and the specific listed errors were added (except in the case where GSS_S_FAILURE is specifically listed, in which case so is GSSError). Note that non-RFC extensions did not have specific errors documented, since they do not have a standardized list of specific errors. Part of #11
1 parent eed8765 commit 35af55c

File tree

5 files changed

+97
-25
lines changed

5 files changed

+97
-25
lines changed

‎gssapi/raw/creds.pyx

Lines changed: 17 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -104,7 +104,11 @@ def acquire_cred(Name name=None, lifetime=None, mechs=None, usage='both'):
104104
indefinite or not supported)
105105
106106
Raises:
107-
GSSError
107+
BadMechanismError
108+
BadNameTypeError
109+
BadNameError
110+
ExpiredCredentialsError
111+
MissingCredentialsError
108112
"""
109113

110114
cdef gss_OID_set desired_mechs
@@ -163,7 +167,7 @@ def release_cred(Creds creds not None):
163167
creds (Creds): the credentials in question
164168
165169
Raises:
166-
GSSError
170+
MissingCredentialsError
167171
"""
168172

169173
cdef OM_uint32 maj_stat, min_stat
@@ -199,8 +203,12 @@ def add_cred(Creds input_cred, Name name not None, OID mech not None,
199203
either indefinite or not supported)
200204
201205
Raises:
202-
GSSError
203-
206+
BadMechanismError
207+
BadNameTypeError
208+
BadNameError
209+
DuplicateCredentialsElementError
210+
ExpiredCredentialsError
211+
MissingCredentialsError
204212
"""
205213
cdef gss_cred_usage_t c_usage
206214
if usage == 'initiate':
@@ -261,7 +269,9 @@ def inquire_cred(Creds creds not None, name=True, lifetime=True, usage=True,
261269
with unused fields set to None
262270
263271
Raises:
264-
GSSError
272+
MissingCredentialsError
273+
InvalidCredentialsError
274+
ExpiredCredentialsError
265275
"""
266276

267277
# TODO(directxman12): add docs
@@ -340,7 +350,8 @@ def inquire_cred_by_mech(Creds creds not None, OID mech not None,
340350
with unused fields set to None
341351
342352
Raises:
343-
GSSError
353+
MissingCredentialsError
354+
InvalidCredentialsError
344355
"""
345356

346357
# TODO(directxman12): add docs

‎gssapi/raw/ext_rfc5588.pyx

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,10 @@ def store_cred(Creds creds not None, usage='both', OID mech=None,
4444
4545
Raises:
4646
GSSError
47+
ExpiredCredentialsError
48+
MissingCredentialsError
49+
OperationUnavailableError
50+
DuplicateCredentialsElementError
4751
"""
4852
cdef gss_OID desired_mech
4953
if mech is not None:

‎gssapi/raw/message.pyx

Lines changed: 25 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -62,7 +62,9 @@ def get_mic(SecurityContext context not None, message, qop=None):
6262
bytes: the generated MIC token
6363
6464
Raises:
65-
GSSError
65+
ExpiredContextError
66+
MissingContextError
67+
BadQoPError
6668
"""
6769

6870
cdef gss_buffer_desc message_buffer = gss_buffer_desc(len(message),
@@ -104,7 +106,14 @@ def verify_mic(SecurityContext context not None, message, token):
104106
int: the QoP used.
105107
106108
Raises:
107-
GSSError
109+
InvalidTokenError
110+
BadMICError
111+
DuplicateTokenError
112+
ExpiredTokenError
113+
TokenTooLateError
114+
TokenTooEarlyError
115+
ExpiredContextError
116+
MissingContextError
108117
"""
109118

110119
cdef gss_buffer_desc message_buffer = gss_buffer_desc(len(message),
@@ -144,7 +153,9 @@ def wrap_size_limit(SecurityContext context not None, OM_uint32 output_size,
144153
int: the maximum unencrypted/unwrapped message size
145154
146155
Raises:
147-
GSSError
156+
MissingContextError
157+
ExpiredContextError
158+
BadQoPError
148159
"""
149160

150161
cdef int conf_req = confidential
@@ -185,7 +196,9 @@ def wrap(SecurityContext context not None, message, confidential=True,
185196
encryption was actually used
186197
187198
Raises:
188-
GSSError
199+
ExpiredContextError
200+
MissingContextError
201+
BadQoPError
189202
"""
190203

191204
cdef int conf_req = confidential
@@ -227,7 +240,14 @@ def unwrap(SecurityContext context not None, message):
227240
encryption was used, and the QoP used
228241
229242
Raises:
230-
GSSError
243+
InvalidTokenError
244+
BadMICError
245+
DuplicateTokenError
246+
ExpiredTokenError
247+
TokenTooLateError
248+
TokenTooEarlyError
249+
ExpiredContextError
250+
MissingContextError
231251
"""
232252

233253
cdef gss_buffer_desc input_buffer = gss_buffer_desc(len(message), message)

‎gssapi/raw/names.pyx

Lines changed: 14 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -80,7 +80,9 @@ def import_name(name not None, OID name_type=None):
8080
Name: the GSSAPI version of the name
8181
8282
Raises:
83-
GSSError
83+
BadNameTypeError
84+
BadNameError
85+
BadMechanismError
8486
"""
8587

8688
cdef gss_OID nt
@@ -126,7 +128,7 @@ def display_name(Name name not None, name_type=True):
126128
DisplayNameResult: the text part of the name and its type
127129
128130
Raises:
129-
GSSError
131+
BadNameError
130132
"""
131133

132134
# GSS_C_EMPTY_BUFFER
@@ -178,7 +180,8 @@ def compare_name(Name name1=None, Name name2=None):
178180
bool: whether or not the names are equal
179181
180182
Raises:
181-
GSSError
183+
BadNameTypeError
184+
BadNameError
182185
"""
183186

184187
# check for either value being None
@@ -221,7 +224,9 @@ def export_name(Name name not None):
221224
bytes: the exported name
222225
223226
Raises:
224-
GSSError
227+
MechanismNameRequiredError
228+
BadNameTypeError
229+
BadNameError
225230
"""
226231

227232
# GSS_C_EMPTY_BUFFER
@@ -258,7 +263,9 @@ def canonicalize_name(Name name not None, OID mech not None):
258263
Name: a canonicalized version of the input name
259264
260265
Raises:
261-
GSSError
266+
BadMechanismError
267+
BadNameTypeError
268+
BadNameError
262269
"""
263270

264271
cdef gss_name_t canonicalized_name
@@ -289,7 +296,7 @@ def duplicate_name(Name name not None):
289296
Name: a duplicate of the input name
290297
291298
Raises:
292-
GSSError
299+
BadNameError
293300
"""
294301

295302
cdef gss_name_t new_name
@@ -314,7 +321,7 @@ def release_name(Name name not None):
314321
name (Name): the name in question
315322
316323
Raises:
317-
GSSError
324+
BadNameError
318325
"""
319326

320327
cdef OM_uint32 maj_stat, min_stat

‎gssapi/raw/sec_contexts.pyx

Lines changed: 37 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -152,7 +152,18 @@ def init_sec_context(Name target_name not None, Creds creds=None,
152152
initiation.
153153
154154
Raises:
155-
GSSError
155+
InvalidTokenError
156+
InvalidCredentialsError
157+
MissingCredentialsError
158+
ExpiredCredentialsError
159+
BadChannelBindingsError
160+
BadMICError
161+
ExpiredTokenError
162+
DuplicateTokenError
163+
MissingContextError
164+
BadNameTypeError
165+
BadNameError
166+
BadMechanismError
156167
"""
157168

158169
cdef gss_OID mech_oid
@@ -260,7 +271,16 @@ def accept_sec_context(input_token not None, Creds acceptor_creds=None,
260271
exchanges are needed to finalize the security context.
261272
262273
Raises:
263-
GSSError
274+
InvalidTokenError
275+
InvalidCredentialsError
276+
MissingCredentialsError
277+
ExpiredCredentialsError
278+
BadChannelBindingsError
279+
MissingContextError
280+
BadMICError
281+
ExpiredTokenError
282+
DuplicateTokenError
283+
BadMechanismError
264284
"""
265285

266286
cdef gss_channel_bindings_t bdng
@@ -364,7 +384,7 @@ def inquire_context(SecurityContext context not None, initiator_name=True,
364384
and whether or not the context is currently fully established
365385
366386
Raises:
367-
GSSError
387+
MissingContextError
368388
"""
369389

370390
cdef gss_name_t output_init_name
@@ -472,7 +492,8 @@ def context_time(SecurityContext context not None):
472492
int: the number of seconds for which the context will be valid
473493
474494
Raises:
475-
GSSError
495+
ExpiredContextError
496+
MissingContextError
476497
"""
477498

478499
cdef OM_uint32 ttl
@@ -504,7 +525,8 @@ def process_context_token(SecurityContext context not None, token):
504525
token (bytes): the token to process
505526
506527
Raises:
507-
GSSError
528+
InvalidTokenError
529+
MissingContextError
508530
"""
509531

510532
cdef gss_buffer_desc token_buffer = gss_buffer_desc(len(token), token)
@@ -525,6 +547,12 @@ def import_sec_context(token not None):
525547
526548
This method imports a security context established in another process
527549
by reading the specified token which was output by exportSecContext.
550+
551+
Raises:
552+
MissingContextError
553+
InvalidTokenError
554+
OperationUnavailableError
555+
UnauthorizedError
528556
"""
529557

530558
cdef gss_buffer_desc token_buffer = gss_buffer_desc(len(token), token)
@@ -561,7 +589,9 @@ def export_sec_context(SecurityContext context not None):
561589
bytes: the output token to be imported
562590
563591
Raises:
564-
GSSError
592+
ExpiredContextError
593+
MissingContextError
594+
OperationUnavailableError
565595
"""
566596

567597
cdef gss_buffer_desc output_token = gss_buffer_desc(0, NULL)
@@ -599,7 +629,7 @@ def delete_sec_context(SecurityContext context not None, local_only=True):
599629
this is None, but bytes for compatability.
600630
601631
Raises:
602-
GSSError
632+
MissingContextError
603633
"""
604634

605635
cdef OM_uint32 maj_stat, min_stat

0 commit comments

Comments
 (0)