SASL_AUXPROP(3)

💖 NAME 💖

sasl_auxprop — the Cyrus SASL auxiliary property glow-up, aka the page that explains SASL_AUXPROP(3) and honestly? it eats.

---

✨ SYNOPSIS ✨

#include <sasl/prop.h>

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 propval *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 🌸

okay so bestie, picture this: SASL auxiliary properties are how you pull properties out of external sources while the authentication process is happening. like, a mechanism might need to go query an LDAP server to get the authentication secret. but the application probably wants other stuff from that same server too — home directory, UID, all of it. and the auxiliary property interface is literally the thing that lets those two cooperate so you only get a single query against the LDAP server (or whatever other property source you're using). one query. iconic behavior. 💅

property lookups happen directly after user canonicalization occurs. so no cap, all your requests need to be registered with the context before that moment. 📌

also hi, quick note: you can register requests with the sasl_auxprop_request(3) function too. but most of the functions listed below? they need a property context, and you get one of those by calling sasl_auxprop_getctx(3). 🫶

---

🎀 API DESCRIPTION 🎀

prop_new(unsigned estimate)

create a new property context. ngl, it's probably unnecessary for application developers to call this at any point. 🙈

Parameters

• estimate – is the estimate of storage needed in total for requests & responses. a value of 0 implies the library default.

Returns

a new property context: propctx ✨

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

duplicate a given property context. copy-paste but make it ✨intentional✨.

Parameters

• src_ctx (propctx) – property context to copy.
• dst_ctx (propctx) – destination context to copy into.

Returns

SASL error code.

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

add properties to the request list of a given context.

Parameters

• ctx (propctx) – the property context to add add the request list to.
• 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().

⚠️ that names array has to stick around — it must persist until the requests are cleared or the context gets disposed of with prop_dispose(). don't let it go out of scope, bestie, it's giving use-after-free 💀

Returns

SASL error code

prop_get(struct propctx *ctx)

fetch out the property values from a context. get you your values, queen. 👑

Parameters

• ctx (propctx) – the property context to fetch from.

Returns

a NULL-terminated array of property values from the given context.

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

fill in a (provided) array of property values 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. and if a name specified here was never requested, then its associated values entry will be set to NULL.

Parameters

• ctx (propctx) – the property context to fill in.

Returns

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

prop_clear(struct propctx *ctx, int requests)

clear values and (optionally) requests from a property context. spring cleaning but for properties 🧹🌸

Parameters

• ctx (propctx) – the property context to clear.
• requests – set to 1 if the requests should be cleared, 0 otherwise.

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

securely erase the value of a property from a context. 🔥 not just deleted — securely erased, and yes the distinction matters.

Parameters

• ctx (propctx) – the property context to find the property in.
• name – is the name of the property to erase.

prop_dispose(struct propctx **ctx)

disposes of a property context and NULLifys the pointer. it takes the double pointer and leaves it NULL. no dangling anything, we don't do that here. 🫶

Parameters

• ctx (propctx) – the property context to clear.

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). so if you're an application dev, hands off, this one's for the plugin girlies. 🙅♀️

Parameters

• ctx (propctx) – the property context to extract values from.
• sep – the separator to use for the string
• seplen – (the original page doesn't spell this one out, bestie, but it's sitting right there in the signature 💀)
• outbuf – destination string. caller must allocate the buffer of length outmax (including NUL terminator).
• outlen – if non-NULL, will contain the length of the resulting string (excluding NUL terminator).

Returns

SASL error code.

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.

Parameters

• ctx (propctx) – the property context to add a value to.
• name – 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 – the new value (of length vallen)
• vallen – the length of the string value.

Returns

SASL error code

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.

Parameters

• ctx (propctx) – the property context to add values to.
• name – the name of the property to receive the new value, or NULL, which implies that the values will be added to the same property as the last call to either prop_set() or prop_setvals().
• values – a NULL-terminated array of values to be added the property.

Returns

SASL error code

---

🦋 DATA STRUCTURES 🦋

type propval

a struct holding a name and its property values. a name can have zero or more values. (zero. so a name can absolutely show up with nothing attached. it's giving "seen but no reply" 🙈)

Param name

const char *. name of this propval. NULL means end of list.

Param values

const char **. list of string values. if property not found, values == NULL. if property found with no values, then *values == NULL

type propctx

a property context.

Param values

list of property values in this context.

Type values

propval *

---

🌈 RETURN VALUE 🌈

the property functions that return an int return SASL error codes. see sasl_errors(3). and the ones that return pointers? they'll return a valid pointer on success, or NULL on any error. simple as. ✨

---

⭐ CONFORMING TO ⭐

RFC 4422

---

👑 SEE ALSO 👑

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

---

💜 AUTHOR 💜

The Cyrus Team

---

🍓 COPYRIGHT 🍓

1993-2016, The Cyrus Team

---

and that's the whole page, bestie, we ate and left no crumbs 🎀 this was Cyrus SASL 2.1.28, dated February 18, 2022 — go forth and query your LDAP server exactly once, the way the universe intended. mwah 💅💖