Low-level Documentation Updates

This commit updates the low-level documentation, introducing method
signatures as well as fixing typos.

Author: DirectXMan12

docs/source/gssapi.raw.rst

@@ -19,6 +19,12 @@ Core RFC 2744
 Names
 ~~~~~
 
+.. note::
+    Some functions in the following section will refer to
+    "mechanism names".  These are not names of mechanisms.
+    Instead, they are a special form of name specific to
+    a given mechanism.
+
 .. automodule:: gssapi.raw.names
     :members:
     :undoc-members:

gssapi/raw/creds.pyx

@@ -82,6 +82,7 @@ cdef class Creds:
 
 def acquire_cred(Name name=None, lifetime=None, mechs=None, usage='both'):
     """
+    acquire_cred(name=None, lifetime=None, mechs=None, usage='both')
     Get GSSAPI credentials for the given name and mechanisms.
 
     This method gets GSSAPI credentials corresponding to the given name
@@ -159,10 +160,15 @@ def acquire_cred(Name name=None, lifetime=None, mechs=None, usage='both'):
 
 def release_cred(Creds creds not None):
     """
+    release_cred(creds)
     Release GSSAPI Credentials.
 
     This method releases GSSAPI credentials.
 
+    Warning:
+        This method is deprecated.  Credentials are
+        automatically freed by Python.
+
     Args:
         creds (Creds): the credentials in question
 
@@ -180,7 +186,10 @@ def release_cred(Creds creds not None):
 def add_cred(Creds input_cred, Name name not None, OID mech not None,
              usage='initiate', init_lifetime=None,
              accept_lifetime=None, mutate_input=False):
-    """Add a credential element to a credential.
+    """
+    add_cred(input_cred, name, mech, usage='initiate', init_lifetime=None, \
+accept_lifetime=None, mutate_input=False)
+    Add a credential element to a credential.
 
     This method can be used to either compose two credentials (i.e., original
     and new credential), or to add a new element to an existing credential.
@@ -264,7 +273,9 @@ def add_cred(Creds input_cred, Name name not None, OID mech not None,
 
 def inquire_cred(Creds creds not None, name=True, lifetime=True, usage=True,
                  mechs=True):
-    """Inspect credentials for information
+    """
+    inquire_cred(creds, name=True, lifetime=True, usage=True, mechs=True)
+    Inspect credentials for information.
 
     This method inspects a :class:`Creds` object for information.
 
@@ -343,10 +354,14 @@ def inquire_cred(Creds creds not None, name=True, lifetime=True, usage=True,
 def inquire_cred_by_mech(Creds creds not None, OID mech not None,
                          name=True, init_lifetime=True,
                          accept_lifetime=True, usage=True):
-    """Inspect credentials for mechanism-specific
+    """
+    inquire_cred_by_mech(creds, mech, name=True, init_lifetime=True, \
+accept_lifetime=True, usage=True)
+    Inspect credentials for mechanism-specific information.
 
     This method inspects a :class:`Creds` object for information
-    specific to a particular mechanism.
+    specific to a particular mechanism.  It functions similarly
+    to :func:`inquire_cred`.
 
     Args:
         creds (Creds): the credentials to inspect

gssapi/raw/ext_cred_imp_exp.pyx

@@ -22,9 +22,11 @@ cdef extern from "python_gssapi_ext.h":
 
 
 def export_cred(Creds creds not None):
-    """Export GSSAPI credentials object
+    """
+    export_cred(creds)
+    Export GSSAPI credentials.
 
-    This method exports a GSSSAPI credentials object into a token
+    This method exports GSSSAPI credentials into a token
     which may be transmitted between different processes.
 
     Args:
@@ -54,7 +56,9 @@ def export_cred(Creds creds not None):
 
 
 def import_cred(token not None):
-    """Import GSSAPI credentials from a token
+    """
+    import_cred(token)
+    Import GSSAPI credentials from a token.
 
     This method imports a credentials object from a token
     previously exported by :func:`export_cred`.

gssapi/raw/ext_cred_store.pyx

@@ -95,7 +95,10 @@ cdef void c_free_key_value_set(gss_key_value_set_desc *kvset):
 
 def acquire_cred_from(dict store=None, Name name=None, lifetime=None,
                       mechs=None, usage='both'):
-    """Acquire credentials from the given store
+    """
+    acquire_cred_from(store=None, name=None, lifetime=None, mechs=None, \
+usage='both')
+    Acquire credentials from the given store.
 
     This method acquires credentials from the store specified by the
     given credential store information.
@@ -183,12 +186,15 @@ def add_cred_from(dict store, Creds input_creds,
                   Name name not None, OID mech not None,
                   usage='both', init_lifetime=None,
                   accept_lifetime=None):
-    """Acquire credentials to add to the current set from the given store
+    """
+    add_cred_from(store, input_creds, name, mech, usage='both', \
+init_lifetime=None, accept_lifetime=None)
+    Acquire credentials to add to the current set from the given store.
 
     This method works like :func:`acquire_cred_from`, except that it
     adds the acquired credentials for a single mechanism to a copy of
     the current set, instead of creating a new set for multiple mechanisms.
-    Unlike :meth:`acquire`, you cannot pass None desired name or
+    Unlike :func:`acquire_cred`, you cannot pass None for the desired name or
     mechanism.
 
     The credential store information is a dictionary containing
@@ -273,7 +279,10 @@ def add_cred_from(dict store, Creds input_creds,
 def store_cred_into(dict store, Creds creds not None,
                     usage='both', OID mech=None, bint overwrite=False,
                     bint set_default=False):
-    """Store credentials to the given store
+    """
+    store_cred_into(store, creds, usage='both', mech=None, overwrite=False, \
+set_default=False)
+    Store credentials into the given store.
 
     This method stores the given credentials into the store specified
     by the given store information.  They may then be retrieved later using

gssapi/raw/ext_dce.pyx

@@ -91,6 +91,7 @@ IOVBuffer = namedtuple('IOVBuffer', ['type', 'allocate', 'value'])
 
 
 cdef class IOV:
+    """A GSSAPI IOV"""
     # defined in ext_dce.pxd
 
     # cdef int iov_len
@@ -304,24 +305,28 @@ cdef class IOV:
 def wrap_iov(SecurityContext context not None, IOV message not None,
              confidential=True, qop=None):
     """
-    Wrap/Encrypt an IOV message
+    wrap_iov(context, message, confidential=True, qop=None)
+    Wrap/Encrypt an IOV message.
 
     This method wraps or encrypts an IOV message.  The allocate
-    parameter of the :class:`IOVBuffer` indicates whether or
-    not that particular buffer should be automatically allocated
-    (for use with padding, header, and trailer buffers).
+    parameter of the :class:`IOVBuffer` objects in the :class:`IOV`
+    indicates whether or not that particular buffer should be
+    automatically allocated (for use with padding, header, and
+    trailer buffers).
+
+    Warning:
+        This modifies the input :class:`IOV`.
 
     Args:
         context (SecurityContext): the current security context
-        message (list): a list of :class:`IOVBuffer` objects
+        message (IOV): an :class:`IOV` containing the message
         confidential (bool): whether or not to encrypt the message (True),
             or just wrap it with a MIC (False)
         qop (int): the desired Quality of Protection
             (or None for the default QoP)
 
     Returns:
-        WrapResult: the wrapped/encrypted message (IOV list), and
-            whether or not encryption was actually used
+        bool: whether or not confidentiality was actually used
 
     Raises:
         GSSError
@@ -348,26 +353,31 @@ def wrap_iov(SecurityContext context not None, IOV message not None,
 
 def unwrap_iov(SecurityContext context not None, IOV message not None):
     """
-    Unwrap/Decrypt an IOV message
+    unwrap_iov(context, message)
+    Unwrap/Decrypt an IOV message.
 
-    This method unwraps or decrypts an IOV message.  The allocate
-    parameter of the :class:`IOVBuffer` indicates whether or
-    not that particular buffer should be automatically allocated
-    (for use with padding, header, and trailer buffers).
+    This method uwraps or decrypts an IOV message.  The allocate
+    parameter of the :class:`IOVBuffer` objects in the :class:`IOV`
+    indicates whether or not that particular buffer should be
+    automatically allocated (for use with padding, header, and
+    trailer buffers).
 
     As a special case, you may pass an entire IOV message
     as a single 'stream'.  In this case, pass a buffer type
     of :attr:`IOVBufferType.stream` followed by a buffer type of
     :attr:`IOVBufferType.data`.  The former should contain the
     entire IOV message, while the latter should be empty.
 
+    Warning:
+        This modifies the input :class:`IOV`.
+
     Args:
         context (SecurityContext): the current security context
-        message (list): a list of :class:`IOVBuffer` objects
+        message (IOV): an :class:`IOV` containing the message
 
     Returns:
-        UnwrapResult: the unwrapped/decrypted message, whether or not
-            encryption was used, and the QoP used
+        IOVUnwrapResult: whether or not confidentiality was used,
+            and the QoP used.
 
     Raises:
         GSSError
@@ -393,7 +403,8 @@ def unwrap_iov(SecurityContext context not None, IOV message not None):
 def wrap_iov_length(SecurityContext context not None, IOV message not None,
                     confidential=True, qop=None):
     """
-    Appropriately size padding, trailer, and header IOV buffers
+    wrap_iov_length(context, message, confidential=True, qop=None)
+    Appropriately size padding, trailer, and header IOV buffers.
 
     This method sets the length values on the IOV buffers.  You
     should already have data provided for the data (and sign-only)
@@ -402,9 +413,12 @@ def wrap_iov_length(SecurityContext context not None, IOV message not None,
     In Python terms, this will result in an appropriately sized
     `bytes` object consisting of all zeros.
 
+    Warning:
+        This modifies the input :class:`IOV`.
+
     Args:
         context (SecurityContext): the current security context
-        message (list): a list of :class:`IOVBuffer` objects
+        message (IOV): an :class:`IOV` containing the message
 
     Returns:
         WrapResult: a list of :class:IOVBuffer` objects, and whether or not
@@ -437,7 +451,8 @@ def wrap_iov_length(SecurityContext context not None, IOV message not None,
 def wrap_aead(SecurityContext context not None, bytes message not None,
               bytes associated=None, confidential=True, qop=None):
     """
-    Wrap/Encrypt an AEAD Message
+    wrap_aead(context, message, associated=None, confidential=True, qop=None)
+    Wrap/Encrypt an AEAD message.
 
     This method takes an input message and associated data,
     and outputs and AEAD message.
@@ -492,7 +507,8 @@ def wrap_aead(SecurityContext context not None, bytes message not None,
 def unwrap_aead(SecurityContext context not None, bytes message not None,
                 bytes associated=None):
     """
-    Unwrap/Decrypt an AEAD Message
+    unwrap_aead(context, message, associated=None)
+    Unwrap/Decrypt an AEAD message.
 
     This method takes an encrpyted/wrapped AEAD message and some associated
     data, and returns an unwrapped/decrypted message.

gssapi/raw/ext_iov_mic.pyx

@@ -34,15 +34,19 @@ IOV.AUTO_ALLOC_BUFFERS.add(IOVBufferType.mic_token)
 def get_mic_iov(SecurityContext context not None, IOV message not None,
                 qop=None):
     """
-    Generate MIC tokens for the given IOV message
+    get_mic_iov(context, message, qop=None)
+    Generate MIC tokens for the given IOV message.
 
     This method generates a MIC token for the given IOV message, and places it
     in the :attr:`IOVBufferType.mic_token` buffer in the IOV.  This method
     operates entirely in-place, and returns nothing.
 
+    Warning:
+        This modifies the input :class:`IOV`.
+
     Args:
         context (SecurityContext): the current security context
-        message (list): a list of :class:`IOVBuffer` objects
+        message (IOV): the :class:`IOV` containing the message
         qop (int): the desired Quality of Protection
             (or None for the default QoP)
 
@@ -70,14 +74,18 @@ def get_mic_iov(SecurityContext context not None, IOV message not None,
 def get_mic_iov_length(SecurityContext context not None, IOV message not None,
                        qop=None):
     """
-    Allocate space for the MIC buffer in the given IOV message
+    get_mic_iov_length(context, message, qop=None)
+    Allocate space for the MIC buffer in the given IOV message.
 
     This method allocates space for the MIC token buffer
     (:attr:`IOVBufferType.mic_token`) in the given IOV message.
 
+    Warning:
+        This modifies the input :class:`IOV`.
+
     Args:
         context (SecurityContext): the current security context
-        message (list): a list of :class:`IOVBuffer` objects
+        message (IOV): the :class:`IOV` containing the message
         qop (int): the desired Quality of Protection
             (or None for the default QoP)
 
@@ -105,15 +113,16 @@ def get_mic_iov_length(SecurityContext context not None, IOV message not None,
 def verify_mic_iov(SecurityContext context not None, IOV message not None,
                    qop=None):
     """
-    Verify that the MIC matches the data in the given IOV message
+    verify_mic_iov(context, message, qop=None)
+    Verify that the MIC matches the data in the given IOV message.
 
     This method verifies that the MIC token in the MIC buffer
     (:attr:`IOVBufferType.mic_token`) match the data buffer(s)
     in the given IOV method.
 
     Args:
         context (SecurityContext): the current security context
-        message (list): a list of :class:`IOVBuffer` objects
+        message (IOV): the :class:`IOV` containing the message
 
     Returns:
         int: the QoP used to generate the MIC token

gssapi/raw/ext_password.pyx

@@ -30,11 +30,15 @@ cdef extern from "python_gssapi_ext.h":
 def acquire_cred_with_password(Name name not None, password not None,
                                lifetime=None, mechs=None, usage="initiate"):
     """
+    acquire_cred_with_password(name, password, lifetime=None, mechs=None, \
+usage="initiate")
     Acquire credentials through provided password.
 
     This function is originally from Solaris and is not documented by either
     MIT or Heimdal.
 
+    In general, it functions similarly to :func:`acquire_cred`.
+
     Args:
         name (Name): the name to acquire credentials for
         password (bytes): the password used to acquire credentialss with

gssapi/raw/ext_password_add.pyx

@@ -37,11 +37,15 @@ def add_cred_with_password(Creds input_cred not None, Name name not None,
                            accept_lifetime=None):
 
     """
+    add_cred_with_password(input_cred, name, mech, password, \
+usage='initiate', init_lifetime=None, accept_lifetime=None)
     Add a credential-element to a credential using provided password.
 
     This function is originally from Solaris and is not documented by either
     MIT or Heimdal.
 
+    In general, it functions similarly to :func:`add_cred`.
+
     Args:
         input_cred (Creds): the credentials to add to
         name (Name): the name to acquire credentials for

gssapi/raw/ext_rfc5588.pyx

@@ -24,7 +24,10 @@ cdef extern from "python_gssapi.h":
 
 def store_cred(Creds creds not None, usage='both', OID mech=None,
                bint overwrite=False, bint set_default=False):
-    """Store credentials to the default store
+    """
+    store_cred(creds, usage='both', mech=None, overwrite=False, \
+set_default=False)
+    Store credentials into the default store.
 
     This method stores the given credentials into the default store.
     They may then be retrieved later using :func:`acquire_cred`.