1sasl_auxprop(10 July 2001) sasl_auxprop(10 July 2001)
2
6 sasl_auxprop - How to work with SASL auxiliary properties
7
10 #include <sasl/prop.h>
11 struct propctx *prop_new(unsigned estimate)
13 int prop_dup(struct propctx *src_ctx,
15 struct propctx *dst_ctx)
16 int prop_request(struct propctx *ctx,
18 const char **names)
19 const struct propval *prop_get(struct propctx *ctx)
21 int prop_getnames(struct propctx *ctx, const char **names,
23 struct porpval *vals)
24 void prop_clear(struct propctx *ctx, int requests)
26 void prop_erase(struct propctx *ctx, const char *name)
28 void prop_dispose(struct propctx **ctx)
30 int prop_format(struct propctx *ctx, const char *sep, int seplen,
32 char *outbuf, unsigned outmax, unsigned *outlen)
33 int prop_set(struct propctx *ctx, const char *name,
35 const char *value, int vallen)
36 int prop_setvals(struct propctx *ctx, const char *name,
38 const char **values)
39
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 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
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 estimate is the estimate of storage needed total for requests &
63 responses. A value of 0 will imply the library default.
64 int prop_dup(struct propctx *src_ctx, struct propctx *dst_ctx)
67 Duplicate a given property context.
69 int prop_request(struct propctx *ctx, const char **names)
72 Add properties to the request list of a given context.
74 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 const struct propval *prop_get(struct propctx *ctx)
81 Returns a NULL-terminated array of struct propval from the
83 given context.
84 int prop_getnames(struct propctx *ctx, const char **names,
87 struct porpval *vals)
88 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 Returns number of matching properties that were found, or a
98 SASL error code.
99 void prop_clear(struct propctx *ctx, int requests)
102 Clear values and optionally requests from a property context.
104 requests is 1 if the requests should be cleared, 0 otherwise.
106 void prop_erase(struct propctx *ctx, const char *name)
109 Securely erase the value of a property.
111 name is the name of the property to erase.
113 void prop_dispose(struct propctx **ctx)
116 Disposes of a property context and NULLifys the pointer.
118 int prop_format(struct propctx *ctx, const char *sep, int seplen,
121 char *outbuf, unsigned outmax, unsigned
122 *outlen)
123 Format the requested property names into a string. This not
125 intended for use by the application (only by auxprop plugins).
126 sep Is the separator to use for the string
128 outbuf Is the caller-allocated buffer of length outmax that the
130 resulting string will be placed in (including NUL terminator).
131 outlen if non-NULL, will contain the length of the resulting
133 string (excluding NUL terminator).
134 int prop_set(struct propctx *ctx, const char *name, const char *value,
137 int vallen)
138 Adds a property value to the context. This is intended for use
140 by auxprop plugins only.
141 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 value is a value for the property of length vallen
147 int prop_setvals(struct propctx *ctx, const char *name, const char
150 **values)
151 Adds multiple values to a single property. This is intended
153 for use by auxprop plugins only.
154 name has the same meaning as in prop_set
156 values are a NULL-terminated array of values to be added the
158 property.
159
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
168 RFC 2222
169
172 sasl(3), sasl_errors(3), sasl_auxprop_request(3), sasl_aux‐
173 prop_getctx(3)
174SASL man pages SASL sasl_auxprop(10 July 2001)