doc/html/plugindev/localauth.html

   1
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
   3   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   4
   5 <html xmlns="http://www.w3.org/1999/xhtml">
   6   <head>
   7     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   8     <title>Local authorization interface (localauth) &#8212; MIT Kerberos Documentation</title>
   9     <link rel="stylesheet" href="../_static/agogo.css" type="text/css" />
  10     <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
  11     <link rel="stylesheet" href="../_static/kerb.css" type="text/css" />
  12     <script type="text/javascript">
  13       var DOCUMENTATION_OPTIONS = {
  14         URL_ROOT:    '../',
  15         VERSION:     '1.20.1',
  16         COLLAPSE_INDEX: false,
  17         FILE_SUFFIX: '.html',
  18         HAS_SOURCE:  true,
  19         SOURCELINK_SUFFIX: '.txt'
  20       };
  21     </script>
  22     <script type="text/javascript" src="../_static/jquery.js"></script>
  23     <script type="text/javascript" src="../_static/underscore.js"></script>
  24     <script type="text/javascript" src="../_static/doctools.js"></script>
  25     <link rel="author" title="About these documents" href="../about.html" />
  26     <link rel="index" title="Index" href="../genindex.html" />
  27     <link rel="search" title="Search" href="../search.html" />
  28     <link rel="copyright" title="Copyright" href="../copyright.html" />
  29     <link rel="next" title="Server location interface (locate)" href="locate.html" />
  30     <link rel="prev" title="Host-to-realm interface (hostrealm)" href="hostrealm.html" />
  31   </head>
  32   <body>
  33     <div class="header-wrapper">
  34         <div class="header">
  35
  36
  37             <h1><a href="../index.html">MIT Kerberos Documentation</a></h1>
  38
  39             <div class="rel">
  40
  41         <a href="../index.html" title="Full Table of Contents"
  42             accesskey="C">Contents</a> |
  43         <a href="hostrealm.html" title="Host-to-realm interface (hostrealm)"
  44             accesskey="P">previous</a> |
  45         <a href="locate.html" title="Server location interface (locate)"
  46             accesskey="N">next</a> |
  47         <a href="../genindex.html" title="General Index"
  48             accesskey="I">index</a> |
  49         <a href="../search.html" title="Enter search criteria"
  50             accesskey="S">Search</a> |
  51     <a href="mailto:krb5-bugs@mit.edu?subject=Documentation__Local authorization interface (localauth)">feedback</a>
  52             </div>
  53         </div>
  54     </div>
  55
  56     <div class="content-wrapper">
  57       <div class="content">
  58         <div class="document">
  59
  60       <div class="documentwrapper">
  61         <div class="bodywrapper">
  62           <div class="body" role="main">
  63
  64   <div class="section" id="local-authorization-interface-localauth">
  65 <span id="localauth-plugin"></span><h1>Local authorization interface (localauth)<a class="headerlink" href="#local-authorization-interface-localauth" title="Permalink to this headline">¶</a></h1>
  66 <p>The localauth interface was first introduced in release 1.12.  It
  67 allows modules to control the relationship between Kerberos principals
  68 and local system accounts.  When an application calls
  69 <a class="reference internal" href="../appdev/refs/api/krb5_kuserok.html#c.krb5_kuserok" title="krb5_kuserok"><code class="xref c c-func docutils literal"><span class="pre">krb5_kuserok()</span></code></a> or <a class="reference internal" href="../appdev/refs/api/krb5_aname_to_localname.html#c.krb5_aname_to_localname" title="krb5_aname_to_localname"><code class="xref c c-func docutils literal"><span class="pre">krb5_aname_to_localname()</span></code></a>, localauth
  70 modules are consulted to determine the result.  For a detailed
  71 description of the localauth interface, see the header file
  72 <code class="docutils literal"><span class="pre">&lt;krb5/localauth_plugin.h&gt;</span></code>.</p>
  73 <p>A module can create and destroy per-library-context state objects
  74 using the <strong>init</strong> and <strong>fini</strong> methods.  If the module does not need
  75 any state, it does not need to implement these methods.</p>
  76 <p>The optional <strong>userok</strong> method allows a module to control the behavior
  77 of <a class="reference internal" href="../appdev/refs/api/krb5_kuserok.html#c.krb5_kuserok" title="krb5_kuserok"><code class="xref c c-func docutils literal"><span class="pre">krb5_kuserok()</span></code></a>.  The module receives the authenticated name
  78 and the local account name as inputs, and can return either 0 to
  79 authorize access, KRB5_PLUGIN_NO_HANDLE to defer the decision to other
  80 modules, or another error (canonically EPERM) to authoritatively deny
  81 access.  Access is granted if at least one module grants access and no
  82 module authoritatively denies access.</p>
  83 <p>The optional <strong>an2ln</strong> method can work in two different ways.  If the
  84 module sets an array of uppercase type names in <strong>an2ln_types</strong>, then
  85 the module’s <strong>an2ln</strong> method will only be invoked by
  86 <a class="reference internal" href="../appdev/refs/api/krb5_aname_to_localname.html#c.krb5_aname_to_localname" title="krb5_aname_to_localname"><code class="xref c c-func docutils literal"><span class="pre">krb5_aname_to_localname()</span></code></a> if an <strong>auth_to_local</strong> value in
  87 <a class="reference internal" href="../admin/conf_files/krb5_conf.html#krb5-conf-5"><span class="std std-ref">krb5.conf</span></a> refers to one of the module’s types.  In this
  88 case, the <em>type</em> and <em>residual</em> arguments will give the type name and
  89 residual string of the <strong>auth_to_local</strong> value.</p>
  90 <p>If the module does not set <strong>an2ln_types</strong> but does implement
  91 <strong>an2ln</strong>, the module’s <strong>an2ln</strong> method will be invoked for all
  92 <a class="reference internal" href="../appdev/refs/api/krb5_aname_to_localname.html#c.krb5_aname_to_localname" title="krb5_aname_to_localname"><code class="xref c c-func docutils literal"><span class="pre">krb5_aname_to_localname()</span></code></a> operations unless an earlier module
  93 determines a mapping, with <em>type</em> and <em>residual</em> set to NULL.  The
  94 module can return KRB5_LNAME_NO_TRANS to defer mapping to later
  95 modules.</p>
  96 <p>If a module implements <strong>an2ln</strong>, it must also implement
  97 <strong>free_string</strong> to ensure that memory is allocated and deallocated
  98 consistently.</p>
  99 </div>
 100
 101
 102           </div>
 103         </div>
 104       </div>
 105         </div>
 106         <div class="sidebar">
 107     <h2>On this page</h2>
 108     <ul>
 109 <li><a class="reference internal" href="#">Local authorization interface (localauth)</a></li>
 110 </ul>
 111
 112     <br/>
 113     <h2>Table of contents</h2>
 114     <ul class="current">
 115 <li class="toctree-l1"><a class="reference internal" href="../user/index.html">For users</a></li>
 116 <li class="toctree-l1"><a class="reference internal" href="../admin/index.html">For administrators</a></li>
 117 <li class="toctree-l1"><a class="reference internal" href="../appdev/index.html">For application developers</a></li>
 118 <li class="toctree-l1 current"><a class="reference internal" href="index.html">For plugin module developers</a><ul class="current">
 119 <li class="toctree-l2"><a class="reference internal" href="general.html">General plugin concepts</a></li>
 120 <li class="toctree-l2"><a class="reference internal" href="clpreauth.html">Client preauthentication interface (clpreauth)</a></li>
 121 <li class="toctree-l2"><a class="reference internal" href="kdcpreauth.html">KDC preauthentication interface (kdcpreauth)</a></li>
 122 <li class="toctree-l2"><a class="reference internal" href="ccselect.html">Credential cache selection interface (ccselect)</a></li>
 123 <li class="toctree-l2"><a class="reference internal" href="pwqual.html">Password quality interface (pwqual)</a></li>
 124 <li class="toctree-l2"><a class="reference internal" href="kadm5_hook.html">KADM5 hook interface (kadm5_hook)</a></li>
 125 <li class="toctree-l2"><a class="reference internal" href="kadm5_auth.html">kadmin authorization interface (kadm5_auth)</a></li>
 126 <li class="toctree-l2"><a class="reference internal" href="hostrealm.html">Host-to-realm interface (hostrealm)</a></li>
 127 <li class="toctree-l2 current"><a class="current reference internal" href="#">Local authorization interface (localauth)</a></li>
 128 <li class="toctree-l2"><a class="reference internal" href="locate.html">Server location interface (locate)</a></li>
 129 <li class="toctree-l2"><a class="reference internal" href="profile.html">Configuration interface (profile)</a></li>
 130 <li class="toctree-l2"><a class="reference internal" href="gssapi.html">GSSAPI mechanism interface</a></li>
 131 <li class="toctree-l2"><a class="reference internal" href="internal.html">Internal pluggable interfaces</a></li>
 132 <li class="toctree-l2"><a class="reference internal" href="certauth.html">PKINIT certificate authorization interface (certauth)</a></li>
 133 <li class="toctree-l2"><a class="reference internal" href="kdcpolicy.html">KDC policy interface (kdcpolicy)</a></li>
 134 </ul>
 135 </li>
 136 <li class="toctree-l1"><a class="reference internal" href="../build/index.html">Building Kerberos V5</a></li>
 137 <li class="toctree-l1"><a class="reference internal" href="../basic/index.html">Kerberos V5 concepts</a></li>
 138 <li class="toctree-l1"><a class="reference internal" href="../formats/index.html">Protocols and file formats</a></li>
 139 <li class="toctree-l1"><a class="reference internal" href="../mitK5features.html">MIT Kerberos features</a></li>
 140 <li class="toctree-l1"><a class="reference internal" href="../build_this.html">How to build this documentation from the source</a></li>
 141 <li class="toctree-l1"><a class="reference internal" href="../about.html">Contributing to the MIT Kerberos Documentation</a></li>
 142 <li class="toctree-l1"><a class="reference internal" href="../resources.html">Resources</a></li>
 143 </ul>
 144
 145     <br/>
 146     <h4><a href="../index.html">Full Table of Contents</a></h4>
 147     <h4>Search</h4>
 148     <form class="search" action="../search.html" method="get">
 149       <input type="text" name="q" size="18" />
 150       <input type="submit" value="Go" />
 151       <input type="hidden" name="check_keywords" value="yes" />
 152       <input type="hidden" name="area" value="default" />
 153     </form>
 154         </div>
 155         <div class="clearer"></div>
 156       </div>
 157     </div>
 158
 159     <div class="footer-wrapper">
 160         <div class="footer" >
 161             <div class="right" ><i>Release: 1.20.1</i><br />
 162                 &copy; <a href="../copyright.html">Copyright</a> 1985-2022, MIT.
 163             </div>
 164             <div class="left">
 165
 166         <a href="../index.html" title="Full Table of Contents"
 167             >Contents</a> |
 168         <a href="hostrealm.html" title="Host-to-realm interface (hostrealm)"
 169             >previous</a> |
 170         <a href="locate.html" title="Server location interface (locate)"
 171             >next</a> |
 172         <a href="../genindex.html" title="General Index"
 173             >index</a> |
 174         <a href="../search.html" title="Enter search criteria"
 175             >Search</a> |
 176     <a href="mailto:krb5-bugs@mit.edu?subject=Documentation__Local authorization interface (localauth)">feedback</a>
 177             </div>
 178         </div>
 179     </div>
 180
 181   </body>
 182 </html>