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

Author: DirectXMan12

gssapi/raw/creds.pyx

@@ -104,7 +104,11 @@ def acquire_cred(Name name=None, lifetime=None, mechs=None, usage='both'):
         indefinite or not supported)
 
     Raises:
-        GSSError
+        BadMechanismError
+        BadNameTypeError
+        BadNameError
+        ExpiredCredentialsError
+        MissingCredentialsError
     """
 
     cdef gss_OID_set desired_mechs
@@ -163,7 +167,7 @@ def release_cred(Creds creds not None):
         creds (Creds): the credentials in question
 
     Raises:
-        GSSError
+        MissingCredentialsError
     """
 
     cdef OM_uint32 maj_stat, min_stat
@@ -202,8 +206,12 @@ def add_cred(Creds input_cred, Name name not None, OID mech not None,
         be set to None if mutate_input is set to True.
 
     Raises:
-        GSSError
-
+        BadMechanismError
+        BadNameTypeError
+        BadNameError
+        DuplicateCredentialsElementError
+        ExpiredCredentialsError
+        MissingCredentialsError
     """
     cdef gss_cred_usage_t c_usage
     if usage == 'initiate':
@@ -272,7 +280,9 @@ def inquire_cred(Creds creds not None, name=True, lifetime=True, usage=True,
             with unused fields set to None
 
     Raises:
-        GSSError
+        MissingCredentialsError
+        InvalidCredentialsError
+        ExpiredCredentialsError
     """
 
     # TODO(directxman12): add docs
@@ -351,7 +361,8 @@ def inquire_cred_by_mech(Creds creds not None, OID mech not None,
             with unused fields set to None
 
     Raises:
-        GSSError
+        MissingCredentialsError
+        InvalidCredentialsError
     """
 
     # TODO(directxman12): add docs

gssapi/raw/ext_rfc5588.pyx

@@ -44,6 +44,10 @@ def store_cred(Creds creds not None, usage='both', OID mech=None,
 
     Raises:
         GSSError
+        ExpiredCredentialsError
+        MissingCredentialsError
+        OperationUnavailableError
+        DuplicateCredentialsElementError
     """
     cdef gss_OID desired_mech
     if mech is not None:

gssapi/raw/message.pyx

@@ -62,7 +62,9 @@ def get_mic(SecurityContext context not None, message, qop=None):
         bytes: the generated MIC token
 
     Raises:
-        GSSError
+        ExpiredContextError
+        MissingContextError
+        BadQoPError
     """
 
     cdef gss_buffer_desc message_buffer = gss_buffer_desc(len(message),
@@ -104,7 +106,14 @@ def verify_mic(SecurityContext context not None, message, token):
         int: the QoP used.
 
     Raises:
-        GSSError
+        InvalidTokenError
+        BadMICError
+        DuplicateTokenError
+        ExpiredTokenError
+        TokenTooLateError
+        TokenTooEarlyError
+        ExpiredContextError
+        MissingContextError
     """
 
     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,
         int: the maximum unencrypted/unwrapped message size
 
     Raises:
-        GSSError
+        MissingContextError
+        ExpiredContextError
+        BadQoPError
     """
 
     cdef int conf_req = confidential
@@ -185,7 +196,9 @@ def wrap(SecurityContext context not None, message, confidential=True,
             encryption was actually used
 
     Raises:
-        GSSError
+        ExpiredContextError
+        MissingContextError
+        BadQoPError
     """
 
     cdef int conf_req = confidential
@@ -227,7 +240,14 @@ def unwrap(SecurityContext context not None, message):
             encryption was used, and the QoP used
 
     Raises:
-        GSSError
+        InvalidTokenError
+        BadMICError
+        DuplicateTokenError
+        ExpiredTokenError
+        TokenTooLateError
+        TokenTooEarlyError
+        ExpiredContextError
+        MissingContextError
     """
 
     cdef gss_buffer_desc input_buffer = gss_buffer_desc(len(message), message)

gssapi/raw/names.pyx

@@ -80,7 +80,9 @@ def import_name(name not None, OID name_type=None):
         Name: the GSSAPI version of the name
 
     Raises:
-        GSSError
+        BadNameTypeError
+        BadNameError
+        BadMechanismError
     """
 
     cdef gss_OID nt
@@ -126,7 +128,7 @@ def display_name(Name name not None, name_type=True):
         DisplayNameResult: the text part of the name and its type
 
     Raises:
-        GSSError
+        BadNameError
     """
 
     # GSS_C_EMPTY_BUFFER
@@ -178,7 +180,8 @@ def compare_name(Name name1=None, Name name2=None):
         bool: whether or not the names are equal
 
     Raises:
-        GSSError
+        BadNameTypeError
+        BadNameError
     """
 
     # check for either value being None
@@ -221,7 +224,9 @@ def export_name(Name name not None):
         bytes: the exported name
 
     Raises:
-        GSSError
+        MechanismNameRequiredError
+        BadNameTypeError
+        BadNameError
     """
 
     # GSS_C_EMPTY_BUFFER
@@ -258,7 +263,9 @@ def canonicalize_name(Name name not None, OID mech not None):
         Name: a canonicalized version of the input name
 
     Raises:
-        GSSError
+        BadMechanismError
+        BadNameTypeError
+        BadNameError
     """
 
     cdef gss_name_t canonicalized_name
@@ -289,7 +296,7 @@ def duplicate_name(Name name not None):
         Name: a duplicate of the input name
 
     Raises:
-        GSSError
+        BadNameError
     """
 
     cdef gss_name_t new_name
@@ -314,7 +321,7 @@ def release_name(Name name not None):
         name (Name): the name in question
 
     Raises:
-        GSSError
+        BadNameError
     """
 
     cdef OM_uint32 maj_stat, min_stat

gssapi/raw/sec_contexts.pyx

@@ -152,7 +152,18 @@ def init_sec_context(Name target_name not None, Creds creds=None,
         initiation.
 
     Raises:
-        GSSError
+        InvalidTokenError
+        InvalidCredentialsError
+        MissingCredentialsError
+        ExpiredCredentialsError
+        BadChannelBindingsError
+        BadMICError
+        ExpiredTokenError
+        DuplicateTokenError
+        MissingContextError
+        BadNameTypeError
+        BadNameError
+        BadMechanismError
     """
 
     cdef gss_OID mech_oid
@@ -260,7 +271,16 @@ def accept_sec_context(input_token not None, Creds acceptor_creds=None,
             exchanges are needed to finalize the security context.
 
     Raises:
-        GSSError
+        InvalidTokenError
+        InvalidCredentialsError
+        MissingCredentialsError
+        ExpiredCredentialsError
+        BadChannelBindingsError
+        MissingContextError
+        BadMICError
+        ExpiredTokenError
+        DuplicateTokenError
+        BadMechanismError
     """
 
     cdef gss_channel_bindings_t bdng
@@ -364,7 +384,7 @@ def inquire_context(SecurityContext context not None, initiator_name=True,
             and whether or not the context is currently fully established
 
     Raises:
-        GSSError
+        MissingContextError
     """
 
     cdef gss_name_t output_init_name
@@ -472,7 +492,8 @@ def context_time(SecurityContext context not None):
         int: the number of seconds for which the context will be valid
 
     Raises:
-        GSSError
+        ExpiredContextError
+        MissingContextError
     """
 
     cdef OM_uint32 ttl
@@ -504,7 +525,8 @@ def process_context_token(SecurityContext context not None, token):
         token (bytes): the token to process
 
     Raises:
-        GSSError
+        InvalidTokenError
+        MissingContextError
     """
 
     cdef gss_buffer_desc token_buffer = gss_buffer_desc(len(token), token)
@@ -525,6 +547,12 @@ def import_sec_context(token not None):
 
     This method imports a security context established in another process
     by reading the specified token which was output by exportSecContext.
+
+    Raises:
+        MissingContextError
+        InvalidTokenError
+        OperationUnavailableError
+        UnauthorizedError
     """
 
     cdef gss_buffer_desc token_buffer = gss_buffer_desc(len(token), token)
@@ -561,7 +589,9 @@ def export_sec_context(SecurityContext context not None):
         bytes: the output token to be imported
 
     Raises:
-        GSSError
+        ExpiredContextError
+        MissingContextError
+        OperationUnavailableError
     """
 
     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):
             this is None, but bytes for compatability.
 
     Raises:
-        GSSError
+        MissingContextError
     """
 
     cdef OM_uint32 maj_stat, min_stat