doc/macosx.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4   <title>Building and Using Cyrus SASL on Mac OS X</title>
   5 <!-- $Id: macosx.html,v 1.6 2003/12/12 00:43:03 rbraun Exp $ -->
   6 </head>
   7 <body>
   8 <h1>Cyrus SASL v2 on Mac OS X (and 9)</h1>
   9 <p>The Cyrus SASL v2 distribution now supports Mac OS X, including
  10 applications written to Apple's Carbon and Cocoa interfaces, as well
  11 as the standard Unix-like API. It includes the following
  12 components:</p>
  13 <ul>
  14   <li>A port of the Unix SASL library, which lives in <tt>/usr/local/lib/libsasl2.dylib</tt>
  15 (or something like that) and
  16 with plugins in <tt>/usr/lib/sasl</tt> (which should be a symlink to <tt>/usr/local/lib/sasl</tt>).
  17   </li>
  18   <li>A framework which lives in
  19 <tt>/Library/Frameworks/SASL2.framework</tt>, and allows the use of the
  20 <tt>-framework</tt> option to Apple's <tt>ld</tt>, or linking with the
  21 framework in Project Builder. This framework is in fact a wrapper for a
  22 symlink to <tt>/usr/local/lib/libsasl2.dylib</tt> with the necessary
  23 information to recognize it as a framework. This is what we expect many
  24 Cocoa and Carbon Mach-O applications will want to use, and the framework
  25 is required for CFBundle to work, which is used by the CFM glue library.
  26 </li>
  27   <li>A CFM glue library (<tt>/Library/CFMSupport/SASL2GlueCFM</tt>) which
  28 can be linked in by Carbon CFM applications, that uses CFBundle to bind
  29 the framework and thus load the Unix-level library. It automatically loads
  30 the important functions at <tt>sasl_client_init</tt> or
  31 <tt>sasl_server_init</tt> time; it also automatically makes sure memory
  32 allocation works if you're using the metrowerks malloc; if you're not,
  33 <tt>sasl_set_alloc</tt> works as usual. </li>
  34   <li>A Carbon port of the existing CFM library for Mac OS 9. Note that
  35 this could probably be modified fairly easily to work on OS X, but
  36 there's not much point. The CFM glue layer to the Unix library
  37 supports many more functions, including the entire server API; also,
  38 the Unix implementation is mostly independent of Kerberos
  39 implementation, while the Mac OS 9 Carbon port specifically requires
  40 MIT Kerberos for Macintosh 3.5 or later in order to get Kerberos
  41 support. The Mac OS 9 code implements only the client API, but this is
  42 mostly what is wanted from SASL on OS 9 anyway. </li>
  43 </ul>
  44 <p>If you are building a Carbon CFM application and intend it to run on
  45 both OS 9 and OS X, you should link against the OS 9 Carbon SASL
  46 library, since it exports fewer APIs (client side only, specifically)
  47 than the OS X CFM glue. Your application should work seamlessly with
  48 both libraries if you do this, despite the different implementations
  49 underneath.</p>
  50 <p>If you need a Carbon CFM application to support server-side SASL
  51 functionality, you need to link against the <tt>SASL2GlueCFM</tt>
  52 library, but be aware that your application will not run on OS 9.</p>
  53 <h2>Compiling and Using the Unix library</h2>
  54
  55 The Unix library is mostly ready to build on Mac OS X, but it does depend
  56 on the <tt>dlcompat</tt> package in order to load its plugins.
  57 <tt>dlcompat-20010505</tt> is a relatively simple version known to work
  58 with SASL; it is provided with the distribution in a tarball. You should
  59 <tt>make</tt> and <tt>make install</tt> the <tt>dlcompat</tt> library
  60 (which probably goes into <tt>/usr/local/lib/libdl.dylib</tt>) before
  61 attempting to <tt>./configure</tt> the SASL distribution itself. SASL will
  62 then pretend it's a real Unix <tt>libdl</tt>, and link against it.
  63
  64 <p>Since there are, at this point, newer and far more complex versions of
  65 dlcompat, you may prefer to use those instead if other software requires
  66 their functionality. The dlcompat homepage is located <a
  67 href="http://www.opendarwin.org/projects/dlcompat/">on the OpenDarwin
  68 site.</a> Many users may want to install the <tt>/sw</tt> tree from <a
  69 href="http://fink.sourceforge.net/">the Fink project</a> to get this, as
  70 well as possibly newer autotools and other software.<br> </p>
  71
  72 <p>As of version 2.1.16, SASL uses and requires a recent version of GNU
  73 autotools (autoconf, automake, and libtool) to build its configuration scripts.
  74 If you are building from CVS, you will need to have the autotools installed
  75 on your system. The version included with all releases of the developer tools
  76 for OS X 10.2.x is too old for this; if you aren't using OS X 10.3 or later,
  77 you should upgrade to more recent patchlevels of these tools. The easiest way
  78 to do this is to <a href="http://fink.sourceforge.net/">install the Fink
  79 environment</a> and then <tt>apt-get
  80 install autoconf2.5 automake1.7 libtool14</tt>.<br>
  81 </p>
  82 <p>Recent versions of SASL ship with Kerberos v4 disabled by default.
  83 If you need Kerberos v4 for some reason, and you are using MIT Kerberos
  84 for Macintosh 4.0 or later, you should <tt>./configure</tt> with
  85 the added options <tt>"--enable-krb4=/usr --without-openssl
  86 --disable-digest"</tt> so that it finds the
  87 correct location for the header files, and does not use OpenSSL or
  88 build anything that depends on it (such as the digest-md5 plugin),
  89 since OpenSSL provides its own DES routines which do not work with
  90 Kerberos v4. <i>Please read the "Known Problems" section at the end of
  91 this
  92 document for more information on this issue.<br>
  93 </i></p>
  94 <p>You must be root to make install, since <tt>/usr/local</tt> is only
  95 modifiable by root. You need not enable the root account using
  96 NetInfo; the recommended (but underdocumented) method is to use
  97 <tt>sudo -s</tt> from the Terminal window when you are logged into an
  98 administrator's account, and enter the password for that account. When
  99 building on Mac OS X, <tt>make install</tt> will automatically add the
 100 framework to <tt>/Library/Frameworks</tt>.</p>
 101 <p>This does not build the CFM glue library. Building the CFM glue
 102 library requires Metrowerks CodeWarrior Pro 6 or later (tested with
 103 6), and the files necessary to build it are in the
 104 <tt>mac/osx_cfm_glue</tt> folder.</p>
 105 <h2>Changes to the Unix library to make it work on OS X</h2>
 106 <p>This is provided for reference purposes only. The build system will
 107 automatically take care of all of these issues when building on Darwin
 108 or Mac OS X.</p>
 109 <ul>
 110   <li>The random code supports the preferred way to generate random
 111 numbers in Darwin. (In SASL v2, it does this on all unix-like
 112 platforms that lack jrand48). <i>Note that Mac OS X "Jaguar", version
 113 10.2,
 114 now has the standard jrand48 function, and that SASL will use this
 115 instead
 116 of the previous workaround.</i> </li>
 117   <li>Symbols which are dlopened have an underscore prefixed. (This
 118 behavior is detected by configure in SASL v2.) </li>
 119   <li>Plugins are linked with the <tt>-module</tt> option to <tt>libtool</tt>,
 120 which causes the <tt>-bundle</tt> option to be
 121 supplied to Apple's <tt>ld</tt>. (This is done on all platforms in
 122 SASL v2.) </li>
 123   <li>The MD5 symbols are renamed to avoid library conflicts. This
 124 allows proper compilations against Heimdal and MIT's unix kerberos
 125 distribution, and prevents crashes when linked against MIT Kerberos
 126 for Macintosh (which also duplicates the symbols, but in a different
 127 way). Note that the MD5 symbols have local names on all platforms with
 128 SASL v2; this was only different in SASL v1. </li>
 129   <li>MIT Kerberos for Macintosh 4.0 and later are fully supported. This
 130 was accomplished by using <tt>krb_get_err_text</tt> if available and
 131 checking for additional names for the krb4 libraries. </li> </ul>
 132 <h2>Changes to the Mac OS 9 projects to support Carbon</h2>
 133 <p><b><i>Please read these notes before you attempt to build SASL for OS 9
 134 Carbon!</i></b> </p> <ul>
 135   <li><b>Important!</b> You must make sure that all files have their
 136 correct HFS filetype before starting to build this code! In
 137 particular, all source and text files must be of type <tt>'TEXT'</tt>,
 138 which is not the default if you use the Mac OS X cvs client to check
 139 out the projects. If you run into this problem, you may want to use a
 140 utility such as FileTyper to recursively change the type on all
 141 files. CodeWarrior is less picky about the projects' filetypes, but
 142 setting them to filetype <tt>'MMPr'</tt>, creator code <tt>'CWIE'</tt>
 143 may be helpful in opening the projects from the Finder. Users on Mac OS
 144 X familiar with the Unix <tt>find</tt>
 145 command should be able to rig <tt>/Developer/Tools/SetFile</tt>
 146 to do this job as well. </li>
 147   <li>Many of the important projects (for <tt>libdes</tt>, <tt>libsasl</tt>,
 148     <tt>build_plugins</tt>, and the sample client <tt>sc_shlb</tt>)
 149 have Carbon versions. </li>
 150   <li>Plugins are loaded from a <tt>Carbon</tt> subfolder of the <tt>SASL
 151 v2</tt> folder in the Extensions folder. Plugins directly
 152 in
 153 the <tt>SASL v2</tt> folder are considered to be for the Classic
 154 libraries. </li>
 155   <li>Note that when using the <tt>build_plugins</tt> project, you must
 156 generate the plugin init files using the <tt>makeinit.sh</tt> script in
 157 the <tt>plugins</tt> directory. The easiest way to do this is to run the
 158 script from a Unix shell, such as Mac OS X. You must then fix the
 159 filetypes of the generated source files (see above). </li>
 160   <li>There is a new folder in <tt>CommonKClient</tt> called <tt>mac_kclient3</tt>
 161 which contains code compatible with MIT's new <a
 162  href="http://web.mit.edu/macdev/Development/MITKerberos/MITKerberosLib/KClient/Documentation/index.html">KClient
 163 3.0</a> API. This folder must be in your CodeWarrior access paths, the
 164 old <tt>mac_kclient</tt> folder must not, and it must precede the
 165 project's main folder. </li>
 166   <li>The kerberos4 plugin uses this new code. The kerberos4 plugin
 167 also
 168 statically links the Carbon <tt>libdes</tt>, and no other part of
 169 Carbon SASL uses <tt>libdes</tt> directly. <i>Your application should
 170     <b>not</b> link against</i> <tt>libdes.shlb</tt> <i>under Carbon!</i>
 171 (It causes problems due to DES symbols also existing in the MIT
 172 Kerberos library, which loads first.) </li>
 173   <li>To build the projects, you should have the MIT Kerberos for
 174 Macintosh 3.5 installation disk images mounted, since the access paths
 175 include the absolute paths to the library directories from that
 176 image. It's easier than you having to find the paths yourself, and
 177 smaller than having to distribute the libraries with SASL. </li>
 178 </ul>
 179 <h2>Known Problems</h2>
 180 <ul>
 181   <li>The Kerberos v4 headers bundled with Mac OS X (and Kerberos for
 182 Macintosh) are not compatible with OS X's OpenSSL headers. (Kerberos v4
 183 support is disabled by default.) If you actually need krb4 support, the
 184 easiest solution is to build without using OpenSSL's
 185 <tt>libcrypto</tt>. To do this, specify the <tt>--without-openssl</tt>
 186 option to <tt>configure</tt>. As of version 2.1.18, this automatically
 187 disables using <tt>libcrypto</tt> for DES as well. You will probably
 188 also need to specify <tt>--disable-digest</tt> since the digestmd5 plugin
 189 does not build against Kerberos v4's DES headers or library. Note that
 190 this disables several features (digestmd5, NTLM, OTP) which require
 191 OpenSSL. If both Kerberos v4 and functionality that requires OpenSSL are
 192 needed, it is probably possible to build the Kerberos v4 plugin against
 193 the correct K4 DES libraries, and everything else against OpenSSL;
 194 however, we do not support that configuration.<br>
 195   </li>
 196   <li>Versions of Cyrus SASL prior to 2.1.14 with support for Carbon
 197 CFM applications on Mac OS X have a known bug involving the CFM glue
 198 code (in <tt>mac/osx_cfm_glue</tt>). If <tt>sasl_done</tt> is called
 199 to unload the SASL library, and then one of the initialization
 200 functions (such as <tt>sasl_client_init</tt>) is called to
 201 reinitialize it from the same process, the application will crash. A
 202 fix for one obvious cause of this problem is included in 2.1.14;
 203 however, as of this writing, it has not been tested. It is possible
 204 that other bugs in Cyrus SASL, or deficiencies in Apple's libraries,
 205 will make this fix insufficient to resolve this issue. </li>
 206 </ul>
 207 </body>
 208 </html>