From 8f43a6f239c31e0e39cd17471d19d761f26869b8 Mon Sep 17 00:00:00 2001 From: Greg Hudson Date: Thu, 25 Oct 2012 11:46:16 -0400 Subject: [PATCH] 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(-) create mode 100644 doc/plugindev/gssapi.rst diff --git a/doc/admins/host_config.rst b/doc/admins/host_config.rst index e5ef06bf1f..755437cf6c 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] -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 0000000000..bb5d6d16fd --- /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 e913810bbf..06d1754baa 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 -- 2.47.3