Add documentation for cred store common values

docs-requirements.txt

@@ -1,4 +1,3 @@
 Sphinx >= 1.3.1
 sphinx-rtd-theme >= 0.2.5b1
-sphinxcontrib-napoleon >= 0.2.8
 recommonmark >= 0.4.0

docs/source/conf.py

@@ -30,7 +30,7 @@
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.ifconfig', 'sphinx.ext.viewcode', "sphinxcontrib.napoleon", 'gssapi_find_missing', 'requires_rfc']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.ifconfig', 'sphinx.ext.viewcode', "sphinx.ext.napoleon", 'gssapi_find_missing', 'requires_rfc']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

docs/source/credstore.rst

@@ -0,0 +1,75 @@
+Common Values for Credentials Store Extensions
+==============================================
+
+The credentials store extension is an extension introduced by the MIT krb5
+library implementation of GSSAPI. It allows for finer control of creedntials
+from within a GSSAPI application.
+Each mechanism can define keywords to manipulate various aspects of their
+credentials for storage or retrieval operations.
+
+.. note:
+
+   Only mechanisms that implement keywords can use them, some mechanism may
+   share the same or similar keywords, but their meaning is always local to
+   a specific mechanism.
+
+The krb5 mechanism in MIT libraries
+-----------------------------------
+
+The krb5 mechanism as implemented by MIT libraries supports the credentials
+store extension with a number of keywords.
+
+client_keytab
+"""""""""""""
+
+The `client_keytab` keyword can be used in a credential store when it is used
+with the :func:`gssapi.raw.ext_cred_store.acquire_cred_from` /
+:func:`gssapi.raw.ext_cred_store.add_cred_from` functions, to indicate a
+custom location for a keytab containing client keys.
+It is not used in the context of calls used to store credentials.
+The value is a string in the form **type:residual** where **type** can be any
+keytab storage type understood by the implementation and **residual** is the
+keytab identifier (usually something like a path). If the string is just a path
+then the type is defaulted to `FILE`.
+
+keytab
+""""""
+
+The `keytab` keyword can be used in a credential store when it is used with
+the :func:`gssapi.raw.ext_cred_store.acquire_cred_from` /
+:func:`gssapi.raw.ext_cred_store.add_cred_from` functions, to indicate a
+custom location for a keytab containing service keys.
+It is not used in the context of calls used to store credentials.
+The value is a string in the form **type:residual** where **type** can be any
+keytab storage type understood by the implementation and **residual** is the
+keytab identifier (usually something like a path). If the string is just a path
+then the type is defaulted to `FILE`.
+
+ccache
+""""""
+
+The `ccache` keyword can be used to reference a specific credential storage.
+It can be used both to indicate the source of existing credentials for the
+:func:`gssapi.raw.ext_cred_store.acquire_cred_from` /
+:func:`gssapi.raw.ext_cred_store.add_cred_from` functions, as well as the
+destination storage for the :func:`gssapi.raw.ext_cred_store.store_cred_into`
+function.
+The value is a string in the form **type:residual** where type can be any
+credential cache storage type understood by the implementation and
+**residual** is the ccache identifier. If the string is just a path then
+the type is defaulted to `FILE`. Other commonly used types are `DIR`,
+`KEYRING`, `KCM`. Each type has a different format for the **residual**;
+refer to the MIT krb5 documentation for more details.
+
+rcache
+""""""
+
+The `rcache` keyword can be used to reference a custom replay cache storage.
+It is used only with the :func:`gssapi.raw.ext_cred_store.acquire_cred_from` /
+:func:`gssapi.raw.ext_cred_store.add_cred_from` functions for credentials used
+to accept context establishments, not to initiate contexts.
+The value is a string in the form **type:residual** where type can be any
+replay cache storage type understood by the implementation and **residual** is
+the cache identifier (usually something like a path). If the string is just a
+path then the type is defaulted to `FILE`.
+

docs/source/index.rst

@@ -28,6 +28,7 @@ straight into the :doc:`high-level API documentation <gssapi>`.
 
    gssapi.rst
    gssapi.raw.rst
+   otherdoc.rst
    tutorials.rst
 
 

docs/source/otherdoc.rst

@@ -0,0 +1,11 @@
+Other Documentation
+===================
+
+This section contain documentation that is not expressed directly in functions
+documentation, like implementation specific quirks or issues, implementation
+tips, environment influence on operations and similar.
+
+.. toctree::
+   :maxdepth: 1
+
+   credstore.rst

gssapi/raw/ext_cred_store.pyx

@@ -109,7 +109,8 @@ usage='both')
 
     Args:
         store (dict): the credential store information pointing to the
-            credential store from which to acquire the credentials
+            credential store from which to acquire the credentials.
+            See :doc:`credstore` for valid values
         name (Name): the name associated with the credentials,
             or None for the default name
         lifetime (int): the desired lifetime of the credentials, or None
@@ -204,6 +205,7 @@ init_lifetime=None, accept_lifetime=None)
     Args:
         store (dict): the store into which to store the credentials,
             or None for the default store.
+            See :doc:`credstore` for valid values
         name (Name): the name associated with the credentials
         mech (OID): the desired mechanism to be used with these
             credentials
@@ -295,6 +297,7 @@ set_default=False)
     Args:
         store (dict): the store into which to store the credentials,
             or None for the default store.
+            See :doc:`credstore` for valid values
         creds (Creds): the credentials to store
         usage (str): the usage to store the credentials with -- either
             'both', 'initiate', or 'accept'