sasl_auxprop(10 July 2001)             sasl_auxprop(10 July 2001)



NAME
       sasl_auxprop - How to work with SASL auxiliary properties


SYNOPSIS
       #include 

       struct propctx *prop_new(unsigned estimate)

       int prop_dup(struct propctx *src_ctx,
                    struct propctx *dst_ctx)

       int prop_request(struct propctx *ctx,
                        const char **names)

       const struct propval *prop_get(struct propctx *ctx)

       int prop_getnames(struct propctx *ctx, const char **names,
                         struct porpval *vals)

       void prop_clear(struct propctx *ctx, int requests)

       void prop_erase(struct propctx *ctx, const char *name)

       void prop_dispose(struct propctx **ctx)

       int prop_format(struct propctx *ctx, const char *sep, int seplen,
                       char *outbuf, unsigned outmax, unsigned *outlen)

       int prop_set(struct propctx *ctx, const char *name,
                    const char *value, int vallen)

       int prop_setvals(struct propctx *ctx, const char *name,
                        const char **values)

DESCRIPTION
       SASL  auxiliary  properties  are used to obtain properties
       from external sources during the  authentication  process.
       For  example,  a  mechanism  might  need  to query an LDAP
       server to obtain the authentication secret.  The  applica-
       tion  probably needs other information from there as well,
       such as home directory or  UID.   The  auxiliary  property
       interface allows the two to cooperate, and only results in
       a single query against the LDAP server (or other  property
       sources).

       Property lookups take place directly after user canonical-
       ization occurs.  Therefore, all requests should be  regis-
       tered  with  he  context  before  that  time.   Note  that
       requests  can  also  be  registered  using  the  sasl_aux-
       prop_request(3)  function.   Most  of the functions listed
       below, however, require a property context  which  can  be
       obtained by calling sasl_auxprop_getctx(3).


API Description
       struct propctx *prop_new(unsigned estimate)
               Create  a new property context.  Probably unneces-
               sary for application developers to  call  this  at
               any point.

               estimate  is  the estimate of storage needed total
               for requests & responses.  A value of 0 will imply
               the library default.


       int   prop_dup(struct  propctx  *src_ctx,  struct  propctx
       *dst_ctx)

               Duplicate a given property context.


       int prop_request(struct propctx *ctx, const char **names)

               Add properties to the request list of a given con-
               text.

               names is the  NULL-terminated  array  of  property
               names,  and  must  persist  until the requests are
               cleared or the context is disposed of with a  call
               to prop_dispose.


       const struct propval *prop_get(struct propctx *ctx)

               Returns  a NULL-terminated array of struct propval
               from the given context.


       int prop_getnames(struct propctx *ctx, const char **names,
                                 struct porpval *vals)

               Fill in a (provided) array of struct propval based
               on  a  list  of property names.  This implies that
               the vals array is at least as long  as  the  names
               array.  The values that are filled in by this call
               persist   until   next   call   to   prop_request,
               prop_clear, or prop_dispose on context.  If a name
               specified here was never requested, that its asso-
               ciated values entry will be set to NULL.

               Returns  number  of  matching properties that were
               found, or a SASL error code.


       void prop_clear(struct propctx *ctx, int requests)

               Clear values and optionally requests from a  prop-
               erty context.

               requests is 1 if the requests should be cleared, 0
               otherwise.


       void prop_erase(struct propctx *ctx, const char *name)

               Securely erase the value of a property.

               name is the name of the property to erase.


       void prop_dispose(struct propctx **ctx)

               Disposes of a property context  and  NULLifys  the
               pointer.


       int  prop_format(struct propctx *ctx, const char *sep, int
       seplen,
                               char   *outbuf,  unsigned  outmax,
               unsigned *outlen)

               Format the requested property names into a string.
               This not intended for use by the application (only
               by auxprop plugins).

               sep Is the separator to use for the string

               outbuf Is the caller-allocated  buffer  of  length
               outmax that the resulting string will be placed in
               (including NUL terminator).

               outlen if non-NULL, will contain the length of the
               resulting string (excluding NUL terminator).


       int  prop_set(struct propctx *ctx, const char *name, const
       char *value,
                            int vallen)

               Adds  a  property  value  to the context.  This is
               intended for use by auxprop plugins only.

               name is the name of the property  to  receive  the
               new  value,  or NULL, which implies that the value
               will be added to the same  property  as  the  last
               call to either prop_set or prop_setvals.

               value is a value for the property of length vallen


       int prop_setvals(struct propctx *ctx,  const  char  *name,
       const char **values)

               Adds multiple values to a single  property.   This
               is intended for use by auxprop plugins only.

               name has the same meaning as in prop_set

               values are a NULL-terminated array of values to be
               added the property.


RETURN VALUE
       The property functions that  return  an  int  return  SASL
       error  codes.   See  sasl_errors(3).   Those  that  return
       pointers will return a valid pointer on success,  or  NULL
       on any error.


CONFORMING TO
       RFC 2222


SEE ALSO
       sasl(3),      sasl_errors(3),     sasl_auxprop_request(3),
       sasl_auxprop_getctx(3)



SASL man pages                 SASL    sasl_auxprop(10 July 2001)