doc/html/_sources/plugindev/gssapi.rst.txt

   1 GSSAPI mechanism interface
   2 ==========================
   3
   4 The GSSAPI library in MIT krb5 can load mechanism modules to augment
   5 the set of built-in mechanisms.
   6
   7 .. note: The GSSAPI loadable mechanism interface does not follow the
   8          normal conventions for MIT krb5 pluggable interfaces.
   9
  10 A mechanism module is a Unix shared object or Windows DLL, built
  11 separately from the krb5 tree.  Modules are loaded according to the
  12 GSS mechanism config files described in :ref:`gssapi_plugin_config`.
  13
  14 For the most part, a GSSAPI mechanism module exports the same
  15 functions as would a GSSAPI implementation itself, with the same
  16 function signatures.  The mechanism selection layer within the GSSAPI
  17 library (called the "mechglue") will dispatch calls from the
  18 application to the module if the module's mechanism is requested.  If
  19 a module does not wish to implement a GSSAPI extension, it can simply
  20 refrain from exporting it, and the mechglue will fail gracefully if
  21 the application calls that function.
  22
  23 The mechglue does not invoke a module's **gss_add_cred**,
  24 **gss_add_cred_from**, **gss_add_cred_impersonate_name**, or
  25 **gss_add_cred_with_password** function.  A mechanism only needs to
  26 implement the "acquire" variants of those functions.
  27
  28 A module does not need to coordinate its minor status codes with those
  29 of other mechanisms.  If the mechglue detects conflicts, it will map
  30 the mechanism's status codes onto unique values, and then map them
  31 back again when **gss_display_status** is called.
  32
  33
  34 NegoEx modules
  35 --------------
  36
  37 Some Windows GSSAPI mechanisms can only be negotiated via a Microsoft
  38 extension to SPNEGO called NegoEx.  Beginning with release 1.18,
  39 mechanism modules can support NegoEx as follows:
  40
  41 * Implement the gssspi_query_meta_data(), gssspi_exchange_meta_data(),
  42   and gssspi_query_mechanism_info() SPIs declared in
  43   ``<gssapi/gssapi_ext.h>``.
  44
  45 * Implement gss_inquire_sec_context_by_oid() and answer the
  46   **GSS_C_INQ_NEGOEX_KEY** and **GSS_C_INQ_NEGOEX_VERIFY_KEY** OIDs
  47   to provide the checksum keys for outgoing and incoming checksums,
  48   respectively.  The answer must be in two buffers: the first buffer
  49   contains the key contents, and the second buffer contains the key
  50   encryption type as a four-byte little-endian integer.
  51
  52 By default, NegoEx mechanisms will not be directly negotiated via
  53 SPNEGO.  If direct SPNEGO negotiation is required for
  54 interoperability, implement gss_inquire_attrs_for_mech() and assert
  55 the GSS_C_MA_NEGOEX_AND_SPNEGO attribute (along with any applicable
  56 RFC 5587 attributes).
  57
  58
  59 Interposer modules
  60 ------------------
  61
  62 The mechglue also supports a kind of loadable module, called an
  63 interposer module, which intercepts calls to existing mechanisms
  64 rather than implementing a new mechanism.
  65
  66 An interposer module must export the symbol **gss_mech_interposer**
  67 with the following signature::
  68
  69     gss_OID_set gss_mech_interposer(gss_OID mech_type);
  70
  71 This function is invoked with the OID of the interposer mechanism as
  72 specified in the mechanism config file, and returns a set of mechanism
  73 OIDs to be interposed.  The returned OID set must have been created
  74 using the mechglue's gss_create_empty_oid_set and
  75 gss_add_oid_set_member functions.
  76
  77 An interposer module must use the prefix ``gssi_`` for the GSSAPI
  78 functions it exports, instead of the prefix ``gss_``.  In most cases,
  79 unexported ``gssi_`` functions will result in failure from their
  80 corresponding ``gss_`` calls.
  81
  82 An interposer module can link against the GSSAPI library in order to
  83 make calls to the original mechanism.  To do so, it must specify a
  84 special mechanism OID which is the concatention of the interposer's
  85 own OID byte string and the original mechanism's OID byte string.
  86
  87 Functions that do not accept a mechanism argument directly require no
  88 special handling, with the following exceptions:
  89
  90 Since **gss_accept_sec_context** does not accept a mechanism argument,
  91 an interposer mechanism must, in order to invoke the original
  92 mechanism's function, acquire a credential for the concatenated OID
  93 and pass that as the *verifier_cred_handle* parameter.
  94
  95 Since **gss_import_name**, **gss_import_cred**, and
  96 **gss_import_sec_context** do not accept mechanism parameters, the SPI
  97 has been extended to include variants which do.  This allows the
  98 interposer module to know which mechanism should be used to interpret
  99 the token.  These functions have the following signatures::
 100
 101     OM_uint32 gssi_import_sec_context_by_mech(OM_uint32 *minor_status,
 102         gss_OID desired_mech, gss_buffer_t interprocess_token,
 103         gss_ctx_id_t *context_handle);
 104
 105     OM_uint32 gssi_import_name_by_mech(OM_uint32 *minor_status,
 106         gss_OID mech_type, gss_buffer_t input_name_buffer,
 107         gss_OID input_name_type, gss_name_t output_name);
 108
 109     OM_uint32 gssi_import_cred_by_mech(OM_uint32 *minor_status,
 110         gss_OID mech_type, gss_buffer_t token,
 111         gss_cred_id_t *cred_handle);
 112
 113 To re-enter the original mechanism when importing tokens for the above
 114 functions, the interposer module must wrap the mechanism token in the
 115 mechglue's format, using the concatenated OID (except in
 116 **gss_import_name**).  The mechglue token formats are:
 117
 118 * For **gss_import_sec_context**, a four-byte OID length in big-endian
 119   order, followed by the concatenated OID, followed by the mechanism
 120   token.
 121
 122 * For **gss_import_name**, the bytes 04 01, followed by a two-byte OID
 123   length in big-endian order, followed by the mechanism OID, followed
 124   by a four-byte token length in big-endian order, followed by the
 125   mechanism token.  Unlike most uses of OIDs in the API, the mechanism
 126   OID encoding must include the DER tag and length for an object
 127   identifier (06 followed by the DER length of the OID byte string),
 128   and this prefix must be included in the two-byte OID length.
 129   input_name_type must also be set to GSS_C_NT_EXPORT_NAME.
 130
 131 * For **gss_import_cred**, a four-byte OID length in big-endian order,
 132   followed by the concatenated OID, followed by a four-byte token
 133   length in big-endian order, followed by the mechanism token.  This
 134   sequence may be repeated multiple times.