<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Components — Cyrus SASL 2.1.27 documentation</title>
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="stylesheet" href="../_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="../_static/cyrus.css" type="text/css" />
<link rel="index" title="Index"
href="../genindex.html"/>
<link rel="search" title="Search" href="../search.html"/>
<link rel="top" title="Cyrus SASL 2.1.27 documentation" href="../index.html"/>
<link rel="up" title="Setup" href="../setup.html"/>
<link rel="next" title="Options" href="options.html"/>
<link rel="prev" title="Upgrading from v1 to v2" href="upgrading.html"/>
</head>
<body class="wy-body-for-nav" role="document">
<div class="pageheader">
<ul>
<li><a href="../index.html">Home</a></li>
<li><a href="http://www.cyrusimap.org">Cyrus IMAP</a></li>
<li><a href="../download.html">Download</a></li>
<li><a href="../contribute.html">Contribute</a></li>
</ul>
<div>
<a href="../index.html">
<img src="../_static/logo.gif" alt="CYRUS SASL" />
</a>
</div>
</div>
<div style="clear: both;"></div>
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-nav-search">
<a href="../index.html">
<img src="../_static/logo.gif" />
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
<p class="caption"><span class="caption-text">Cyrus SASL</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../download.html">Download</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../getsasl.html">Get SASL</a><ul>
<li class="toctree-l3"><a class="reference internal" href="installation.html">Installation</a><ul>
<li class="toctree-l4"><a class="reference internal" href="installation.html#quick-install-guide">Quick install guide</a></li>
<li class="toctree-l4"><a class="reference internal" href="installation.html#detailed-installation-guide">Detailed installation guide</a></li>
<li class="toctree-l4"><a class="reference internal" href="installation.html#supported-platforms">Supported platforms</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="release-notes/index.html">Release Notes</a><ul>
<li class="toctree-l3"><a class="reference internal" href="release-notes/index.html#supported-product-series">Supported Product Series</a><ul>
<li class="toctree-l4"><a class="reference internal" href="release-notes/index.html#series-2-1">Series 2.1</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="release-notes/index.html#older-versions">Older Versions</a><ul>
<li class="toctree-l4"><a class="reference internal" href="release-notes/index.html#series-2-2-0">Series 2: 2.0</a></li>
<li class="toctree-l4"><a class="reference internal" href="release-notes/index.html#series-1">Series 1</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../packager.html">Note for Packagers</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="quickstart.html">Quickstart guide</a><ul>
<li class="toctree-l2"><a class="reference internal" href="quickstart.html#features">Features</a></li>
<li class="toctree-l2"><a class="reference internal" href="quickstart.html#typical-installation">Typical Installation</a></li>
<li class="toctree-l2"><a class="reference internal" href="quickstart.html#configuration">Configuration</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="concepts.html">Concepts</a><ul>
<li class="toctree-l2"><a class="reference internal" href="concepts.html#sasl">SASL</a></li>
<li class="toctree-l2"><a class="reference internal" href="concepts.html#sasl-authentication-mechanisms">SASL Authentication Mechanisms</a></li>
<li class="toctree-l2"><a class="reference internal" href="concepts.html#security-layers">Security Layers</a></li>
<li class="toctree-l2"><a class="reference internal" href="concepts.html#channel-binding">Channel Binding</a></li>
<li class="toctree-l2"><a class="reference internal" href="concepts.html#realms">Realms</a></li>
<li class="toctree-l2"><a class="reference internal" href="concepts.html#protocols">Protocols</a></li>
<li class="toctree-l2"><a class="reference internal" href="concepts.html#cyrus-sasl">Cyrus SASL</a></li>
<li class="toctree-l2"><a class="reference internal" href="concepts.html#the-glue-library">The Glue Library</a></li>
<li class="toctree-l2"><a class="reference internal" href="concepts.html#auxiliary-properties">Auxiliary Properties</a></li>
<li class="toctree-l2"><a class="reference internal" href="concepts.html#plugins">Plugins</a></li>
</ul>
</li>
<li class="toctree-l1 current"><a class="reference internal" href="../setup.html">Setup</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="installation.html">Installation</a><ul>
<li class="toctree-l3"><a class="reference internal" href="installation.html#quick-install-guide">Quick install guide</a><ul>
<li class="toctree-l4"><a class="reference internal" href="installation.html#tarball-installation">Tarball installation</a></li>
<li class="toctree-l4"><a class="reference internal" href="installation.html#unix-package-installation">Unix package Installation</a></li>
<li class="toctree-l4"><a class="reference internal" href="installation.html#configuration">Configuration</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="installation.html#detailed-installation-guide">Detailed installation guide</a><ul>
<li class="toctree-l4"><a class="reference internal" href="installation.html#requirements">Requirements</a></li>
<li class="toctree-l4"><a class="reference internal" href="installation.html#build-configuration">Build Configuration</a></li>
<li class="toctree-l4"><a class="reference internal" href="installation.html#building-and-installation">Building and Installation</a></li>
<li class="toctree-l4"><a class="reference internal" href="installation.html#compilation-hints">Compilation Hints</a></li>
<li class="toctree-l4"><a class="reference internal" href="installation.html#application-configuration">Application Configuration</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="installation.html#supported-platforms">Supported platforms</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="upgrading.html">Upgrading from v1 to v2</a><ul>
<li class="toctree-l3"><a class="reference internal" href="upgrading.html#backwards-compatibility">Backwards Compatibility</a></li>
<li class="toctree-l3"><a class="reference internal" href="upgrading.html#coexistence-with-saslv1">Coexistence with SASLv1</a></li>
<li class="toctree-l3"><a class="reference internal" href="upgrading.html#database-upgrades">Database Upgrades</a></li>
<li class="toctree-l3"><a class="reference internal" href="upgrading.html#errors-on-migration">Errors on migration</a></li>
</ul>
</li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">Components</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#the-application">The Application</a></li>
<li class="toctree-l3"><a class="reference internal" href="#the-sasl-glue-layer">The SASL Glue Layer</a></li>
<li class="toctree-l3"><a class="reference internal" href="#plugins">Plugins</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#plugins-general">Plugins: General</a></li>
<li class="toctree-l4"><a class="reference internal" href="#plugins-sasl-mechanisms">Plugins: SASL Mechanisms</a></li>
<li class="toctree-l4"><a class="reference internal" href="#plugins-auxiliary-property">Plugins: Auxiliary Property</a></li>
<li class="toctree-l4"><a class="reference internal" href="#plugins-username-canonicalization">Plugins: Username Canonicalization</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#password-verification-services">Password Verification Services</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="options.html">Options</a><ul>
<li class="toctree-l3"><a class="reference internal" href="options.html#sasl-library">SASL Library</a></li>
<li class="toctree-l3"><a class="reference internal" href="options.html#auxiliary-property-plugin">Auxiliary Property Plugin</a></li>
<li class="toctree-l3"><a class="reference internal" href="options.html#gssapi">GSSAPI</a></li>
<li class="toctree-l3"><a class="reference internal" href="options.html#ldapdb">LDAPDB</a><ul>
<li class="toctree-l4"><a class="reference internal" href="options.html#notes-on-ldapdb">Notes on LDAPDB</a></li>
<li class="toctree-l4"><a class="reference internal" href="options.html#examples">Examples</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="options.html#ntlm">NTLM</a></li>
<li class="toctree-l3"><a class="reference internal" href="options.html#otp">OTP</a></li>
<li class="toctree-l3"><a class="reference internal" href="options.html#digest-md5">Digest-md5</a></li>
<li class="toctree-l3"><a class="reference internal" href="options.html#sasldb">SASLDB</a><ul>
<li class="toctree-l4"><a class="reference internal" href="options.html#notes-on-sasldb-with-lmdb">Notes on sasldb with LMDB</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="options.html#sql-plugin">SQL Plugin</a><ul>
<li class="toctree-l4"><a class="reference internal" href="options.html#notes-on-sql">Notes on SQL</a></li>
<li class="toctree-l4"><a class="reference internal" href="options.html#id2">Examples</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="options.html#srp">SRP</a></li>
<li class="toctree-l3"><a class="reference internal" href="options.html#kerberos-v4">Kerberos V4</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="advanced.html">Advanced Usage</a><ul>
<li class="toctree-l3"><a class="reference internal" href="advanced.html#notes-for-advanced-usage-of-libsasl">Notes for Advanced Usage of libsasl</a><ul>
<li class="toctree-l4"><a class="reference internal" href="advanced.html#using-cyrus-sasl-as-a-static-library">Using Cyrus SASL as a static library</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../operations.html">Operations</a><ul>
<li class="toctree-l2"><a class="reference internal" href="sysadmin.html">System Administrators</a><ul>
<li class="toctree-l3"><a class="reference internal" href="sysadmin.html#what-sasl-is">What SASL is</a><ul>
<li class="toctree-l4"><a class="reference internal" href="sysadmin.html#authentication-and-authorization-identifiers">Authentication and authorization identifiers</a></li>
<li class="toctree-l4"><a class="reference internal" href="sysadmin.html#realms">Realms</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="sysadmin.html#how-sasl-works">How SASL works</a><ul>
<li class="toctree-l4"><a class="reference internal" href="sysadmin.html#the-plain-mechanism-sasl-checkpass-and-plaintext-passwords">The PLAIN mechanism, <code class="docutils literal"><span class="pre">sasl_checkpass()</span></code>, and plaintext passwords</a></li>
<li class="toctree-l4"><a class="reference internal" href="sysadmin.html#shared-secrets-mechanisms">Shared secrets mechanisms</a></li>
<li class="toctree-l4"><a class="reference internal" href="sysadmin.html#kerberos-mechanisms">Kerberos mechanisms</a></li>
<li class="toctree-l4"><a class="reference internal" href="sysadmin.html#the-otp-mechanism">The OTP mechanism</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="sysadmin.html#auxiliary-properties">Auxiliary Properties</a></li>
<li class="toctree-l3"><a class="reference internal" href="sysadmin.html#how-to-set-configuration-options">How to set configuration options</a><ul>
<li class="toctree-l4"><a class="reference internal" href="sysadmin.html#the-default-configuration-file">The default configuration file</a></li>
<li class="toctree-l4"><a class="reference internal" href="sysadmin.html#application-configuration">Application configuration</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="sysadmin.html#troubleshooting">Troubleshooting</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="manpages.html">Man pages</a><ul>
<li class="toctree-l3"><a class="reference internal" href="manpages.html#library-files">(3) Library Files</a><ul>
<li class="toctree-l4"><a class="reference internal" href="reference/manpages/library/sasl.html"><strong>SASL</strong> - SASL Authentication Library</a></li>
<li class="toctree-l4"><a class="reference internal" href="reference/manpages/library/sasl_authorize_t.html"><strong>sasl_authorize_t</strong> - The SASL authorization callback</a></li>
<li class="toctree-l4"><a class="reference internal" href="reference/manpages/library/sasl_auxprop.html"><strong>sasl_auxprop</strong> - How to work with SASL auxiliary properties</a></li>
<li class="toctree-l4"><a class="reference internal" href="reference/manpages/library/sasl_auxprop_add_plugin.html"><strong>sasl_auxprop_add_plugin</strong> - add a SASL auxiliary property plugin</a></li>
<li class="toctree-l4"><a class="reference internal" href="reference/manpages/library/sasl_auxprop_getctx.html"><strong>sasl_auxprop_getctx</strong> - Acquire an auxiliary property context</a></li>
<li class="toctree-l4"><a class="reference internal" href="reference/manpages/library/sasl_auxprop_request.html"><strong>sasl_auxprop_request</strong> - Request auxiliary properties from SASL</a></li>
<li class="toctree-l4"><a class="reference internal" href="reference/manpages/library/sasl_callbacks.html"><strong>sasl_callbacks</strong> - How to work with SASL callbacks</a></li>
<li class="toctree-l4"><a class="reference internal" href="reference/manpages/library/sasl_canon_user_t.html"><strong>sasl_canon_user_t</strong> - Application-supplied user canonicalization function</a></li>
<li class="toctree-l4"><a class="reference internal" href="reference/manpages/library/sasl_canonuser_add_plugin.html"><strong>sasl_canonuser_add_plugin</strong> - add a SASL user canonicalization plugin</a></li>
<li class="toctree-l4"><a class="reference internal" href="reference/manpages/library/sasl_chalprompt_t.html"><strong>sasl_chalprompt_t</strong> - Realm acquisition callback</a></li>
<li class="toctree-l4"><a class="reference internal" href="reference/manpages/library/sasl_checkapop.html"><strong>sasl_checkapop</strong> - Check an APOP challenge/response</a></li>
<li class="toctree-l4"><a class="reference internal" href="reference/manpages/library/sasl_checkpass.html"><strong>sasl_checkpass</strong> - Check a plaintext password</a></li>
<li class="toctree-l4"><a class="reference internal" href="reference/manpages/library/sasl_client_add_plugin.html"><strong>sasl_client_add_plugin</strong> - add a SASL client plugin</a></li>
<li class="toctree-l4"><a class="reference internal" href="reference/manpages/library/sasl_client_done.html"><strong>sasl_client_done</strong> - Cleanup function</a></li>
<li class="toctree-l4"><a class="reference internal" href="reference/manpages/library/sasl_client_init.html"><strong>sasl_client_init</strong> - SASL client authentication initialization</a></li>
<li class="toctree-l4"><a class="reference internal" href="reference/manpages/library/sasl_client_new.html"><strong>sasl_client_new</strong> - Create a new client authentication object</a></li>
<li class="toctree-l4"><a class="reference internal" href="reference/manpages/library/sasl_client_plug_init_t.html"><strong>sasl_client_plug_init_t</strong> - client plug‐in entry point</a></li>
<li class="toctree-l4"><a class="reference internal" href="reference/manpages/library/sasl_client_start.html"><strong>sasl_client_start</strong> - Begin an authentication negotiation</a></li>
<li class="toctree-l4"><a class="reference internal" href="reference/manpages/library/sasl_client_step.html"><strong>sasl_client_step</strong> - Perform a step in the authentication negotiation</a></li>
<li class="toctree-l4"><a class="reference internal" href="reference/manpages/library/sasl_decode.html"><strong>sasl_decode</strong> - Decode data received</a></li>
<li class="toctree-l4"><a class="reference internal" href="reference/manpages/library/sasl_decode64.html"><strong>sasl_decode64</strong> - Decode base64 string</a></li>
<li class="toctree-l4"><a class="reference internal" href="reference/manpages/library/sasl_dispose.html"><strong>sasl_dispose</strong> - Dispose of a SASL connection object</a></li>
<li class="toctree-l4"><a class="reference internal" href="reference/manpages/library/sasl_done.html"><strong>sasl_done</strong> - Dispose of a SASL connection object</a></li>
<li class="toctree-l4"><a class="reference internal" href="reference/manpages/library/sasl_encode.html"><strong>sasl_encode</strong> - Encode data for transport to authenticated host</a></li>
<li class="toctree-l4"><a class="reference internal" href="reference/manpages/library/sasl_encode64.html"><strong>sasl_encode64</strong> - Encode base64 string</a></li>
<li class="toctree-l4"><a class="reference internal" href="reference/manpages/library/sasl_encodev.html"><strong>sasl_encodev</strong> - Encode data for transport to authenticated host</a></li>
<li class="toctree-l4"><a class="reference internal" href="reference/manpages/library/sasl_erasebuffer.html"><strong>sasl_erasebuffer</strong> - erase buffer</a></li>
<li class="toctree-l4"><a class="reference internal" href="reference/manpages/library/sasl_errdetail.html"><strong>sasl_errdetail</strong> - Retrieve detailed information about an error</a></li>
<li class="toctree-l4"><a class="reference internal" href="reference/manpages/library/sasl_errors.html"><strong>sasl_errors</strong> - SASL error codes</a></li>
<li class="toctree-l4"><a class="reference internal" href="reference/manpages/library/sasl_errstring.html"><strong>sasl_errstring</strong> - Translate a SASL return code to a human-readable form</a></li>
<li class="toctree-l4"><a class="reference internal" href="reference/manpages/library/sasl_getcallback_t.html"><strong>sasl_getcallback_t</strong> - callback function to lookup a sasl_callback_t for a connection</a></li>
<li class="toctree-l4"><a class="reference internal" href="reference/manpages/library/sasl_getconfpath_t.html"><strong>sasl_getconfpath_t</strong> - The SASL callback to indicate location of the config files</a></li>
<li class="toctree-l4"><a class="reference internal" href="reference/manpages/library/sasl_getopt_t.html"><strong>sasl_getopt_t</strong> - The SASL get option callback</a></li>
<li class="toctree-l4"><a class="reference internal" href="reference/manpages/library/sasl_getpath_t.html"><strong>sasl_getpath_t</strong> - The SASL callback to indicate location of the mechanism drivers</a></li>
<li class="toctree-l4"><a class="reference internal" href="reference/manpages/library/sasl_getprop.html"><strong>sasl_getprop</strong> - Get a SASL property</a></li>
<li class="toctree-l4"><a class="reference internal" href="reference/manpages/library/sasl_getrealm_t.html"><strong>sasl_getrealm_t</strong> - Realm Acquisition Callback</a></li>
<li class="toctree-l4"><a class="reference internal" href="reference/manpages/library/sasl_getsecret_t.html"><strong>sasl_getsecret_t</strong> - The SASL callback for secrets (passwords)</a></li>
<li class="toctree-l4"><a class="reference internal" href="reference/manpages/library/sasl_getsimple_t.html"><strong>sasl_getsimple_t</strong> - The SASL callback for username/authname/realm</a></li>
<li class="toctree-l4"><a class="reference internal" href="reference/manpages/library/sasl_global_listmech.html"><strong>sasl_global_listmech</strong> - Retrieve a list of the supported SASL mechanisms</a></li>
<li class="toctree-l4"><a class="reference internal" href="reference/manpages/library/sasl_idle.html"><strong>sasl_idle</strong> - Perform precalculations during an idle period</a></li>
<li class="toctree-l4"><a class="reference internal" href="reference/manpages/library/sasl_listmech.html"><strong>sasl_listmech</strong> - Retrieve a list of the supported SASL mechanisms</a></li>
<li class="toctree-l4"><a class="reference internal" href="reference/manpages/library/sasl_log_t.html"><strong>sasl_log_t</strong> - The SASL logging callback</a></li>
<li class="toctree-l4"><a class="reference internal" href="reference/manpages/library/sasl_server_add_plugin.html"><strong>sasl_server_add_plugin</strong> - add a SASL server plugin</a></li>
<li class="toctree-l4"><a class="reference internal" href="reference/manpages/library/sasl_server_done.html"><strong>sasl_server_done</strong> - Cleanup function</a></li>
<li class="toctree-l4"><a class="reference internal" href="reference/manpages/library/sasl_server_init.html"><strong>sasl_server_init</strong> - SASL server authentication initialization</a></li>
<li class="toctree-l4"><a class="reference internal" href="reference/manpages/library/sasl_server_new.html"><strong>sasl_server_new</strong> - Create a new server authentication object</a></li>
<li class="toctree-l4"><a class="reference internal" href="reference/manpages/library/sasl_server_plug_init_t.html"><strong>sasl_server_plug_init_t</strong> - server plug‐in entry point</a></li>
<li class="toctree-l4"><a class="reference internal" href="reference/manpages/library/sasl_server_start.html"><strong>sasl_server_start</strong> - Begin an authentication negotiation</a></li>
<li class="toctree-l4"><a class="reference internal" href="reference/manpages/library/sasl_server_step.html"><strong>sasl_server_step</strong> - Perform a step in the authentication negotiation</a></li>
<li class="toctree-l4"><a class="reference internal" href="reference/manpages/library/sasl_server_userdb_checkpass_t.html"><strong>sasl_server_userdb_checkpass_t</strong> - Plaintext Password Verification Callback</a></li>
<li class="toctree-l4"><a class="reference internal" href="reference/manpages/library/sasl_server_userdb_setpass_t.html"><strong>sasl_server_userdb_setpass_t</strong> - UserDB Plaintext Password Setting Callback</a></li>
<li class="toctree-l4"><a class="reference internal" href="reference/manpages/library/sasl_set_alloc.html"><strong>sasl_set_alloc</strong> - set the memory allocation functions used by the SASL library</a></li>
<li class="toctree-l4"><a class="reference internal" href="reference/manpages/library/sasl_set_mutex.html"><strong>sasl_set_mutex</strong> - set the mutex lock functions used by the SASL library</a></li>
<li class="toctree-l4"><a class="reference internal" href="reference/manpages/library/sasl_seterror.html"><strong>sasl_seterror</strong> - set the error string</a></li>
<li class="toctree-l4"><a class="reference internal" href="reference/manpages/library/sasl_setpass.html"><strong>sasl_setpass</strong> - Check a plaintext password</a></li>
<li class="toctree-l4"><a class="reference internal" href="reference/manpages/library/sasl_setprop.html"><strong>sasl_setprop</strong> - Set a SASL property</a></li>
<li class="toctree-l4"><a class="reference internal" href="reference/manpages/library/sasl_user_exists.html"><strong>sasl_user_exists</strong> - Check if a user exists on server</a></li>
<li class="toctree-l4"><a class="reference internal" href="reference/manpages/library/sasl_usererr.html"><strong>sasl_usererr</strong> - Remove information leak about accounts from sasl error codes</a></li>
<li class="toctree-l4"><a class="reference internal" href="reference/manpages/library/sasl_utf8verify.html"><strong>sasl_utf8verify</strong> - Verify a string is valid utf8</a></li>
<li class="toctree-l4"><a class="reference internal" href="reference/manpages/library/sasl_verifyfile_t.html"><strong>sasl_verifyfile_t</strong> - The SASL file verification</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="auxiliary_properties.html">Auxiliary Properties</a><ul>
<li class="toctree-l3"><a class="reference internal" href="auxiliary_properties.html#auxiliary-properties-and-the-glue-layer">Auxiliary Properties and the Glue Layer</a></li>
<li class="toctree-l3"><a class="reference internal" href="auxiliary_properties.html#passwords-and-other-data">Passwords and other Data</a></li>
<li class="toctree-l3"><a class="reference internal" href="auxiliary_properties.html#sasldb">sasldb</a></li>
<li class="toctree-l3"><a class="reference internal" href="auxiliary_properties.html#ldapdb">ldapdb</a></li>
<li class="toctree-l3"><a class="reference internal" href="auxiliary_properties.html#sql">sql</a></li>
<li class="toctree-l3"><a class="reference internal" href="auxiliary_properties.html#user-canonicalization">User Canonicalization</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="authentication_mechanisms.html">Authentication Mechanisms</a><ul>
<li class="toctree-l3"><a class="reference internal" href="authentication_mechanisms.html#mechanisms">Mechanisms</a><ul>
<li class="toctree-l4"><a class="reference internal" href="authentication_mechanisms.html#anonymous">ANONYMOUS</a></li>
<li class="toctree-l4"><a class="reference internal" href="authentication_mechanisms.html#cram-md5">CRAM-MD5</a></li>
<li class="toctree-l4"><a class="reference internal" href="authentication_mechanisms.html#digest-md5">DIGEST-MD5</a></li>
<li class="toctree-l4"><a class="reference internal" href="authentication_mechanisms.html#external">EXTERNAL</a></li>
<li class="toctree-l4"><a class="reference internal" href="authentication_mechanisms.html#g2">G2</a></li>
<li class="toctree-l4"><a class="reference internal" href="authentication_mechanisms.html#gssapi">GSSAPI</a></li>
<li class="toctree-l4"><a class="reference internal" href="authentication_mechanisms.html#gss-spegno">GSS-SPEGNO</a></li>
<li class="toctree-l4"><a class="reference internal" href="authentication_mechanisms.html#kerberos-v4">KERBEROS_V4</a></li>
<li class="toctree-l4"><a class="reference internal" href="authentication_mechanisms.html#login">LOGIN</a></li>
<li class="toctree-l4"><a class="reference internal" href="authentication_mechanisms.html#ntlm">NTLM</a></li>
<li class="toctree-l4"><a class="reference internal" href="authentication_mechanisms.html#otp">OTP</a></li>
<li class="toctree-l4"><a class="reference internal" href="authentication_mechanisms.html#passdss">PASSDSS</a></li>
<li class="toctree-l4"><a class="reference internal" href="authentication_mechanisms.html#plain">PLAIN</a></li>
<li class="toctree-l4"><a class="reference internal" href="authentication_mechanisms.html#scram">SCRAM</a></li>
<li class="toctree-l4"><a class="reference internal" href="authentication_mechanisms.html#srp">SRP</a></li>
<li class="toctree-l4"><a class="reference internal" href="authentication_mechanisms.html#non-sasl-authentication">Non-SASL Authentication</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="authentication_mechanisms.html#summary">Summary</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="pwcheck.html">Pwcheck</a><ul>
<li class="toctree-l3"><a class="reference internal" href="pwcheck.html#auxprop">Auxprop</a></li>
<li class="toctree-l3"><a class="reference internal" href="pwcheck.html#auxprop-hashed">Auxprop-hashed</a></li>
<li class="toctree-l3"><a class="reference internal" href="pwcheck.html#saslauthd">Saslauthd</a></li>
<li class="toctree-l3"><a class="reference internal" href="pwcheck.html#authdaemon">Authdaemon</a></li>
<li class="toctree-l3"><a class="reference internal" href="pwcheck.html#alwaystrue">Alwaystrue</a></li>
<li class="toctree-l3"><a class="reference internal" href="pwcheck.html#auto-transition">Auto Transition</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="faq.html">Frequently Asked Questions</a><ul>
<li class="toctree-l3"><a class="reference internal" href="faqs/authorize-vs-authenticate.html">What is the difference between an Authorization ID and a Authentication ID?</a></li>
<li class="toctree-l3"><a class="reference internal" href="faqs/crammd5-digestmd5.html">Why do CRAM-MD5 and DIGEST-MD5 not work with CyrusSaslauthd?</a></li>
<li class="toctree-l3"><a class="reference internal" href="faqs/openldap-sasl-gssapi.html">How do I configure OpenLDAP +SASL+GSSAPI?</a></li>
<li class="toctree-l3"><a class="reference internal" href="faqs/plaintextpasswords.html">Why does CyrusSasl store plaintext passwords in its databases?</a></li>
<li class="toctree-l3"><a class="reference internal" href="faqs/rfcs.html">RFCs and drafts</a></li>
<li class="toctree-l3"><a class="reference internal" href="faqs/upgrade-saslv2.html">Why am I having a problem running dbconverter-2 to upgrade from SASLv1 to SASLv2?</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="resources.html">Other Documentation & Resources</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../developer.html">Developers</a><ul>
<li class="toctree-l2"><a class="reference internal" href="appconvert.html">Converting Applications from v1 to v2</a><ul>
<li class="toctree-l3"><a class="reference internal" href="appconvert.html#tips-for-both-clients-and-servers">Tips for both clients and servers</a></li>
<li class="toctree-l3"><a class="reference internal" href="appconvert.html#tips-for-clients">Tips for clients</a></li>
<li class="toctree-l3"><a class="reference internal" href="appconvert.html#tips-for-servers">Tips for Servers</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="developer/programming.html">Application Programmer’s Guide</a><ul>
<li class="toctree-l3"><a class="reference internal" href="developer/programming.html#introduction">Introduction</a><ul>
<li class="toctree-l4"><a class="reference internal" href="developer/programming.html#about-this-guide">About this Guide</a></li>
<li class="toctree-l4"><a class="reference internal" href="developer/programming.html#what-is-sasl">What is SASL?</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="developer/programming.html#background">Background</a><ul>
<li class="toctree-l4"><a class="reference internal" href="developer/programming.html#how-did-the-world-work-before-sasl">How did the world work before SASL?</a></li>
<li class="toctree-l4"><a class="reference internal" href="developer/programming.html#sasl-to-the-rescue">SASL to the rescue!</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="developer/programming.html#briefly">Briefly</a><ul>
<li class="toctree-l4"><a class="reference internal" href="developer/programming.html#what-is-the-cyrus-sasl-library-good-for">What is the Cyrus SASL library good for?</a></li>
<li class="toctree-l4"><a class="reference internal" href="developer/programming.html#what-does-the-cyrus-sasl-library-do">What does the Cyrus SASL library do?</a></li>
<li class="toctree-l4"><a class="reference internal" href="developer/programming.html#what-doesn-t-the-cyrus-sasl-library-do">What doesn’t the Cyrus SASL library do?</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="developer/programming.html#client-only-section">Client-only Section</a><ul>
<li class="toctree-l4"><a class="reference internal" href="developer/programming.html#a-typical-interaction-from-the-client-s-perspective">A typical interaction from the client’s perspective</a></li>
<li class="toctree-l4"><a class="reference internal" href="developer/programming.html#how-does-this-look-in-code">How does this look in code</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="developer/programming.html#server-only-section">Server-only Section</a><ul>
<li class="toctree-l4"><a class="reference internal" href="developer/programming.html#a-typical-interaction-from-the-server-s-perspective">A typical interaction from the server’s perspective</a></li>
<li class="toctree-l4"><a class="reference internal" href="developer/programming.html#id1">How does this look in code?</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="developer/programming.html#common-section">Common Section</a><ul>
<li class="toctree-l4"><a class="reference internal" href="developer/programming.html#callbacks-and-interactions">Callbacks and Interactions</a></li>
<li class="toctree-l4"><a class="reference internal" href="developer/programming.html#security-layers">Security layers</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="developer/programming.html#example-applications-that-come-with-the-cyrus-sasl-library">Example applications that come with the Cyrus SASL library</a><ul>
<li class="toctree-l4"><a class="reference internal" href="developer/programming.html#sample-client-and-sample-server"><cite>sample-client</cite> and <cite>sample-server</cite></a></li>
<li class="toctree-l4"><a class="reference internal" href="developer/programming.html#cyrus-imapd-v2-1-0-or-later">Cyrus imapd v2.1.0 or later</a></li>
<li class="toctree-l4"><a class="reference internal" href="developer/programming.html#imtest-from-cyrus-2-1-0-or-later"><cite>imtest</cite>, from Cyrus 2.1.0 or later</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="developer/programming.html#miscellaneous-information">Miscellaneous Information</a><ul>
<li class="toctree-l4"><a class="reference internal" href="developer/programming.html#empty-exchanges">Empty exchanges</a></li>
<li class="toctree-l4"><a class="reference internal" href="developer/programming.html#idle">Idle</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="developer/plugprog.html">Plugin Programmer’s Guide</a><ul>
<li class="toctree-l3"><a class="reference internal" href="developer/plugprog.html#introduction">Introduction</a><ul>
<li class="toctree-l4"><a class="reference internal" href="developer/plugprog.html#about-this-guide">About this Guide</a></li>
<li class="toctree-l4"><a class="reference internal" href="developer/plugprog.html#what-is-sasl">What is SASL?</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="developer/plugprog.html#common-section">Common Section</a><ul>
<li class="toctree-l4"><a class="reference internal" href="developer/plugprog.html#overview-of-plugin-programming">Overview of Plugin Programming</a></li>
<li class="toctree-l4"><a class="reference internal" href="developer/plugprog.html#use-of-sasl-utils-t">Use of sasl_utils_t</a></li>
<li class="toctree-l4"><a class="reference internal" href="developer/plugprog.html#error-reporting">Error Reporting</a></li>
<li class="toctree-l4"><a class="reference internal" href="developer/plugprog.html#memory-allocation">Memory Allocation</a></li>
<li class="toctree-l4"><a class="reference internal" href="developer/plugprog.html#client-send-first-server-send-last">Client Send First / Server Send Last</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="developer/plugprog.html#client-plugins">Client Plugins</a></li>
<li class="toctree-l3"><a class="reference internal" href="developer/plugprog.html#server-plugins">Server Plugins</a></li>
<li class="toctree-l3"><a class="reference internal" href="developer/plugprog.html#user-canonicalization-canon-user-plugins">User Canonicalization (canon_user) Plugins</a></li>
<li class="toctree-l3"><a class="reference internal" href="developer/plugprog.html#auxiliary-property-auxprop-plugins">Auxiliary Property (auxprop) Plugins</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="developer/testing.html">Testing</a><ul>
<li class="toctree-l3"><a class="reference internal" href="developer/testing.html#testing-the-cmu-sasl-library-with-the-included-sample-applications">Testing the CMU SASL Library with the included sample applications</a><ul>
<li class="toctree-l4"><a class="reference internal" href="developer/testing.html#example">Example</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="developer/testing.html#running-the-testsuite-application">Running the Testsuite application</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../support.html">Support/Community</a></li>
</ul>
<p class="caption"><span class="caption-text">IMAP</span></p>
<ul>
<li class="toctree-l1"><a class="reference external" href="http://www.cyrusimap.org">Cyrus IMAP</a></li>
</ul>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../index.html">Cyrus SASL</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="../index.html">Docs v2.1.27</a> »</li>
<li><a href="../setup.html">Setup</a> »</li>
<li>Components</li>
<li class="wy-breadcrumbs-aside">
<a href="https://github.com/cyrusimap/cyrus-sasl/blob/master/docsrc/sasl/components.rst" class="fa fa-github"> Edit on GitHub</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document">
<div class="section" id="components">
<span id="id1"></span><h1>Components<a class="headerlink" href="#components" title="Permalink to this headline">¶</a></h1>
<p>As the SASL library is a ‘glue layer’ between many different parts of the
authentication system, there are a lot of different components
that often cause confusion to users of the library who are trying to
configure it for use on their system. This document will try to provide
some structure to all of these components, though you will also need
to read the <a class="reference internal" href="sysadmin.html#sysadmin"><span class="std std-ref">System Administration</span></a> to have a full
understanding of how to install SASL on your system.</p>
<p>The first thing to realize is that there is a difference between SASL,
the protocol, and Cyrus SASL, the library. The first is a specification
that describes how authentication mechanisms can be plugged into an application
protocol <em>on the wire</em>. The later is an implementation that aims
to make this easier for application developers to integrate authentication
mechanisms into their application in a generic way. It is quite possible
to have an application that uses SASL (the specification) without using
Cyrus SASL (the implementation).</p>
<p>The remainder of this document will refer to components of the Cyrus
SASL implementation, though some of these will necessarily have a broader
scope.</p>
<div class="section" id="the-application">
<h2>The Application<a class="headerlink" href="#the-application" title="Permalink to this headline">¶</a></h2>
<p>The application is a client of the SASL library. It can be a client or server
application (or both, in the case of a proxy). It takes care of the
on-the-wire representation of the SASL negotiation, however it performs no
analysis of the exchange itself. It relies on the judgment of the SASL
library whether authentication has occurred or not. The application is also
responsible for determining if the authenticated user may authorize as another
user id (For more details on authentication and authorization identities
and their differences, see <a href=sysadmin.html>Cyrus SASL for System Administrators</a>)</p>
<p>Examples of applications are Cyrus IMAPd, OpenLDAP, Sendmail, Mutt,
sieveshell, cyradm, and many others.</p>
</div>
<div class="section" id="the-sasl-glue-layer">
<h2>The SASL Glue Layer<a class="headerlink" href="#the-sasl-glue-layer" title="Permalink to this headline">¶</a></h2>
<p>The first component of the SASL library is affectionately called the
<code class="docutils literal"><span class="pre">glue</span></code> layer. It takes care of ensuring that the application and
the mechanisms can work together successfully. To this end, it does a
variety of basic tasks:</p>
<ul class="simple">
<li>Loading of any plugins (more on these below)</li>
<li>Ascertaining necessary security properties from the application to aid
in the choice of mechanism (or to limit the available mechanisms)</li>
<li>Listing of available plugins to the application (mostly used on the server
side)</li>
<li>Choosing the best mechanism from a list of available mechanisms
for a particular authentication attempt (client-side)</li>
<li>Routing the authentication (and in the case of a mechanism with a security
layer, encrypted) data packets between the application and the
chosen mechanism.</li>
<li>Providing information about the SASL negotiation back to the application
(authenticated user, requested authorization identity, security strength of
any negotiated security layer, and so on).</li>
</ul>
<p>The Cyrus SASL implementation also provides several other services to
both its plugins and applications. Some of these are simply general utilities,
such as MIME Base-64 encoding and decoding, and random number generation.
Others are more specific to the task of authentication, such as providing
password verification services. Such services are capable of taking
a username and a plaintext password and saying <code class="docutils literal"><span class="pre">yes</span></code> or
<code class="docutils literal"><span class="pre">no</span></code>. Details of available password verification services are
discussed below.</p>
<p>Finally, the glue code allows the mechanisms and applications access to
two special types of plugins, Auxiliary Property or <code class="docutils literal"><span class="pre">auxprop</span></code>
plugins, which provide a simple database interface and can return properties
about the user such as password, home directory, or mail
routing address, and Username Canonicalization, which might provide
site-specific ways to canonicalize a username or perform other tasks.</p>
<p>In the Cyrus SASL Implementation, the glue code is entirely contained
within <code class="docutils literal"><span class="pre">libsasl2.so</span></code> (or <code class="docutils literal"><span class="pre">libsasl2.a</span></code>)</p>
</div>
<div class="section" id="plugins">
<h2>Plugins<a class="headerlink" href="#plugins" title="Permalink to this headline">¶</a></h2>
<div class="section" id="plugins-general">
<h3>Plugins: General<a class="headerlink" href="#plugins-general" title="Permalink to this headline">¶</a></h3>
<p>The Cyrus SASL architechure is very modular, using loadable modules for
things such as the mechanism profiles and the database access done by the
auxillary property plugins. This means that it is easy to limit what
parts are loaded by a given application, and that third parties can write
their own modules to provide services, just by adhering to the API description
in <code class="docutils literal"><span class="pre">saslplug.h</span></code>.</p>
</div>
<div class="section" id="plugins-sasl-mechanisms">
<h3>Plugins: SASL Mechanisms<a class="headerlink" href="#plugins-sasl-mechanisms" title="Permalink to this headline">¶</a></h3>
<p>The simplest types of plugins to understand are those which provide
SASL mechanisms, such as CRAM-MD5, DIGEST-MD5, GSSAPI, PLAIN, SRP, and so on.
These mechanisms take care of both server-side and client-side parts
of the SASL negotiation. If the given mechanism supports a security layer
(that is, makes guarantees about privacy or integrity of data after the
negotiation is complete), the plugin provides that functionality as well.</p>
<p>SASL mechanisms are generally defined by the IETF standards process,
however, some mechanisms are not (For example, NTLM). This is in contrast
to the other types of plugins, which provide database and username
canonicalization services to other plugins and thus aren’t standardized in
their behavior (they are specific to our implementation). Password verifiers
are also an implementation detail (though saslauthd makes use of
standards such as PAM and LDAP to perform that verification)</p>
<p>There are several types of mechanisms, in broad strokes we have:</p>
<dl class="docutils">
<dt>Password Verification Mechanisms</dt>
<dd>For example, PLAIN. These receive a raw password from the remote and then pass it into the glue code for
verification by a password verifier. These require the existence of an
outside security layer to hide the otherwise plaintext password from people
who might be snooping on the wire. These mechanisms do not require that
the server have access to a plaintext (or plaintext-equivalent) version
of the password.</dd>
<dt>Shared Secret Mechanisms</dt>
<dd>For these mechanisms, such as CRAM-MD5, DIGEST-MD5, and SRP, there is a shared secret between the server and client
(e.g. a password). However, in this case the password itself does not travel
on the wire. Instead, the client passes a server a token that proves that
it knows the secret (without actually sending the secret across the wire).
For these mechanisms, the server generally needs a plaintext equivalent of
the secret to be in local storage (not true for SRP).</dd>
<dt>Kerberos Mechanisms</dt>
<dd>Kerberos mechanisms use a trusted
third party to authenticate the client. These mechanisms don’t require
the server to share any secret information with the client, it is all performed
through the Kerberos protocol.</dd>
</dl>
<p>Mechanism plugins are generally contained in a .so file that has a name
similar to the mechanism’s name. Though, in a static compilation they
can also be a part of <code class="docutils literal"><span class="pre">libsasl2.a</span></code></p>
</div>
<div class="section" id="plugins-auxiliary-property">
<h3>Plugins: Auxiliary Property<a class="headerlink" href="#plugins-auxiliary-property" title="Permalink to this headline">¶</a></h3>
<p>Auxiliary Property (or auxprop) plugins provide a database service for the
glue layer (and through it, to the mechanisms and application). Cyrus SASL
ships with two auxprop plugins: SASLdb and SQL. Though they can be use
in much more generic ways, auxprop plugins are mostly only used by
shared secret mechanisms (or by the auxprop password verify) to access the
<code class="docutils literal"><span class="pre">userPassword</span></code> attribute. This provides a plaintext copy of the
password that allows for authentication to take place.</p>
<p>Like the mechanism plugins, these are named similarly to the databases
that they implement an interface for.</p>
</div>
<div class="section" id="plugins-username-canonicalization">
<h3>Plugins: Username Canonicalization<a class="headerlink" href="#plugins-username-canonicalization" title="Permalink to this headline">¶</a></h3>
<p>Username Canonicalization plugins are not widely used, however it may be
useful to use as a hook if your site has specific requirements for how userids
are presented to the applications.</p>
</div>
</div>
<div class="section" id="password-verification-services">
<h2>Password Verification Services<a class="headerlink" href="#password-verification-services" title="Permalink to this headline">¶</a></h2>
<p>As described above, the password verifiers take a username and plaintext
password, and say either <code class="docutils literal"><span class="pre">yes</span></code> or <code class="docutils literal"><span class="pre">no</span></code>. It is not possible
to use them to verify hashes that might be provided by the shared secret
mechanisms.</p>
<p>Password verifiers are selected using the <code class="docutils literal"><span class="pre">pwcheck_method</span></code>
SASL option. There are two main password verifiers provided with Cyrus SASL:</p>
<dl class="docutils">
<dt>auxprop</dt>
<dd>This uses an auxprop plugin to fetch the password and then
compares it with the client-provided copy to make the determination.</dd>
<dt>saslauthd</dt>
<dd>This calls out to the <code class="docutils literal"><span class="pre">saslauthd</span></code> daemon, which
also ships with the distribution. The <code class="docutils literal"><span class="pre">saslauthd</span></code> daemon has a number
of modules of its own, which allow it to do verification of passwords in
a variety of ways, including PAM, LDAP, against a Kerberos database, and so on.
This is how you would want to, for example, use the data contained in
<code class="docutils literal"><span class="pre">/etc/shadow</span></code> to authenticate users.</dd>
</dl>
</div>
</div>
</div>
<footer>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="options.html" class="btn btn-neutral float-right" title="Options" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="upgrading.html" class="btn btn-neutral" title="Upgrading from v1 to v2" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
<hr/>
<div role="contentinfo">
<p>
© Copyright 1993-2016, The Cyrus Team.
</p>
</div>
Built with <a href="http://sphinx-doc.org/">Sphinx</a> 1.6.6 using a modified <a href="https://readthedocs.org">Read the Docs</a> <a href="https://github.com/snide/sphinx_rtd_theme">theme</a>.
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'../',
VERSION:'2.1.27',
COLLAPSE_INDEX:false,
FILE_SUFFIX:'.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="https://cdn.mathjax.org/mathjax/latest/MathJax.js"></script>
<script type="text/javascript" src="../_static/js/theme.js"></script>
<script type="text/javascript">
<!-- jQuery(function () {
SphinxRtdTheme.StickyNav.enable();
}); -->
</script>
</body>
</html>
