1sasl_auxprop(10 July 2001)                          sasl_auxprop(10 July 2001)
2
3
4

NAME

6       sasl_auxprop - How to work with SASL auxiliary properties
7
8

SYNOPSIS

10       #include <sasl/prop.h>
11
12       struct propctx *prop_new(unsigned estimate)
13
14       int prop_dup(struct propctx *src_ctx,
15                    struct propctx *dst_ctx)
16
17       int prop_request(struct propctx *ctx,
18                        const char **names)
19
20       const struct propval *prop_get(struct propctx *ctx)
21
22       int prop_getnames(struct propctx *ctx, const char **names,
23                         struct porpval *vals)
24
25       void prop_clear(struct propctx *ctx, int requests)
26
27       void prop_erase(struct propctx *ctx, const char *name)
28
29       void prop_dispose(struct propctx **ctx)
30
31       int prop_format(struct propctx *ctx, const char *sep, int seplen,
32                       char *outbuf, unsigned outmax, unsigned *outlen)
33
34       int prop_set(struct propctx *ctx, const char *name,
35                    const char *value, int vallen)
36
37       int prop_setvals(struct propctx *ctx, const char *name,
38                        const char **values)
39

DESCRIPTION

41       SASL  auxiliary  properties are used to obtain properties from external
42       sources during the authentication process.  For  example,  a  mechanism
43       might need to query an LDAP server to obtain the authentication secret.
44       The application probably needs other information from  there  as  well,
45       such as home directory or UID.  The auxiliary property interface allows
46       the two to cooperate, and only results in a single  query  against  the
47       LDAP server (or other property sources).
48
49       Property  lookups  take  place  directly  after  user  canonicalization
50       occurs.  Therefore, all requests should be registered with  he  context
51       before  that time.  Note that requests can also be registered using the
52       sasl_auxprop_request(3) function.  Most of the functions listed  below,
53       however,  require  a  property context which can be obtained by calling
54       sasl_auxprop_getctx(3).
55
56

API Description

58       struct propctx *prop_new(unsigned estimate)
59               Create a new property context.  Probably unnecessary for appli‐
60               cation developers to call this at any point.
61
62               estimate is the estimate of storage needed total for requests &
63               responses.  A value of 0 will imply the library default.
64
65
66       int prop_dup(struct propctx *src_ctx, struct propctx *dst_ctx)
67
68               Duplicate a given property context.
69
70
71       int prop_request(struct propctx *ctx, const char **names)
72
73               Add properties to the request list of a given context.
74
75               names is the NULL-terminated array of property names, and  must
76               persist  until  the requests are cleared or the context is dis‐
77               posed of with a call to prop_dispose.
78
79
80       const struct propval *prop_get(struct propctx *ctx)
81
82               Returns a NULL-terminated array  of  struct  propval  from  the
83               given context.
84
85
86       int prop_getnames(struct propctx *ctx, const char **names,
87                                 struct porpval *vals)
88
89               Fill in a (provided) array of struct propval based on a list of
90               property names.  This implies that the vals array is  at  least
91               as  long  as  the names array. The values that are filled in by
92               this call persist until next call to prop_request,  prop_clear,
93               or prop_dispose on context.  If a name specified here was never
94               requested, that its associated values  entry  will  be  set  to
95               NULL.
96
97               Returns  number  of  matching  properties that were found, or a
98               SASL error code.
99
100
101       void prop_clear(struct propctx *ctx, int requests)
102
103               Clear values and optionally requests from a property context.
104
105               requests is 1 if the requests should be cleared, 0 otherwise.
106
107
108       void prop_erase(struct propctx *ctx, const char *name)
109
110               Securely erase the value of a property.
111
112               name is the name of the property to erase.
113
114
115       void prop_dispose(struct propctx **ctx)
116
117               Disposes of a property context and NULLifys the pointer.
118
119
120       int prop_format(struct propctx *ctx, const char *sep, int seplen,
121                               char   *outbuf,   unsigned   outmax,   unsigned
122               *outlen)
123
124               Format  the  requested  property names into a string.  This not
125               intended for use by the application (only by auxprop plugins).
126
127               sep Is the separator to use for the string
128
129               outbuf Is the caller-allocated buffer of length outmax that the
130               resulting string will be placed in (including NUL terminator).
131
132               outlen  if  non-NULL,  will contain the length of the resulting
133               string (excluding NUL terminator).
134
135
136       int prop_set(struct propctx *ctx, const char *name, const char *value,
137                            int vallen)
138
139               Adds a property value to the context.  This is intended for use
140               by auxprop plugins only.
141
142               name  is  the name of the property to receive the new value, or
143               NULL, which implies that the value will be added  to  the  same
144               property as the last call to either prop_set or prop_setvals.
145
146               value is a value for the property of length vallen
147
148
149       int  prop_setvals(struct  propctx  *ctx,  const  char *name, const char
150       **values)
151
152               Adds multiple values to a single property.   This  is  intended
153               for use by auxprop plugins only.
154
155               name has the same meaning as in prop_set
156
157               values  are  a  NULL-terminated array of values to be added the
158               property.
159
160

RETURN VALUE

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

CONFORMING TO

168       RFC 2222
169
170

SEE ALSO

172       sasl(3),     sasl_errors(3),     sasl_auxprop_request(3),     sasl_aux‐
173       prop_getctx(3)
174
175
176
177SASL man pages                       SASL           sasl_auxprop(10 July 2001)
Impressum