usr/src/man/man3sasl/sasl_server_new.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_SERVER_NEW 3SASL "Oct 14, 2003"
   9 .SH NAME
  10 sasl_server_new \- create a new server authentication object
  11 .SH SYNOPSIS
  12 .LP
  13 .nf
  14 \fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lsasl\fR   [ \fIlibrary\fR ... ]
  15 #include <sasl/sasl.h>
  16
  17 \fBint\fR \fBsasl_server_new\fR(\fBconst char  *\fR\fIservice\fR, \fBconst char  *\fR\fIserverFQDN\fR,
  18      \fBconst char  *\fR\fIuser_realm\fR, \fBconst char  *\fR\fIiplocalport\fR,
  19      \fBconst char  *\fR\fIipremoteport\fR, \fBconst sasl_callback_t *\fR\fIcallbacks\fR,
  20      \fBunsigned\fR \fIflags\fR, \fBsasl_conn_t **\fR\fIpconn\fR);
  21 .fi
  22
  23 .SH DESCRIPTION
  24 .sp
  25 .LP
  26 Use the \fBsasl_server_new()\fR interface to create a new SASL context. This
  27 context will be used for all SASL calls for one connection. The new SASL
  28 context handles both authentication and integrity or encryption layers after
  29 authentication.
  30 .SH PARAMETERS
  31 .sp
  32 .ne 2
  33 .na
  34 \fB\fIservice\fR\fR
  35 .ad
  36 .RS 16n
  37 The registered name of the service that uses SASL. The registered name is
  38 usually the protocol name, for example, IMAP.
  39 .RE
  40
  41 .sp
  42 .ne 2
  43 .na
  44 \fB\fIserverFQDN\fR\fR
  45 .ad
  46 .RS 16n
  47 The fully-qualified server domain name. If the value of \fIserverFQDN\fR is
  48 \fINULL\fR, use \fBgethostname\fR(3C). The \fIserverFQDN\fR parameter is useful
  49 for multi-homed servers.
  50 .RE
  51
  52 .sp
  53 .ne 2
  54 .na
  55 \fB\fIuser_realm\fR\fR
  56 .ad
  57 .RS 16n
  58 The domain of the user agent. The \fIuser_realm\fR is usually not necessary.
  59 The default value of \fIuser_realm\fR is \fINULL\fR.
  60 .RE
  61
  62 .sp
  63 .ne 2
  64 .na
  65 \fB\fIiplocalport\fR\fR
  66 .ad
  67 .RS 16n
  68 .sp
  69 .LP
  70 The IP address and port of the local side of the connection. The value of
  71 \fIiplocalport\fR may be \fINULL\fR. If \fIiplocalport\fR is \fINULL\fR,
  72 mechanisms that require IP address information are disabled. The
  73 \fIiplocalport\fR string must be in one of the following formats:
  74 .RS +4
  75 .TP
  76 .ie t \(bu
  77 .el o
  78 \fBa.b.c.d:port\fR (IPv4)
  79 .RE
  80 .RS +4
  81 .TP
  82 .ie t \(bu
  83 .el o
  84 \fB[e:f:g:h:i:j:k:l]:port\fR (IPv6)
  85 .RE
  86 .RS +4
  87 .TP
  88 .ie t \(bu
  89 .el o
  90 \fB[e:f:g:h:i:j:a.b.c.d]:port\fR (IPv6)
  91 .RE
  92 .sp
  93 .LP
  94 The following older formats are also supported:
  95 .RS +4
  96 .TP
  97 .ie t \(bu
  98 .el o
  99 \fBa.b.c.d;port\fR (IPv4)
 100 .RE
 101 .RS +4
 102 .TP
 103 .ie t \(bu
 104 .el o
 105 \fBe:f:g:h:i:j:k:l;port\fR (IPv6)
 106 .RE
 107 .RS +4
 108 .TP
 109 .ie t \(bu
 110 .el o
 111 \fBe:f:g:h:i:j:a.b.c.d;port\fR (IPv6)
 112 .RE
 113 .RE
 114
 115 .sp
 116 .ne 2
 117 .na
 118 \fB\fIipremoteport\fR\fR
 119 .ad
 120 .RS 16n
 121 The IP address and port of the remote side of the connection. The value of
 122 \fIipremoteport\fR may be \fINULL\fR. See \fIiplocalport\fR.
 123 .RE
 124
 125 .sp
 126 .ne 2
 127 .na
 128 \fB\fIcallbacks\fR\fR
 129 .ad
 130 .RS 16n
 131 Callbacks, for example: authorization, lang, and new getopt context.
 132 .RE
 133
 134 .sp
 135 .ne 2
 136 .na
 137 \fB\fIflags\fR\fR
 138 .ad
 139 .RS 16n
 140 Usage flags. For servers, the flags \fBSASL_NEED_PROXY\fR and
 141 \fBSASL_SUCCESS_DATA\fR are available.
 142 .RE
 143
 144 .sp
 145 .ne 2
 146 .na
 147 \fB\fIpconn\fR\fR
 148 .ad
 149 .RS 16n
 150 A pointer to the connection context allocated by the library. This structure
 151 will be used for all future SASL calls for this connection.
 152 .RE
 153
 154 .SH RETURN VALUES
 155 .sp
 156 .LP
 157 \fBsasl_server_new()\fR returns an integer that corresponds to a SASL error
 158 code.
 159 .SH ERRORS
 160 .sp
 161 .ne 2
 162 .na
 163 \fB\fBSASL_OK\fR\fR
 164 .ad
 165 .RS 11n
 166 The call to \fBsasl_server_new()\fR was successful.
 167 .RE
 168
 169 .sp
 170 .LP
 171 All other error codes indicate an error situation that must be handled, or the
 172 authentication session should be quit. See \fBsasl_errors\fR(3SASL) for
 173 information on SASL error codes.
 174 .SH ATTRIBUTES
 175 .sp
 176 .LP
 177 See \fBattributes\fR(5) for descriptions of the following attributes:
 178 .sp
 179
 180 .sp
 181 .TS
 182 box;
 183 c | c
 184 l | l .
 185 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 186 _
 187 Interface Stability     Evolving
 188 _
 189 MT-Level        MT-Safe
 190 .TE
 191
 192 .SH SEE ALSO
 193 .sp
 194 .LP
 195 \fBgethostname\fR(3C), \fBsasl_errors\fR(3SASL), \fBattributes\fR(5)