<html><head> <title>Building and Using Cyrus SASL on Mac OS X</title> </head> <body> <h1>Cyrus SASL on Mac OS X</h1><p> The Cyrus SASL distribution now supports Mac OS X, including applications written to Apple's Carbon and Cocoa interfaces, as well as the standard Unix-like API. It is composed of the following components:<p> <ul> <li>A port of the Unix SASL library, which lives in <tt>/usr/local/lib/libsasl.7.1.10.dylib</tt> (or something like that) and with plugins in <tt>/usr/lib/sasl</tt> (which should be a symlink to <tt>/usr/local/lib/sasl</tt>). <li>A framework which lives in <tt>/Library/Frameworks/SASL.framework</tt>, and allows the use of the <tt>-framework</tt> option to Apple's <tt>ld</tt>, or linking with the framework in Project Builder. This framework is in fact a wrapper for a symlink to <tt>/usr/local/lib/libsasl.dylib</tt> with the necessary information to recognize it as a framework. This is what we expect many Cocoa and Carbon Mach-O applications will want to use. <li>A CFM glue library (<tt>/Library/CFMSupport/SASLGlueCFM</tt>) which can be linked in by Carbon CFM applications, that uses CFBundle to bind the framework and thus load the Unix-level library. It automatically loads the important functions at <tt>sasl_client_init</tt> or <tt>sasl_server_init</tt> time; it also automatically makes sure memory allocation works if you're using the metrowerks malloc; if you're not, <tt>sasl_set_alloc</tt> works as usual. <li>A Carbon port of the existing CFM library for Mac OS 9. Note that this could probably be modified fairly easily to work on OS X, but there's not much point. The CFM glue layer to the Unix library supports many more functions, including the entire server API; also, the Unix implementation is mostly independent of Kerberos implementation, while the Mac OS 9 Carbon port specifically requires MIT Kerberos for Macintosh 3.5 or later. The Mac OS 9 code implements only the client API, but this is mostly what is wanted from SASL on OS 9 anyway. </ul><p> If you are building a Carbon CFM application and intend it to run on both OS 9 and OS X, you should link against the OS 9 Carbon SASL library, since it exports fewer APIs (client side only, specifically) than the OS X CFM glue. Your application should work seamlessly with both libraries if you do this, despite the different implementations underneath.<p> If you need a Carbon CFM application to support server-side SASL functionality, you need to link against the <tt>SASLGlueCFM</tt> library, but be aware that your application will not run on OS 9.<p> <h2>Compiling and Using the Unix library</h2> The Unix library is mostly ready to build on Mac OS X, but it does depend on the <tt>dlcompat</tt> package in order to load its plugins. <tt>dlcompat-20010505</tt> is the latest version and is known to work with SASL; it is provided with the distribution in a tarball. You should <tt>make</tt> and <tt>make install</tt> the <tt>dlcompat</tt> library (which probably goes into <tt>/usr/local/lib/libdl.dylib</tt>) before attempting to <tt>./configure</tt> the SASL distribution itself. SASL will then pretend it's a real Unix <tt>libdl</tt>, and link against it.<p> If you are using MIT Kerberos for Macintosh 4.0, which is fully supported by the SASL library, you should <tt>./configure</tt> with the added option <tt>--enable-krb4=/usr</tt> so that it finds the correct location for the header files. KfM will be automatically detected by the configure script, and the correct libraries linked in.<p> You must be root to make install, since <tt>/usr/local</tt> is only modifiable by root. This is a mistake on Apple's part; <tt>/usr/local</tt> is intended for local installations of software, and so is more the equivalent of <tt>/Applications</tt>, <tt>/Library</tt>, etc. than of <tt>/System</tt> (and <tt>/usr</tt>). You need not enable the root account using NetInfo; the recommended (but underdocumented) method is to use <tt>sudo -s</tt> from the Terminal window when you are logged into an administrator's account, and enter the password for that account. When building on Mac OS X, <tt>make install</tt> will automatically add the framework to <tt>/Library/Frameworks</tt>.<p> This does not build the CFM glue library. Building the CFM glue library requires Metrowerks CodeWarrior Pro 6 or later (tested with 6), and the files necessary to build it are in the <tt>mac_only_files.sit.hqx</tt> archive, in the <tt>osx_cfm_glue</tt> folder.<p> <h2>Changes to the Unix library to make it work on OS X</h2><p> This is provided for documentation purposes only. The build system will automatically take care of all of these issues when building on Darwin or Mac OS X.<p> <ul> <li>The random code supports the preferred way to generate random numbers in Darwin. <li>Symbols which are dlopened have an underscore prefixed. <li>Plugins are linked with the <tt>-module</tt> option to <tt>libtool</tt>, which causes the <tt>-bundle</tt> option to be supplied to Apple's <tt>ld</tt>. <li>When building on Darwin or OS X, the MD5 symbols are renamed to avoid library conflicts. This allows proper compilations against Heimdal and MIT's unix kerberos distribution, and prevents crashes when linked against MIT Kerberos for Macintosh (which also duplicates the symbols, but in a different way). <li>MIT Kerberos for Macintosh 4.0 is fully supported. </ul><p> <h2>Changes to the Mac OS 9 projects to support Carbon</h2><p> <b><i>Please read these notes before you attempt to build SASL for OS 9 Carbon!</i></b> <ul> <li>Many of the important projects (for <tt>libdes</tt>, <tt>libsasl</tt>, <tt>build_plugins</tt>, and the sample client <tt>sc_shlb</tt>) have Carbon versions. <li>There is a new folder in <tt>CommonKClient</tt> called <tt>mac_kclient3</tt> which contains code compatible with MIT's new <a href="http://web.mit.edu/macdev/Development/MITKerberos/MITKerberosLib/KClient/Documentation/index.html">KClient 3.0</a> API. This folder must be in your CodeWarrior access paths, the old <tt>mac_kclient</tt> folder must not, and it must precede the project's main folder. <li>The kerberos4 plugin uses this new code. The kerberos4 plugin also statically links the Carbon <tt>libdes</tt>, and no other part of Carbon SASL uses <tt>libdes</tt> directly. <i>Your application should <b>not</b> link against</i> <tt>libdes.shlb</tt> <i>under Carbon!</i> (It causes problems due to DES symbols also existing in the MIT Kerberos library, which loads first.) <li>To build the projects, you should have the MIT Kerberos for Macintosh 3.5 installation disk images mounted, since the access paths include the absolute paths to the library directories from that image. It's easier than you having to find the paths yourself, and smaller than having to distribute the libraries with SASL. </ul><p>
