'\" te
.\" Copyright (C) 1998-2003, Carnegie Mellon Univeristy.  All Rights Reserved.
.\" Portions Copyright (C) 2003, Sun Microsystems,
.\" Inc. All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH sasl_auxprop 3SASL "14 Oct 2003" "SunOS 5.11" "Simple Authentication Security Layer Library Functions"
.SH NAME
sasl_auxprop, prop_new, prop_dup, prop_request, prop_get, prop_getnames,
prop_clear, prop_erase, prop_dispose, prop_format, prop_set, prop_setvals \-
SASL auxilliary properties
.SH SYNOPSIS
.LP
.nf
\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lsasl\fR   [ \fIlibrary\fR ... ]
#include <sasl/prop.h>

\fBstruct propctx *\fR\fBprop_new\fR(\fBunsigned\fR \fIestimate\fR);
.fi

.LP
.nf
\fBint\fR \fBprop_dup\fR(\fBstruct propctx *\fR\fIsrc_ctx\fR, \fBstruct propctx *\fR\fIdst_ctx\fR
.fi

.LP
.nf
\fBint\fR \fBprop_request\fR(\fBstruct propctx *\fR\fIctx\fR, \fBconst char **\fR\fInames\fR
.fi

.LP
.nf
\fBconst struct propval *\fR\fBprop_get\fR(\fBstruct propctx *\fR\fIctx\fR
.fi

.LP
.nf
\fBint\fR \fBprop_getnames\fR(\fBstruct propctx *\fR\fIctx\fR, \fBconst char **\fR\fInames\fR,
     \fBstruct propval *\fR\fIvals\fR
.fi

.LP
.nf
\fBvoid\fR \fBprop_clear\fR(\fBstruct propctx *\fR\fIctx\fR, \fBint\fR \fIrequests\fR
.fi

.LP
.nf
\fBvoid\fR \fBprop_erase\fR(\fBstruct propctx *\fR\fIctx\fR, \fBconst char *\fR\fIname\fR
.fi

.LP
.nf
\fBvoid\fR \fBprop_dispose\fR(\fBstruct propctx *\fR\fIctx\fR
.fi

.LP
.nf
\fBint\fR \fBprop_format\fR(\fBstruct propctx *\fR\fIctx\fR, \fBconst char *\fR\fIsep\fR, \fBint\fR \fIseplen\fR,
     \fBchar *\fR\fIoutbuf\fR, \fBunsigned\fR \fIoutmax\fR, \fBunsigned *\fR\fIoutlen\fR
.fi

.LP
.nf
\fBint\fR \fBprop_set\fR(\fBstruct propctx *\fR\fIctx\fR, \fBconst char *\fR\fIname\fR, \fBconst char *\fR\fIvalue\fR,
     \fBint\fR \fIvallen\fR
.fi

.LP
.nf
\fBint\fR \fBprop_setvals\fR(\fBstruct propctx *\fR\fIctx\fR, \fBconst char *\fR\fIname\fR,
     \fBconst char **\fR\fIvalues\fR
.fi

.SH DESCRIPTION
.sp
.LP
The SASL auxilliary properties are used to obtain properties from external
sources during the authentication process. For example, a mechanizm might need
to query an LDAP server to obtain the authentication secret. The application
probably needs other information from the LDAP server as well, such as the home
directory of the UID. The auxilliary property interface allows the two to
cooperate and results in only a single query against the property sources.
.sp
.LP
Property lookups take place directly after user canonicalization occurs.
Therefore, all request should be registered with the context before user
canonicalization occurs. Requests can calso be registered by using the
\fBsasl_auxprop_request\fR(3SASL) function. Most of the auxilliary property
functions require a property context that can be obtained by calling
\fBsasl_auxprop_getctx\fR(3SASL).
.SS "\fBprop_new()\fR"
.sp
.LP
The \fBprop_new()\fR function creates a new property context. It is unlikely
that application developers will use this call.
.SS "\fBprop_dup()\fR"
.sp
.LP
The \fBprop_dup()\fR function duplicates a given property context.
.SS "\fBprop_request()\fR"
.sp
.LP
The \fBprop_request()\fR function adds properties to the request list of a
given context.
.SS "\fBprop_get()\fR"
.sp
.LP
The \fBprop_get()\fR function returns a null-terminated array of \fBstruct\fR
\fBpropval\fR from the given context.
.SS "\fBprop_getnames()\fR"
.sp
.LP
The \fBprop_getnames()\fR function fills in an array of \fBstruct\fR
\fBpropval\fR based on a list of property names. The \fBvals\fR array is at
least as long as the \fBnames\fR array. The values that are filled in by this
call persist until the next call on the context to \fBprop_request()\fR,
\fBprop_clear()\fR, or \fBprop_dispose()\fR. If a name specified was never
requested, then its associated values entry will be set to \fINULL\fR.
.sp
.LP
The \fBprop_getnames()\fR function returns the number of matching properties
that were found or a SASL error code.
.SS "\fBprop_clear()\fR"
.sp
.LP
The \fBprop_clear()\fR function clears \fIvalues\fR and \fIrequests\fR from a
property context. If the value of \fIrequests\fR is \fB1\fR, then
\fIrequests\fR is cleared. Otherwise, the value of \fIrequests\fR is \fB0\fR.
.SS "\fBprop_erase()\fR"
.sp
.LP
The \fBprop_erase()\fR function securely erases the value of a property.
\fIname\fR is the name of the property to erase.
.SS "\fBprop_dispose()\fR"
.sp
.LP
The \fBprop_dispose()\fR function disposes of a property context and nullifies
the pointer.
.SS "\fBprop_format()\fR"
.sp
.LP
The \fBprop_format()\fR function formats the requested property names into a
string. The \fBprop_format()\fR function is not intended to be used by the
application. The function is used only by \fBauxprop\fR plug-ins.
.SS "\fBprop_set()\fR"
.sp
.LP
The \fBprop_set()\fR functions adds a property value to the context. The
\fBprop_set()\fR function is used only by \fBauxprop\fR plug-ins.
.SS "\fBprop_setvals()\fR"
.sp
.LP
The \fBprop_setvals()\fR function adds multiple values to a single property.
The \fBprop_setvals()\fR function is used only by \fBauxprop\fR plug-ins.
.SH PARAMETERS
.sp
.ne 2
.mk
.na
\fB\fIconn\fR\fR
.ad
.RS 12n
.rt  
The \fBsasl_conn_t\fR for which the request is being made
.RE

.sp
.ne 2
.mk
.na
\fB\fIctx\fR\fR
.ad
.RS 12n
.rt  
The property context.
.RE

.sp
.ne 2
.mk
.na
\fB\fIestimate\fR\fR
.ad
.RS 12n
.rt  
The estimate of the total storage needed for requests and responses. The
library default is implied by a value of \fB0\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fInames\fR\fR
.ad
.RS 12n
.rt  
The null-terminated array of property names. \fInames\fR must persist until the
requests are cleared or the context is disposed of with a call to
\fBprop_dispose()\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fIname\fR\fR
.ad
.RS 12n
.rt  
The name of the property.
.sp
For \fBprop_set()\fR, \fIname\fR is the named of the property to receive the
new value, or \fINULL\fR. The value will be added to the same property as the
last call to either \fBprop_set()\fR or \fBprop_setvals()\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fIoutbuf\fR\fR
.ad
.RS 12n
.rt  
The caller-allocated buffer of length \fIoutmax\fR that the resulting string,
including the \fINULL\fR terminator, will be placed in.
.RE

.sp
.ne 2
.mk
.na
\fB\fIoutlen\fR\fR
.ad
.RS 12n
.rt  
If non-\fINULL\fR, contains the length of the resulting sting, excluding the
\fINULL\fR terminator.
.RE

.sp
.ne 2
.mk
.na
\fB\fIoutmax\fR\fR
.ad
.RS 12n
.rt  
The maximum length of the output buffer, including the \fINULL\fR terminator.
.RE

.sp
.ne 2
.mk
.na
\fB\fIrequests\fR\fR
.ad
.RS 12n
.rt  
The request list for a given context.
.RE

.sp
.ne 2
.mk
.na
\fB\fIsep\fR\fR
.ad
.RS 12n
.rt  
The separator to use for the string.
.RE

.sp
.ne 2
.mk
.na
\fB\fIseplen\fR\fR
.ad
.RS 12n
.rt  
The length of the separator. The the values is less than 0, then \fBstrlen\fR
will be used as \fIsep\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fIvallen\fR\fR
.ad
.RS 12n
.rt  
The length of the property.
.RE

.sp
.ne 2
.mk
.na
\fB\fIvals\fR\fR
.ad
.RS 12n
.rt  
The value string.
.RE

.sp
.ne 2
.mk
.na
\fB\fIvalue\fR\fR
.ad
.RS 12n
.rt  
A value for the property of length \fIvallen\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fIvalues\fR\fR
.ad
.RS 12n
.rt  
A null-terminated array of values to be added to the property.
.RE

.SH ERRORS
.sp
.LP
The \fBsasl_auxprop()\fR functions that return an \fBint\fR will return a SASL
error code. See \fBsasl_errors\fR(3SASL). Those \fBsasl_auxprop()\fR functions
that return a pointer will return a valid pointer upon success and return
\fINULL\fR upon failure.
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Interface StabilityEvolving
_
MT-LevelMT-Safe
.TE

.SH SEE ALSO
.sp
.LP
\fBsasl_auxprop_getctx\fR(3SASL), \fBsasl_auxprop_request\fR(3SASL),
\fBsasl_errors\fR(3SASL), \fBattributes\fR(5)