share/man/man3sasl/sasl_auxprop.3sasl

   1 '\" te
   2 .\" Copyright (C) 1998-2003, Carnegie Mellon Univeristy.  All Rights Reserved.
   3 .\" Portions Copyright (C) 2003, Sun Microsystems,
   4 .\" Inc. All Rights Reserved
   5 .\" 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.
   6 .\" 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.
   7 .\" 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]
   8 .TH SASL_AUXPROP 3SASL "April 9, 2016"
   9 .SH NAME
  10 sasl_auxprop, prop_new, prop_dup, prop_request, prop_get, prop_getnames,
  11 prop_clear, prop_erase, prop_dispose, prop_format, prop_set, prop_setvals \-
  12 SASL auxiliary properties
  13 .SH SYNOPSIS
  14 .LP
  15 .nf
  16 \fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lsasl\fR   [ \fIlibrary\fR ... ]
  17 #include <sasl/prop.h>
  18
  19 \fBstruct propctx *\fR\fBprop_new\fR(\fBunsigned\fR \fIestimate\fR);
  20 .fi
  21
  22 .LP
  23 .nf
  24 \fBint\fR \fBprop_dup\fR(\fBstruct propctx *\fR\fIsrc_ctx\fR, \fBstruct propctx *\fR\fIdst_ctx\fR
  25 .fi
  26
  27 .LP
  28 .nf
  29 \fBint\fR \fBprop_request\fR(\fBstruct propctx *\fR\fIctx\fR, \fBconst char **\fR\fInames\fR
  30 .fi
  31
  32 .LP
  33 .nf
  34 \fBconst struct propval *\fR\fBprop_get\fR(\fBstruct propctx *\fR\fIctx\fR
  35 .fi
  36
  37 .LP
  38 .nf
  39 \fBint\fR \fBprop_getnames\fR(\fBstruct propctx *\fR\fIctx\fR, \fBconst char **\fR\fInames\fR,
  40      \fBstruct propval *\fR\fIvals\fR
  41 .fi
  42
  43 .LP
  44 .nf
  45 \fBvoid\fR \fBprop_clear\fR(\fBstruct propctx *\fR\fIctx\fR, \fBint\fR \fIrequests\fR
  46 .fi
  47
  48 .LP
  49 .nf
  50 \fBvoid\fR \fBprop_erase\fR(\fBstruct propctx *\fR\fIctx\fR, \fBconst char *\fR\fIname\fR
  51 .fi
  52
  53 .LP
  54 .nf
  55 \fBvoid\fR \fBprop_dispose\fR(\fBstruct propctx *\fR\fIctx\fR
  56 .fi
  57
  58 .LP
  59 .nf
  60 \fBint\fR \fBprop_format\fR(\fBstruct propctx *\fR\fIctx\fR, \fBconst char *\fR\fIsep\fR, \fBint\fR \fIseplen\fR,
  61      \fBchar *\fR\fIoutbuf\fR, \fBunsigned\fR \fIoutmax\fR, \fBunsigned *\fR\fIoutlen\fR
  62 .fi
  63
  64 .LP
  65 .nf
  66 \fBint\fR \fBprop_set\fR(\fBstruct propctx *\fR\fIctx\fR, \fBconst char *\fR\fIname\fR, \fBconst char *\fR\fIvalue\fR,
  67      \fBint\fR \fIvallen\fR
  68 .fi
  69
  70 .LP
  71 .nf
  72 \fBint\fR \fBprop_setvals\fR(\fBstruct propctx *\fR\fIctx\fR, \fBconst char *\fR\fIname\fR,
  73      \fBconst char **\fR\fIvalues\fR
  74 .fi
  75
  76 .SH DESCRIPTION
  77 .LP
  78 The SASL auxiliary properties are used to obtain properties from external
  79 sources during the authentication process. For example, a mechanism might need
  80 to query an LDAP server to obtain the authentication secret. The application
  81 probably needs other information from the LDAP server as well, such as the home
  82 directory of the UID. The auxiliary property interface allows the two to
  83 cooperate and results in only a single query against the property sources.
  84 .sp
  85 .LP
  86 Property lookups take place directly after user canonicalization occurs.
  87 Therefore, all request should be registered with the context before user
  88 canonicalization occurs. Requests can also be registered by using the
  89 \fBsasl_auxprop_request\fR(3SASL) function. Most of the auxiliary property
  90 functions require a property context that can be obtained by calling
  91 \fBsasl_auxprop_getctx\fR(3SASL).
  92 .SS "\fBprop_new()\fR"
  93 .LP
  94 The \fBprop_new()\fR function creates a new property context. It is unlikely
  95 that application developers will use this call.
  96 .SS "\fBprop_dup()\fR"
  97 .LP
  98 The \fBprop_dup()\fR function duplicates a given property context.
  99 .SS "\fBprop_request()\fR"
 100 .LP
 101 The \fBprop_request()\fR function adds properties to the request list of a
 102 given context.
 103 .SS "\fBprop_get()\fR"
 104 .LP
 105 The \fBprop_get()\fR function returns a null-terminated array of \fBstruct\fR
 106 \fBpropval\fR from the given context.
 107 .SS "\fBprop_getnames()\fR"
 108 .LP
 109 The \fBprop_getnames()\fR function fills in an array of \fBstruct\fR
 110 \fBpropval\fR based on a list of property names. The \fBvals\fR array is at
 111 least as long as the \fBnames\fR array. The values that are filled in by this
 112 call persist until the next call on the context to \fBprop_request()\fR,
 113 \fBprop_clear()\fR, or \fBprop_dispose()\fR. If a name specified was never
 114 requested, then its associated values entry will be set to \fINULL\fR.
 115 .sp
 116 .LP
 117 The \fBprop_getnames()\fR function returns the number of matching properties
 118 that were found or a SASL error code.
 119 .SS "\fBprop_clear()\fR"
 120 .LP
 121 The \fBprop_clear()\fR function clears \fIvalues\fR and \fIrequests\fR from a
 122 property context. If the value of \fIrequests\fR is \fB1\fR, then
 123 \fIrequests\fR is cleared. Otherwise, the value of \fIrequests\fR is \fB0\fR.
 124 .SS "\fBprop_erase()\fR"
 125 .LP
 126 The \fBprop_erase()\fR function securely erases the value of a property.
 127 \fIname\fR is the name of the property to erase.
 128 .SS "\fBprop_dispose()\fR"
 129 .LP
 130 The \fBprop_dispose()\fR function disposes of a property context and nullifies
 131 the pointer.
 132 .SS "\fBprop_format()\fR"
 133 .LP
 134 The \fBprop_format()\fR function formats the requested property names into a
 135 string. The \fBprop_format()\fR function is not intended to be used by the
 136 application. The function is used only by \fBauxprop\fR plug-ins.
 137 .SS "\fBprop_set()\fR"
 138 .LP
 139 The \fBprop_set()\fR functions adds a property value to the context. The
 140 \fBprop_set()\fR function is used only by \fBauxprop\fR plug-ins.
 141 .SS "\fBprop_setvals()\fR"
 142 .LP
 143 The \fBprop_setvals()\fR function adds multiple values to a single property.
 144 The \fBprop_setvals()\fR function is used only by \fBauxprop\fR plug-ins.
 145 .SH PARAMETERS
 146 .ne 2
 147 .na
 148 \fB\fIconn\fR\fR
 149 .ad
 150 .RS 12n
 151 The \fBsasl_conn_t\fR for which the request is being made
 152 .RE
 153
 154 .sp
 155 .ne 2
 156 .na
 157 \fB\fIctx\fR\fR
 158 .ad
 159 .RS 12n
 160 The property context.
 161 .RE
 162
 163 .sp
 164 .ne 2
 165 .na
 166 \fB\fIestimate\fR\fR
 167 .ad
 168 .RS 12n
 169 The estimate of the total storage needed for requests and responses. The
 170 library default is implied by a value of \fB0\fR.
 171 .RE
 172
 173 .sp
 174 .ne 2
 175 .na
 176 \fB\fInames\fR\fR
 177 .ad
 178 .RS 12n
 179 The null-terminated array of property names. \fInames\fR must persist until the
 180 requests are cleared or the context is disposed of with a call to
 181 \fBprop_dispose()\fR.
 182 .RE
 183
 184 .sp
 185 .ne 2
 186 .na
 187 \fB\fIname\fR\fR
 188 .ad
 189 .RS 12n
 190 The name of the property.
 191 .sp
 192 For \fBprop_set()\fR, \fIname\fR is the named of the property to receive the
 193 new value, or \fINULL\fR. The value will be added to the same property as the
 194 last call to either \fBprop_set()\fR or \fBprop_setvals()\fR.
 195 .RE
 196
 197 .sp
 198 .ne 2
 199 .na
 200 \fB\fIoutbuf\fR\fR
 201 .ad
 202 .RS 12n
 203 The caller-allocated buffer of length \fIoutmax\fR that the resulting string,
 204 including the \fINULL\fR terminator, will be placed in.
 205 .RE
 206
 207 .sp
 208 .ne 2
 209 .na
 210 \fB\fIoutlen\fR\fR
 211 .ad
 212 .RS 12n
 213 If non-\fINULL\fR, contains the length of the resulting sting, excluding the
 214 \fINULL\fR terminator.
 215 .RE
 216
 217 .sp
 218 .ne 2
 219 .na
 220 \fB\fIoutmax\fR\fR
 221 .ad
 222 .RS 12n
 223 The maximum length of the output buffer, including the \fINULL\fR terminator.
 224 .RE
 225
 226 .sp
 227 .ne 2
 228 .na
 229 \fB\fIrequests\fR\fR
 230 .ad
 231 .RS 12n
 232 The request list for a given context.
 233 .RE
 234
 235 .sp
 236 .ne 2
 237 .na
 238 \fB\fIsep\fR\fR
 239 .ad
 240 .RS 12n
 241 The separator to use for the string.
 242 .RE
 243
 244 .sp
 245 .ne 2
 246 .na
 247 \fB\fIseplen\fR\fR
 248 .ad
 249 .RS 12n
 250 The length of the separator. If the value is less than 0, then \fBstrlen\fR
 251 will be used to determine the length of \fIsep\fR instead.
 252 .RE
 253
 254 .sp
 255 .ne 2
 256 .na
 257 \fB\fIvallen\fR\fR
 258 .ad
 259 .RS 12n
 260 The length of the property.
 261 .RE
 262
 263 .sp
 264 .ne 2
 265 .na
 266 \fB\fIvals\fR\fR
 267 .ad
 268 .RS 12n
 269 The value string.
 270 .RE
 271
 272 .sp
 273 .ne 2
 274 .na
 275 \fB\fIvalue\fR\fR
 276 .ad
 277 .RS 12n
 278 A value for the property of length \fIvallen\fR.
 279 .RE
 280
 281 .sp
 282 .ne 2
 283 .na
 284 \fB\fIvalues\fR\fR
 285 .ad
 286 .RS 12n
 287 A null-terminated array of values to be added to the property.
 288 .RE
 289
 290 .SH ERRORS
 291 .LP
 292 The \fBsasl_auxprop()\fR functions that return an \fBint\fR will return a SASL
 293 error code. See \fBsasl_errors\fR(3SASL). Those \fBsasl_auxprop()\fR functions
 294 that return a pointer will return a valid pointer upon success and return
 295 \fINULL\fR upon failure.
 296 .SH ATTRIBUTES
 297 .LP
 298 See \fBattributes\fR(5) for descriptions of the following attributes:
 299 .sp
 300
 301 .sp
 302 .TS
 303 box;
 304 c | c
 305 l | l .
 306 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 307 _
 308 Interface Stability     Evolving
 309 _
 310 MT-Level        MT-Safe
 311 .TE
 312
 313 .SH SEE ALSO
 314 .LP
 315 \fBsasl_auxprop_getctx\fR(3SASL), \fBsasl_auxprop_request\fR(3SASL),
 316 \fBsasl_errors\fR(3SASL), \fBattributes\fR(5)