krb5 commit: Document GSSAPI loadable module interface
Greg Hudson
ghudson at MIT.EDU
Thu Oct 25 12:00:06 EDT 2012
https://github.com/krb5/krb5/commit/8f43a6f239c31e0e39cd17471d19d761f26869b8
commit 8f43a6f239c31e0e39cd17471d19d761f26869b8
Author: Greg Hudson <ghudson at mit.edu>
Date: Thu Oct 25 11:46:16 2012 -0400
Document GSSAPI loadable module interface
ticket: 7429 (new)
target_version: 1.11
tags: pullup
doc/admins/host_config.rst | 15 ++++--
doc/plugindev/gssapi.rst | 101 ++++++++++++++++++++++++++++++++++++++++++++
doc/plugindev/index.rst | 1 +
3 files changed, 112 insertions(+), 5 deletions(-)
diff --git a/doc/admins/host_config.rst b/doc/admins/host_config.rst
index e5ef06b..755437c 100644
--- a/doc/admins/host_config.rst
+++ b/doc/admins/host_config.rst
@@ -80,18 +80,23 @@ locator plugin would be registered by placing its shared object in
|libdir|\ ``/krb5/plugins/libkrb5/winbind_krb5_locator.so``.
+.. _gssapi_plugin_config:
+
GSSAPI mechanism modules
~~~~~~~~~~~~~~~~~~~~~~~~
GSSAPI mechanism module are registered using the file
``/etc/gss/mech``. Each line in this file has the form::
- oid pathname [options]
+ oid pathname [options] <type>
-where *oid* is the object identifier of the GSSAPI mechanism to be
-registered, *pathname* is a path to the module shared object or DLL,
-and *options* (if present) are options provided to the plugin module,
-surrounded in square brackets.
+Only the oid and pathname are required. *oid* is the object
+identifier of the GSSAPI mechanism to be registered. *pathname* is a
+path to the module shared object or DLL. *options* (if present) are
+options provided to the plugin module, surrounded in square brackets.
+*type* (if present) can be used to indicate a special type of module.
+Currently the only special module type is "interposer", for a module
+designed to intercept calls to other mechanisms.
.. _profile_plugin_config:
diff --git a/doc/plugindev/gssapi.rst b/doc/plugindev/gssapi.rst
new file mode 100644
index 0000000..bb5d6d1
--- /dev/null
+++ b/doc/plugindev/gssapi.rst
@@ -0,0 +1,101 @@
+GSSAPI mechanism interface
+==========================
+
+The GSSAPI library in MIT krb5 can load mechanism modules to augment
+the set of built-in mechanisms.
+
+.. note: The GSSAPI loadable mechanism interface does not follow the
+ normal conventions for MIT krb5 pluggable interfaces.
+
+A mechanism module is a Unix shared object or Windows DLL, built
+separately from the krb5 tree. Modules are loaded according to the
+``/etc/gss/mech`` config file, as described in
+:ref:`gssapi_plugin_config`.
+
+For the most part, a GSSAPI mechanism module exports the same
+functions as would a GSSAPI implementation itself, with the same
+function signatures. The mechanism selection layer within the GSSAPI
+library (called the "mechglue") will dispatch calls from the
+application to the module if the module's mechanism is requested. If
+a module does not wish to implement a GSSAPI extension, it can simply
+refrain from exporting it, and the mechglue will fail gracefully if
+the application calls that function.
+
+The mechglue does not invoke a module's **gss_add_cred**,
+**gss_add_cred_from**, **gss_add_cred_impersonate_name**, or
+**gss_add_cred_with_password** function. A mechanism only needs to
+implement the "acquire" variants of those functions.
+
+A module does not need to coordinate its minor status codes with those
+of other mechanisms. If the mechglue detects conflicts, it will map
+the mechanism's status codes onto unique values, and then map them
+back again when **gss_display_status** is called.
+
+
+Interposer modules
+------------------
+
+The mechglue also supports a kind of loadable module, called an
+interposer module, which intercepts calls to existing mechanisms
+rather than implementing a new mechanism.
+
+An interposer module must export the symbol **gss_mech_interposer**
+with the following signature::
+
+ gss_OID_set gss_mech_interposer(gss_OID mech_type);
+
+This function is invoked with the OID of the interposer mechanism as
+specified in ``/etc/gss/mech``, and returns a set of mechanism OIDs to
+be interposed. The returned OID set must have been created using the
+mechglue's gss_create_empty_oid_set and gss_add_oid_set_member
+functions.
+
+An interposer module must use the prefix ``gssi_`` for the GSSAPI
+functions it exports, instead of the prefix ``gss_``.
+
+An interposer module can link against the GSSAPI library in order to
+make calls to the original mechanism. To do so, it must specify a
+special mechanism OID which is the concatention of the interposer's
+own OID byte string and the original mechanism's OID byte string.
+
+Since **gss_accept_sec_context** does not accept a mechanism argument,
+an interposer mechanism must, in order to invoke the original
+mechanism's function, acquire a credential for the concatenated OID
+and pass that as the *verifier_cred_handle* parameter.
+
+Since **gss_import_name**, **gss_import_cred**, and
+**gss_import_sec_context** do not accept mechanism parameters, the SPI
+has been extended to include variants which do. This allows the
+interposer module to know which mechanism should be used to interpret
+the token. These functions have the following signatures::
+
+ OM_uint32 gssi_import_sec_context_by_mech(OM_uint32 *minor_status,
+ gss_OID desired_mech, gss_buffer_t interprocess_token,
+ gss_ctx_id_t *context_handle);
+
+ OM_uint32 gssi_import_name_by_mech(OM_uint32 *minor_status,
+ gss_OID mech_type, gss_buffer_t input_name_buffer,
+ gss_OID input_name_type, gss_name_t output_name);
+
+ OM_uint32 gssi_import_cred_by_mech(OM_uint32 *minor_status,
+ gss_OID mech_type, gss_buffer_t token,
+ gss_cred_id_t *cred_handle);
+
+To re-enter the original mechanism when importing tokens for the above
+functions, the interposer module must wrap the mechanism token in the
+mechglue's format, using the concatenated OID. The mechglue token
+formats are:
+
+* For **gss_import_sec_context**, a four-byte OID length in big-endian
+ order, followed by the mechanism OID, followed by the mechanism
+ token.
+
+* For **gss_import_name**, the bytes 04 01, followed by a two-byte OID
+ length in big-endian order, followed by the mechanism OID, followed
+ by the bytes 06, followed by the OID length as a single byte,
+ followed by the mechanism OID, followed by the mechanism token.
+
+* For **gss_import_cred**, a four-byte OID length in big-endian order,
+ followed by the mechanism OID, followed by a four-byte token length
+ in big-endian order, followed by the mechanism token. This sequence
+ may be repeated multiple times.
diff --git a/doc/plugindev/index.rst b/doc/plugindev/index.rst
index e913810..06d1754 100644
--- a/doc/plugindev/index.rst
+++ b/doc/plugindev/index.rst
@@ -27,6 +27,7 @@ Contents
kadm5_hook.rst
locate.rst
profile.rst
+ gssapi.rst
internal.rst
.. TODO: GSSAPI mechanism plugins
More information about the cvs-krb5
mailing list