1SASL_AUXPROP(3) Cyrus SASL SASL_AUXPROP(3)
2
6 sasl_auxprop - Cyrus SASL documentation
7
9 #include <sasl/prop.h>
10 struct propctx *prop_new(unsigned estimate)
12 int prop_dup(struct propctx *src_ctx,
14 struct propctx *dst_ctx)
15 int prop_request(struct propctx *ctx,
17 const char **names)
18 const struct propval *prop_get(struct propctx *ctx)
20 int prop_getnames(struct propctx *ctx, const char **names,
22 struct propval *vals)
23 void prop_clear(struct propctx *ctx, int requests)
25 void prop_erase(struct propctx *ctx, const char *name)
27 void prop_dispose(struct propctx **ctx)
29 int prop_format(struct propctx *ctx, const char *sep, int seplen,
31 char *outbuf, unsigned outmax, unsigned *outlen)
32 int prop_set(struct propctx *ctx, const char *name,
34 const char *value, int vallen)
35 int prop_setvals(struct propctx *ctx, const char *name,
37 const char **values)
38
40 SASL auxiliary properties are used to obtain properties from external
41 sources during the authentication process. For example, a mechanism
42 might need to query an LDAP server to obtain the authentication secret.
43 The application probably needs other information from there as well,
44 such as home directory or UID. The auxiliary property interface
45 allows the two to cooperate, and only results in a single query against
46 the LDAP server (or other property sources).
47 Property lookups take place directly after user canonicalization
49 occurs. Therefore, all requests should be registered with the context
50 before that time. Note that requests can also be registered using the
51 sasl_auxprop_request(3) function. Most of the functions listed
52 below, however, require a property context which can be obtained by
53 calling sasl_auxprop_getctx(3).
54
56 struct propctx *prop_new(unsigned estimate)
57 Create a new property context. Probably unnecessary for appli‐
58 cation developers to call this at any point.
59 Parameters
61 · estimate – is the estimate of storage needed in total
63 for requests & responses. A value of 0 implies the
64 library default.
65 Returns
67 a new property context: propctx
68 int prop_dup(struct propctx *src_ctx, struct propctx *dst_ctx)
70 Duplicate a given property context.
71 Parameters
73 · src_ctx (propctx) – Property context to copy.
75 · dst_ctx (propctx) – Destination context to copy into.
77 Returns
79 SASL error code.
80 int prop_request(struct propctx *ctx, const char **names)
82 Add properties to the request list of a given context.
83 Parameters
85 · ctx (propctx) – The property context to add add the
87 request list to.
88 · names – is the NULL-terminated array of property names,
90 and must persist until the requests are cleared or the
91 context is disposed of with a call to prop_dispose().
92 Returns
94 SASL error code
95 const struct propval *prop_get(struct propctx *ctx)
97 Fetch out the property values from a context.
98 Parameters
100 · ctx (propctx) – The property context to fetch from.
102 Returns
104 a NULL-terminated array of property values from the given
105 context.
106 int prop_getnames(struct propctx *ctx, const char **names, struct
108 propval *vals)
109 Fill in a (provided) array of property values based on a list of
110 property names. This implies that the vals array is at least as
111 long as the names array. The values that are filled in by this
112 call persist until next call to prop_request(),
113 prop_clear(), or prop_dispose() on context. If a name specified
114 here was never requested, then its associated values entry will
115 be set to NULL.
116 Parameters
118 · ctx (propctx) – The property context to fill in.
120 Returns
122 number of matching properties that were found, or a SASL
123 error code.
124 void prop_clear(struct propctx *ctx, int requests)
126 Clear values and (optionally) requests from a property context.
127 Parameters
129 · ctx (propctx) – The property context to clear.
131 · requests – set to 1 if the requests should be cleared,
133 0 otherwise.
134 void prop_erase(struct propctx *ctx, const char *name)
136 Securely erase the value of a property from a context.
137 Parameters
139 · ctx (propctx) – The property context to find the prop‐
141 erty in.
142 · name – is the name of the property to erase.
144 void prop_dispose(struct propctx **ctx)
146 Disposes of a property context and NULLifys the pointer.
147 Parameters
149 · ctx (propctx) – The property context to clear.
151 int prop_format(struct propctx *ctx, const char *sep, int seplen,
153 char *outbuf, unsigned outmax, unsigned *outlen)
154 Format the requested property names into a string. This not
155 intended for use by the application (only by auxprop plugins).
156 Parameters
158 · ctx (propctx) – The property context to extract values
160 from.
161 · sep – the separator to use for the string
163 · outbuf – destination string. Caller must allocate the
165 buffer of length outmax (including NUL terminator).
166 · outlen – if non-NULL, will contain the length of the
168 resulting string (excluding NUL terminator).
169 Returns
171 SASL error code.
172 int prop_set(struct propctx *ctx, const char *name, const char *value,
174 int vallen)
175 Adds a property value to the context. This is intended for use
176 by auxprop plugins only.
177 Parameters
179 · ctx (propctx) – The property context to add a value to.
181 · name – the name of the property to receive the new
183 value, or NULL, which implies that the value will be
184 added to the same property as the last call to either
185 prop_set() or prop_setvals().
186 · value – the new value (of length vallen)
188 · vallen – the length of the string value.
190 Returns
192 SASL error code
193 int prop_setvals(struct propctx *ctx, const char *name, const
195 char **values)
196 Adds multiple values to a single property. This is intended for
197 use by auxprop plugins only.
198 Parameters
200 · ctx (propctx) – The property context to add values to.
202 · name – The name of the property to receive the new
204 value, or NULL, which implies that the values will be
205 added to the same property as the last call to either
206 prop_set() or prop_setvals().
207 · values – A NULL-terminated array of values to be added
209 the property.
210 Returns
212 SASL error code
213
215 propval
216 A struct holding a name and its property values. A name can have
217 zero or more values.
218 Parameters
220 · name – const char *. Name of this propval. NULL means
222 end of list.
223 · values – const char **. List of string values. If prop‐
225 erty not found, values == NULL. If property found with
226 no values, then *values == NULL
227 propctx
229 A property context.
230 Parameters
232 · values (propval *) – List of property values in this
234 context.
235
237 The property functions that return an int return SASL error codes.
238 See sasl_errors(3). Those that return pointers will return a valid
239 pointer on success, or NULL on any error.
240
242 RFC 4422
243
245 sasl(3), sasl_errors(3), sasl_auxprop_request(3), sasl_aux‐
246 prop_getctx(3)
247
249 The Cyrus Team
250
252 1993-2016, The Cyrus Team
2532.1.27 January 29, 2018 SASL_AUXPROP(3)