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