1 2<!DOCTYPE html> 3 4<html> 5 <head> 6 <meta charset="utf-8" /> 7 <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> 8 9 <title>GSSAPI mechanism interface — MIT Kerberos Documentation</title> 10 <link rel="stylesheet" type="text/css" href="../_static/pygments.css" /> 11 <link rel="stylesheet" type="text/css" href="../_static/agogo.css" /> 12 <link rel="stylesheet" type="text/css" href="../_static/kerb.css" /> 13 <script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script> 14 <script src="../_static/jquery.js"></script> 15 <script src="../_static/underscore.js"></script> 16 <script src="../_static/doctools.js"></script> 17 <link rel="author" title="About these documents" href="../about.html" /> 18 <link rel="index" title="Index" href="../genindex.html" /> 19 <link rel="search" title="Search" href="../search.html" /> 20 <link rel="copyright" title="Copyright" href="../copyright.html" /> 21 <link rel="next" title="Internal pluggable interfaces" href="internal.html" /> 22 <link rel="prev" title="Configuration interface (profile)" href="profile.html" /> 23 </head><body> 24 <div class="header-wrapper"> 25 <div class="header"> 26 27 28 <h1><a href="../index.html">MIT Kerberos Documentation</a></h1> 29 30 <div class="rel"> 31 32 <a href="../index.html" title="Full Table of Contents" 33 accesskey="C">Contents</a> | 34 <a href="profile.html" title="Configuration interface (profile)" 35 accesskey="P">previous</a> | 36 <a href="internal.html" title="Internal pluggable interfaces" 37 accesskey="N">next</a> | 38 <a href="../genindex.html" title="General Index" 39 accesskey="I">index</a> | 40 <a href="../search.html" title="Enter search criteria" 41 accesskey="S">Search</a> | 42 <a href="mailto:krb5-bugs@mit.edu?subject=Documentation__GSSAPI mechanism interface">feedback</a> 43 </div> 44 </div> 45 </div> 46 47 <div class="content-wrapper"> 48 <div class="content"> 49 <div class="document"> 50 51 <div class="documentwrapper"> 52 <div class="bodywrapper"> 53 <div class="body" role="main"> 54 55 <section id="gssapi-mechanism-interface"> 56<h1>GSSAPI mechanism interface<a class="headerlink" href="#gssapi-mechanism-interface" title="Permalink to this headline">¶</a></h1> 57<p>The GSSAPI library in MIT krb5 can load mechanism modules to augment 58the set of built-in mechanisms.</p> 59<p>A mechanism module is a Unix shared object or Windows DLL, built 60separately from the krb5 tree. Modules are loaded according to the 61GSS mechanism config files described in <a class="reference internal" href="../admin/host_config.html#gssapi-plugin-config"><span class="std std-ref">GSSAPI mechanism modules</span></a>.</p> 62<p>For the most part, a GSSAPI mechanism module exports the same 63functions as would a GSSAPI implementation itself, with the same 64function signatures. The mechanism selection layer within the GSSAPI 65library (called the “mechglue”) will dispatch calls from the 66application to the module if the module’s mechanism is requested. If 67a module does not wish to implement a GSSAPI extension, it can simply 68refrain from exporting it, and the mechglue will fail gracefully if 69the application calls that function.</p> 70<p>The mechglue does not invoke a module’s <strong>gss_add_cred</strong>, 71<strong>gss_add_cred_from</strong>, <strong>gss_add_cred_impersonate_name</strong>, or 72<strong>gss_add_cred_with_password</strong> function. A mechanism only needs to 73implement the “acquire” variants of those functions.</p> 74<p>A module does not need to coordinate its minor status codes with those 75of other mechanisms. If the mechglue detects conflicts, it will map 76the mechanism’s status codes onto unique values, and then map them 77back again when <strong>gss_display_status</strong> is called.</p> 78<section id="negoex-modules"> 79<h2>NegoEx modules<a class="headerlink" href="#negoex-modules" title="Permalink to this headline">¶</a></h2> 80<p>Some Windows GSSAPI mechanisms can only be negotiated via a Microsoft 81extension to SPNEGO called NegoEx. Beginning with release 1.18, 82mechanism modules can support NegoEx as follows:</p> 83<ul class="simple"> 84<li><p>Implement the gssspi_query_meta_data(), gssspi_exchange_meta_data(), 85and gssspi_query_mechanism_info() SPIs declared in 86<code class="docutils literal notranslate"><span class="pre"><gssapi/gssapi_ext.h></span></code>.</p></li> 87<li><p>Implement gss_inquire_sec_context_by_oid() and answer the 88<strong>GSS_C_INQ_NEGOEX_KEY</strong> and <strong>GSS_C_INQ_NEGOEX_VERIFY_KEY</strong> OIDs 89to provide the checksum keys for outgoing and incoming checksums, 90respectively. The answer must be in two buffers: the first buffer 91contains the key contents, and the second buffer contains the key 92encryption type as a four-byte little-endian integer.</p></li> 93</ul> 94<p>By default, NegoEx mechanisms will not be directly negotiated via 95SPNEGO. If direct SPNEGO negotiation is required for 96interoperability, implement gss_inquire_attrs_for_mech() and assert 97the GSS_C_MA_NEGOEX_AND_SPNEGO attribute (along with any applicable 98RFC 5587 attributes).</p> 99</section> 100<section id="interposer-modules"> 101<h2>Interposer modules<a class="headerlink" href="#interposer-modules" title="Permalink to this headline">¶</a></h2> 102<p>The mechglue also supports a kind of loadable module, called an 103interposer module, which intercepts calls to existing mechanisms 104rather than implementing a new mechanism.</p> 105<p>An interposer module must export the symbol <strong>gss_mech_interposer</strong> 106with the following signature:</p> 107<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">gss_OID_set</span> <span class="n">gss_mech_interposer</span><span class="p">(</span><span class="n">gss_OID</span> <span class="n">mech_type</span><span class="p">);</span> 108</pre></div> 109</div> 110<p>This function is invoked with the OID of the interposer mechanism as 111specified in the mechanism config file, and returns a set of mechanism 112OIDs to be interposed. The returned OID set must have been created 113using the mechglue’s gss_create_empty_oid_set and 114gss_add_oid_set_member functions.</p> 115<p>An interposer module must use the prefix <code class="docutils literal notranslate"><span class="pre">gssi_</span></code> for the GSSAPI 116functions it exports, instead of the prefix <code class="docutils literal notranslate"><span class="pre">gss_</span></code>. In most cases, 117unexported <code class="docutils literal notranslate"><span class="pre">gssi_</span></code> functions will result in failure from their 118corresponding <code class="docutils literal notranslate"><span class="pre">gss_</span></code> calls.</p> 119<p>An interposer module can link against the GSSAPI library in order to 120make calls to the original mechanism. To do so, it must specify a 121special mechanism OID which is the concatention of the interposer’s 122own OID byte string and the original mechanism’s OID byte string.</p> 123<p>Functions that do not accept a mechanism argument directly require no 124special handling, with the following exceptions:</p> 125<p>Since <strong>gss_accept_sec_context</strong> does not accept a mechanism argument, 126an interposer mechanism must, in order to invoke the original 127mechanism’s function, acquire a credential for the concatenated OID 128and pass that as the <em>verifier_cred_handle</em> parameter.</p> 129<p>Since <strong>gss_import_name</strong>, <strong>gss_import_cred</strong>, and 130<strong>gss_import_sec_context</strong> do not accept mechanism parameters, the SPI 131has been extended to include variants which do. This allows the 132interposer module to know which mechanism should be used to interpret 133the token. These functions have the following signatures:</p> 134<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">OM_uint32</span> <span class="n">gssi_import_sec_context_by_mech</span><span class="p">(</span><span class="n">OM_uint32</span> <span class="o">*</span><span class="n">minor_status</span><span class="p">,</span> 135 <span class="n">gss_OID</span> <span class="n">desired_mech</span><span class="p">,</span> <span class="n">gss_buffer_t</span> <span class="n">interprocess_token</span><span class="p">,</span> 136 <span class="n">gss_ctx_id_t</span> <span class="o">*</span><span class="n">context_handle</span><span class="p">);</span> 137 138<span class="n">OM_uint32</span> <span class="n">gssi_import_name_by_mech</span><span class="p">(</span><span class="n">OM_uint32</span> <span class="o">*</span><span class="n">minor_status</span><span class="p">,</span> 139 <span class="n">gss_OID</span> <span class="n">mech_type</span><span class="p">,</span> <span class="n">gss_buffer_t</span> <span class="n">input_name_buffer</span><span class="p">,</span> 140 <span class="n">gss_OID</span> <span class="n">input_name_type</span><span class="p">,</span> <span class="n">gss_name_t</span> <span class="n">output_name</span><span class="p">);</span> 141 142<span class="n">OM_uint32</span> <span class="n">gssi_import_cred_by_mech</span><span class="p">(</span><span class="n">OM_uint32</span> <span class="o">*</span><span class="n">minor_status</span><span class="p">,</span> 143 <span class="n">gss_OID</span> <span class="n">mech_type</span><span class="p">,</span> <span class="n">gss_buffer_t</span> <span class="n">token</span><span class="p">,</span> 144 <span class="n">gss_cred_id_t</span> <span class="o">*</span><span class="n">cred_handle</span><span class="p">);</span> 145</pre></div> 146</div> 147<p>To re-enter the original mechanism when importing tokens for the above 148functions, the interposer module must wrap the mechanism token in the 149mechglue’s format, using the concatenated OID (except in 150<strong>gss_import_name</strong>). The mechglue token formats are:</p> 151<ul class="simple"> 152<li><p>For <strong>gss_import_sec_context</strong>, a four-byte OID length in big-endian 153order, followed by the concatenated OID, followed by the mechanism 154token.</p></li> 155<li><p>For <strong>gss_import_name</strong>, the bytes 04 01, followed by a two-byte OID 156length in big-endian order, followed by the mechanism OID, followed 157by a four-byte token length in big-endian order, followed by the 158mechanism token. Unlike most uses of OIDs in the API, the mechanism 159OID encoding must include the DER tag and length for an object 160identifier (06 followed by the DER length of the OID byte string), 161and this prefix must be included in the two-byte OID length. 162input_name_type must also be set to GSS_C_NT_EXPORT_NAME.</p></li> 163<li><p>For <strong>gss_import_cred</strong>, a four-byte OID length in big-endian order, 164followed by the concatenated OID, followed by a four-byte token 165length in big-endian order, followed by the mechanism token. This 166sequence may be repeated multiple times.</p></li> 167</ul> 168</section> 169</section> 170 171 172 <div class="clearer"></div> 173 </div> 174 </div> 175 </div> 176 </div> 177 <div class="sidebar"> 178 179 <h2>On this page</h2> 180 <ul> 181<li><a class="reference internal" href="#">GSSAPI mechanism interface</a><ul> 182<li><a class="reference internal" href="#negoex-modules">NegoEx modules</a></li> 183<li><a class="reference internal" href="#interposer-modules">Interposer modules</a></li> 184</ul> 185</li> 186</ul> 187 188 <br/> 189 <h2>Table of contents</h2> 190 <ul class="current"> 191<li class="toctree-l1"><a class="reference internal" href="../user/index.html">For users</a></li> 192<li class="toctree-l1"><a class="reference internal" href="../admin/index.html">For administrators</a></li> 193<li class="toctree-l1"><a class="reference internal" href="../appdev/index.html">For application developers</a></li> 194<li class="toctree-l1 current"><a class="reference internal" href="index.html">For plugin module developers</a><ul class="current"> 195<li class="toctree-l2"><a class="reference internal" href="general.html">General plugin concepts</a></li> 196<li class="toctree-l2"><a class="reference internal" href="clpreauth.html">Client preauthentication interface (clpreauth)</a></li> 197<li class="toctree-l2"><a class="reference internal" href="kdcpreauth.html">KDC preauthentication interface (kdcpreauth)</a></li> 198<li class="toctree-l2"><a class="reference internal" href="ccselect.html">Credential cache selection interface (ccselect)</a></li> 199<li class="toctree-l2"><a class="reference internal" href="pwqual.html">Password quality interface (pwqual)</a></li> 200<li class="toctree-l2"><a class="reference internal" href="kadm5_hook.html">KADM5 hook interface (kadm5_hook)</a></li> 201<li class="toctree-l2"><a class="reference internal" href="kadm5_auth.html">kadmin authorization interface (kadm5_auth)</a></li> 202<li class="toctree-l2"><a class="reference internal" href="hostrealm.html">Host-to-realm interface (hostrealm)</a></li> 203<li class="toctree-l2"><a class="reference internal" href="localauth.html">Local authorization interface (localauth)</a></li> 204<li class="toctree-l2"><a class="reference internal" href="locate.html">Server location interface (locate)</a></li> 205<li class="toctree-l2"><a class="reference internal" href="profile.html">Configuration interface (profile)</a></li> 206<li class="toctree-l2 current"><a class="current reference internal" href="#">GSSAPI mechanism interface</a></li> 207<li class="toctree-l2"><a class="reference internal" href="internal.html">Internal pluggable interfaces</a></li> 208<li class="toctree-l2"><a class="reference internal" href="certauth.html">PKINIT certificate authorization interface (certauth)</a></li> 209<li class="toctree-l2"><a class="reference internal" href="kdcpolicy.html">KDC policy interface (kdcpolicy)</a></li> 210</ul> 211</li> 212<li class="toctree-l1"><a class="reference internal" href="../build/index.html">Building Kerberos V5</a></li> 213<li class="toctree-l1"><a class="reference internal" href="../basic/index.html">Kerberos V5 concepts</a></li> 214<li class="toctree-l1"><a class="reference internal" href="../formats/index.html">Protocols and file formats</a></li> 215<li class="toctree-l1"><a class="reference internal" href="../mitK5features.html">MIT Kerberos features</a></li> 216<li class="toctree-l1"><a class="reference internal" href="../build_this.html">How to build this documentation from the source</a></li> 217<li class="toctree-l1"><a class="reference internal" href="../about.html">Contributing to the MIT Kerberos Documentation</a></li> 218<li class="toctree-l1"><a class="reference internal" href="../resources.html">Resources</a></li> 219</ul> 220 221 <br/> 222 <h4><a href="../index.html">Full Table of Contents</a></h4> 223 <h4>Search</h4> 224 <form class="search" action="../search.html" method="get"> 225 <input type="text" name="q" size="18" /> 226 <input type="submit" value="Go" /> 227 <input type="hidden" name="check_keywords" value="yes" /> 228 <input type="hidden" name="area" value="default" /> 229 </form> 230 231 </div> 232 <div class="clearer"></div> 233 </div> 234 </div> 235 236 <div class="footer-wrapper"> 237 <div class="footer" > 238 <div class="right" ><i>Release: 1.21.3</i><br /> 239 © <a href="../copyright.html">Copyright</a> 1985-2024, MIT. 240 </div> 241 <div class="left"> 242 243 <a href="../index.html" title="Full Table of Contents" 244 >Contents</a> | 245 <a href="profile.html" title="Configuration interface (profile)" 246 >previous</a> | 247 <a href="internal.html" title="Internal pluggable interfaces" 248 >next</a> | 249 <a href="../genindex.html" title="General Index" 250 >index</a> | 251 <a href="../search.html" title="Enter search criteria" 252 >Search</a> | 253 <a href="mailto:krb5-bugs@mit.edu?subject=Documentation__GSSAPI mechanism interface">feedback</a> 254 </div> 255 </div> 256 </div> 257 258 </body> 259</html>