doc/appconvert.html

   1 <HTML>
   2 <HEAD>
   3 <TITLE>Converting Applications from SASLv1 to SASLv2</TITLE>
   4 <BODY>
   5 <H1>Application Conversion Guide for SASLv2</H1>
   6
   7 <p>This documents our conversion experience with Cyrus IMAPd, an application
   8 that uses almost every part of SASL, so it should give a good idea what caveats
   9 need to be looked for when one is converting an application which uses SASLv1
  10 to use SASLv2.</P>
  11
  12 <P>The major changes in the SASLv2 API have to do with memory management.
  13 That is, the rule "If you allocate it, you free it" is now enforced.  That
  14 means that if the application allocates something (for example, an interaction
  15 or callback response), it must free it.  Likewise, the application does
  16 NOT free anything handed to it by the SASL library, such as responses
  17 given by sasl_client_step or sasl_decode.</P>
  18
  19 <UL>
  20 <LI>Tips for both clients and servers:<P>
  21 <UL>
  22 <LI>Change configure scripts to search for libsasl2 and include files
  23 prefixed with sasl/ (sasl/sasl.h, sasl/saslutil.h, etc)</LI>
  24 <LI><tt>sasl_decode64</tt> now takes an
  25 additional parameter that is the size of the buffer it is passed.</LI>
  26 <LI>External authentication properties are no longer handled by a
  27 <tt>sasl_external_properties_t</tt>.  Instead you make 2 separate calls to
  28 <tt>sasl_setprop.</tt>
  29 One with SASL_SSF_EXTERNAL to tell the SASL library what SSF is being
  30 provided by the external layer. The other sets SASL_AUTH_EXTERNAL to indicate
  31 the authentication name.</LI>
  32 <LI>
  33 <tt>sasl_getprop</tt> now returns its value in a <tt>const void **</tt>
  34 </LI>
  35 <LI><tt>sasl_encode</tt> and <tt>sasl_decode</tt> now return a constant output buffer, which
  36 you do not need to free (it is only valid until the next call for this sasl_
  37 conn_t, however)</LI>
  38 <LI>The SASL_IP_REMOTE and SASL_IP_LOCAL properties are now SASL_IPLOCALPORT
  39 and SASL_IPREMOTEPORT and take strings instead of sockaddrs. These strings
  40 may also be passed to the sasl_[client/server]_new functions.  They
  41 are in one of the following formats:
  42 <UL>
  43 <LI>a.b.c.d;p (IPv4, with port)</LI>
  44 <LI>e:f:g:h:i:j:k:l;p (IPv6, with port)</LI>
  45 <LI>e:j:k:l;p (IPv6, abbreviated zero fields, with port)</LI>
  46 </UL></LI>
  47 <li>Error handling and reporting is different. All of the functions that used
  48 to return a "reply" string no longer do.  Now you should (always) check
  49 <tt>sasl_errdetail</tt>.  Callbacks MUST likewise use <tt>sasl_seterror</tt>
  50 instead of setting their (now nonexistent) reply parameter.</li>
  51 <li>Be very careful about your handling of maxoutbuf.  If you claim that
  52 you can only read 4096 bytes at a time, be sure to only pass at most
  53 that much at a time to the SASL library!</li>
  54 </UL></LI>
  55
  56 <LI>Tips for clients:</LI>
  57 <OL>
  58 <LI>In <tt>sasl_client_new</tt> you can now pass ip address strings as
  59 parameters 3 and 4 instead of calling setprop later on sockaddr's.
  60 This is preferred but not required (not passing them by either method disables
  61 mechs which require IP address information).   You might find the iptostring()
  62 function in utils/smtptest.c to be useful for this.  If the protocol supports
  63 the server sending data on success you should pass SASL_SUCCESS_DATA as a
  64 flag.</LI>
  65 <LI><tt>sasl_client_start</tt> loses the 3rd "secret" parameter.
  66 Also, NULL clientout and clientoutlen indicates that the protocol does not
  67 support client-send-first.  A NULL return value indicates that there is no
  68 first client send. (as opposed to an empty string, which indicates that
  69 the first client send is the empty string).</LI>
  70 <LI>
  71 Both <tt>sasl_client_start</tt> and <tt>sasl_client_step</tt> now take
  72 const clientout parameters that you are no longer responsible for freeing
  73 (it is only valid until the next call for this <tt>sasl_conn_t</tt>, however)
  74 </LI>
  75 <LI>When interactions and callbacks happen you are responsible for freeing
  76 the results.</LI>
  77 </OL></LI>
  78
  79 <LI>Tips for Servers:</LI>
  80 <OL>
  81 <LI>SASL_SECURITY_LAYER flag no longer exists, whether or not to use a
  82 security layer is solely determined by the security properties information,
  83 namely, the <tt>maxbufsize</tt> member of the
  84 <tt>sasl_security_properties_t</tt></LI>
  85 <LI><tt>sasl_server_new</tt> now can take ip address strings.</li>
  86 <LI><tt>sasl_checkpass</tt> no longer has a "reply" parameter.  There
  87 are also considerably fewer possible values for the pwcheck_method
  88 option (now only auxprop, saslauthd, authdaemond, and pwcheck).</li>
  89 <li><tt>sasl_server_start</tt> / <tt>sasl_server_step</tt> have same
  90 output parameter deal as their equivalents on the client side</li>
  91 <li><tt>sasl_listmech</tt> has a constant output parameter</li>
  92 <li>If you used to canonicalize the username in a SASL_CB_PROXY_POLICY
  93 callback you should now separate the functionality of authorization and
  94 canonicalization.  That is, only do authorization in SASL_CB_PROXY_POLICY,
  95 and do canonicalization in the SASL_CB_CANON_USER callback</li>
  96 </OL></LI>
  97
  98 </UL>
  99 </BODY>
 100 </HTML>