diff --git a/docs-requirements.txt b/docs-requirements.txt index c0eb0c23..0e60f68f 100644 --- a/docs-requirements.txt +++ b/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 diff --git a/docs/source/conf.py b/docs/source/conf.py index c2373ea2..5f2cf231 100644 --- a/docs/source/conf.py +++ b/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'] diff --git a/docs/source/credstore.rst b/docs/source/credstore.rst new file mode 100644 index 00000000..4c5b31b7 --- /dev/null +++ b/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`. + diff --git a/docs/source/index.rst b/docs/source/index.rst index 8a2f3bce..1cf289bb 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -28,6 +28,7 @@ straight into the :doc:`high-level API documentation `. gssapi.rst gssapi.raw.rst + otherdoc.rst tutorials.rst diff --git a/docs/source/otherdoc.rst b/docs/source/otherdoc.rst new file mode 100644 index 00000000..7e8e6f30 --- /dev/null +++ b/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 diff --git a/gssapi/raw/ext_cred_store.pyx b/gssapi/raw/ext_cred_store.pyx index be26a142..9ee57c36 100644 --- a/gssapi/raw/ext_cred_store.pyx +++ b/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'