usr/src/man/man3sasl/sasl_client_start.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_CLIENT_START 3SASL "Aug 26, 2003"
   9 .SH NAME
  10 sasl_client_start \- perform a step in the authentication negotiation
  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_client_start\fR(\fBsasl_conn_t *\fR\fIconn\fR, \fBconst char *\fR\fImechlist\fR,
  18      \fBsasl_interact_t **\fR\fIprompt_need\fR, \fBconst char **\fR\fIclientout\fR,
  19      \fBunsigned *\fR\fIclientoutlen\fR, \fBconst char **\fR\fImech\fR);
  20 .fi
  21
  22 .SH DESCRIPTION
  23 .sp
  24 .LP
  25 Use the \fBsasl_client_start()\fR interface to select a mechanism for
  26 authentication and start the authentication session. The \fImechlist\fR
  27 parameter holds the list of mechanisms that the client might like to use. The
  28 mechanisms in the list are not necessarily supported by the client, nor are the
  29 mechanisms necessarily valid. SASL determines which of the mechanisms to use
  30 based upon the security preferences specified earlier. The list of mechanisms
  31 is typically a list of mechanisms that the server supports, acquired from a
  32 capability request.
  33 .sp
  34 .LP
  35 If \fBSASL_INTERACT\fR is returned, the library needs some values to be filled
  36 in before it can proceed. The \fIprompt_need\fR structure is filled in with
  37 requests. The application fullfills these requests and calls
  38 \fBsasl_client_start()\fR again with identical parameters. The
  39 \fIprompt_need\fR parameter is the same pointer as before, but it is filled in
  40 by the application.
  41 .SH PARAMETERS
  42 .sp
  43 .ne 2
  44 .na
  45 \fB\fIconn\fR\fR
  46 .ad
  47 .RS 16n
  48 The SASL connection context.
  49 .RE
  50
  51 .sp
  52 .ne 2
  53 .na
  54 \fB\fImechlist\fR\fR
  55 .ad
  56 .RS 16n
  57 A list of mechanism that the server has available. Punctuation is ignored.
  58 .RE
  59
  60 .sp
  61 .ne 2
  62 .na
  63 \fB\fIprompt_need\fR\fR
  64 .ad
  65 .RS 16n
  66 A list of prompts that are needed to continue, if necessary.
  67 .RE
  68
  69 .sp
  70 .ne 2
  71 .na
  72 \fB\fIclientout\fR\fR
  73 .ad
  74 .br
  75 .na
  76 \fB\fIclientoutlen\fR\fR
  77 .ad
  78 .RS 16n
  79 \fIclientout\fR and \fIclientoutlen\fR are created. They contain the initial
  80 client response to send to the server. It is the job of the client to send them
  81 over the network to the server. Any protocol specific encodingthat is
  82 necessary, for example \fBbase64\fR encoding, must be done by the client.
  83 .sp
  84 If the protocol lacks client-send-first capability, then set \fIclientout\fR to
  85 \fINULL\fR. If there is no initial client-send, then *\fIclientout\fR will be
  86 set to \fINULL\fR on return.
  87 .RE
  88
  89 .sp
  90 .ne 2
  91 .na
  92 \fB\fImech\fR\fR
  93 .ad
  94 .RS 16n
  95 Contains the name of the chosen SASL mechanism, upon success.
  96 .RE
  97
  98 .SH RETURN VALUES
  99 .sp
 100 .LP
 101 \fBsasl_client_start()\fR returns an integer that corresponds to a SASL error
 102 code.
 103 .SH ERRORS
 104 .sp
 105 .ne 2
 106 .na
 107 \fB\fBSASL_CONTINUE\fR\fR
 108 .ad
 109 .RS 17n
 110 The call to \fBsasl_client_start()\fR was successful, and more steps are needed
 111 in the authentication.
 112 .RE
 113
 114 .sp
 115 .LP
 116 All other error codes indicate an error situation that must be handled, or the
 117 authentication session should be quit. See \fBsasl_errors\fR(3SASL) for
 118 information on SASL error codes.
 119 .SH ATTRIBUTES
 120 .sp
 121 .LP
 122 See \fBattributes\fR(5) for descriptions of the following attributes:
 123 .sp
 124
 125 .sp
 126 .TS
 127 box;
 128 c | c
 129 l | l .
 130 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 131 _
 132 Availablity     SUNWlibsasl
 133 _
 134 Interface Stability     Evolving
 135 _
 136 MT-Level        Safe
 137 .TE
 138
 139 .SH SEE ALSO
 140 .sp
 141 .LP
 142 \fBsasl_errors\fR(3SASL), \fBattributes\fR(5)