High-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 high-level API.

Closes #11

Author: DirectXMan12

gssapi/creds.py

@@ -42,6 +42,13 @@ def __new__(cls, base=None, token=None, name=None, lifetime=None,
 
         Otherwise, the credentials are acquired as per the
         :meth:`acquire` method.
+
+        Raises:
+            BadMechanismError
+            BadNameTypeError
+            BadNameError
+            ExpiredCredentialsError
+            MissingCredentialsError
         """
 
         # TODO(directxman12): this is missing support for password
@@ -119,6 +126,13 @@ def acquire(cls, name=None, lifetime=None, mechs=None, usage='both',
         Returns:
             AcquireCredResult: the acquired credentials and information about
                 them
+
+        Raises:
+            BadMechanismError
+            BadNameTypeError
+            BadNameError
+            ExpiredCredentialsError
+            MissingCredentialsError
         """
 
         if store is None:
@@ -161,6 +175,13 @@ def store(self, store=None, usage='both', mech=None,
 
         Returns:
             StoreCredResult: the results of the credential storing operation
+
+        Raises:
+            GSSError
+            ExpiredCredentialsError
+            MissingCredentialsError
+            OperationUnavailableError
+            DuplicateCredentialsElementError
         """
 
         if store is None:
@@ -227,6 +248,11 @@ def inquire(self, name=True, lifetime=True, usage=True, mechs=True):
         Returns:
             InquireCredResult: the information about the credentials,
                 with None used when the corresponding argument was False
+
+        Raises:
+            MissingCredentialsError
+            InvalidCredentialsError
+            ExpiredCredentialsError
         """
 
         res = rcreds.inquire_cred(self, name, lifetime, usage, mechs)
@@ -319,6 +345,14 @@ def add(self, name, mech, usage='both',
         Returns:
             Credentials: the credentials set containing the current credentials
                 and the newly acquired ones.
+
+        Raises:
+            BadMechanismError
+            BadNameTypeError
+            BadNameError
+            DuplicateCredentialsElementError
+            ExpiredCredentialsError
+            MissingCredentialsError
         """
 
         if store is not None and impersonator is not None:

gssapi/names.py

@@ -36,6 +36,11 @@ def __new__(cls, base=None, name_type=None, token=None):
 
         Otherwise, a new name will be created, using the `base` argument as
         the string and the `name_type` argument to denote the name type.
+
+        Raises:
+            BadNameTypeError
+            BadNameError
+            BadMechanismError
         """
 
         if token is not None:
@@ -95,6 +100,11 @@ def export(self):
 
         Returns:
             bytes: the exported name in token form
+
+        Raises:
+            MechanismNameRequiredError
+            BadNameTypeError
+            BadNameError
         """
 
         return rname.export_name(self)
@@ -110,6 +120,11 @@ def canonicalize(self, mech):
 
         Returns:
             Name: the canonicalized name
+
+        Raises:
+            BadMechanismError
+            BadNameTypeError
+            BadNameError
         """
 
         return type(self)(rname.canonicalize_name(self, mech))

gssapi/sec_contexts.py

@@ -134,6 +134,11 @@ def get_signature(self, message):
 
         Returns:
             bytes: the message signature
+
+        Raises:
+            ExpiredContextError
+            MissingContextError
+            BadQoPError
         """
 
         # TODO(directxman12): check flags?
@@ -154,6 +159,16 @@ def verify_signature(self, message, mic):
 
         Raises:
             BadMICError: the signature was not valid
+
+        Raises:
+            InvalidTokenError
+            BadMICError
+            DuplicateTokenError
+            ExpiredTokenError
+            TokenTooLateError
+            TokenTooEarlyError
+            ExpiredContextError
+            MissingContextError
         """
 
         return rmessage.verify_mic(self, message, mic)
@@ -171,6 +186,11 @@ def wrap(self, message, encrypt):
         Returns:
             WrapResult: the wrapped message and details about it
                 (e.g. whether encryption was used succesfully)
+
+        Raises:
+            ExpiredContextError
+            MissingContextError
+            BadQoPError
         """
 
         return rmessage.wrap(self, message, encrypt)
@@ -187,6 +207,16 @@ def unwrap(self, message):
         Returns:
             UnwrapResult: the unwrapped message and details about it
                 (e.g. wheter encryption was used)
+
+        Raises:
+            InvalidTokenError
+            BadMICError
+            DuplicateTokenError
+            ExpiredTokenError
+            TokenTooLateError
+            TokenTooEarlyError
+            ExpiredContextError
+            MissingContextError
         """
 
         return rmessage.unwrap(self, message)
@@ -208,6 +238,9 @@ def encrypt(self, message):
 
         Raises:
             EncryptionNotUsed: the encryption could not be used
+            ExpiredContextError
+            MissingContextError
+            BadQoPError
         """
 
         res = self.wrap(message, encrypt=True)
@@ -233,6 +266,14 @@ def decrypt(self, message):
 
         Raises:
             EncryptionNotUsed: encryption was expected, but not used
+            InvalidTokenError
+            BadMICError
+            DuplicateTokenError
+            ExpiredTokenError
+            TokenTooLateError
+            TokenTooEarlyError
+            ExpiredContextError
+            MissingContextError
         """
 
         res = self.unwrap(message)
@@ -260,6 +301,11 @@ def get_wrap_size_limit(self, desired_output_size,
 
         Returns:
             int: the maximum input message size
+
+        Raises:
+            MissingContextError
+            ExpiredContextError
+            BadQoPError
         """
 
         return rmessage.wrap_size_limit(self, desired_output_size,
@@ -273,6 +319,10 @@ def process_token(self, token):
 
         Args:
             token (bytes): the token to process
+
+        Raises:
+            InvalidTokenError
+            MissingContextError
         """
 
         rsec_contexts.process_context_token(self, token)
@@ -285,6 +335,11 @@ def export(self):
 
         Returns:
             bytes: the exported security context
+
+        Raises:
+            ExpiredContextError
+            MissingContextError
+            OperationUnavailableError
         """
 
         return rsec_contexts.export_sec_context(self)
@@ -315,6 +370,9 @@ def _inquire(self, **kwargs):
         Returns:
             InquireContextResult: the results of the inquiry, with unused
                 fields set to None
+
+        Raises:
+            MissingContextError
         """
         if not kwargs:
             default_val = True
@@ -395,6 +453,20 @@ def step(self, token=None):
 
         Returns:
             bytes: the output token to send to the other participant
+
+        Raises:
+            InvalidTokenError
+            InvalidCredentialsError
+            MissingCredentialsError
+            ExpiredCredentialsError
+            BadChannelBindingsError
+            BadMICError
+            ExpiredTokenError: (initiate only)
+            DuplicateTokenError
+            MissingContextError
+            BadNameTypeError: (initiate only)
+            BadNameError: (initiate only)
+            BadMechanismError
         """
 
         if self.usage == 'accept':