usr/src/man/man3sasl/sasl_client_step.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_STEP 3SASL "Aug 28, 2003"
   9 .SH NAME
  10 sasl_client_step \- acquire an auxiliary property context
  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_step\fR(\fBsasl_conn_t *\fR\fIconn\fR, \fBconst char *\fR\fIserverin\fR,
  18      \fBsasl_interact_t **\fR\fBunsigned\fR \fIserverinlen\fR, \fIprompt_need\fR,
  19      \fBconst char **\fR\fIclientout\fR, \fBsasl_interact_t **\fR\fBunsigned *\fR\fIclientoutlen\fR);
  20 .fi
  21
  22 .SH DESCRIPTION
  23 .sp
  24 .LP
  25 Use the \fBsasl_client_step()\fR interface performs a step in the
  26 authentication negotiation. \fBsasl_client_step()\fR returns \fBSASL_OK\fR if
  27 the complete negotiation is successful. If the negotiation on step is completed
  28 successfuly, but at least one more step is required, \fBsasl_client_step()\fR
  29 returns \fBSASL_CONTINUE\fR. A client should not assume an authentication
  30 negotiaion is successful because the server signaled success through the
  31 protocol. For example, if the server signaled \fBOK Authentication succeeded\fR
  32 in IMAP, \fBsasl_client_step()\fR should be called one more time with a
  33 \fIserverinlen\fR of zero.
  34 .sp
  35 .LP
  36 If a call to \fBsasl_client_step()\fR returns \fBSASL_INTERACT\fR, the library
  37 requires some values before \fBsasl_client_step()\fR can proceed. The
  38 \fIprompt_need\fR structure will be filled with the requests. The application
  39 should fulfull these requests and call \fBsasl_client_step()\fR again with
  40 identical parameters. The \fIprompt_need\fR parameter will be the same pointer
  41 as before, but it will have been filled in by the application.
  42 .SH PARAMETERS
  43 .sp
  44 .ne 2
  45 .na
  46 \fB\fIconn\fR\fR
  47 .ad
  48 .RS 16n
  49 The SASL connection context.
  50 .RE
  51
  52 .sp
  53 .ne 2
  54 .na
  55 \fB\fIserverin\fR\fR
  56 .ad
  57 .RS 16n
  58 The data given by the server. The data is decoded if the protocol encodes
  59 requests sent over the wire.
  60 .RE
  61
  62 .sp
  63 .ne 2
  64 .na
  65 \fB\fIserverinlen\fR\fR
  66 .ad
  67 .RS 16n
  68 The length of the \fIserverin\fR.
  69 .RE
  70
  71 .sp
  72 .ne 2
  73 .na
  74 \fB\fIclientout\fR\fR
  75 .ad
  76 .br
  77 .na
  78 \fB\fIclientoutlen\fR\fR
  79 .ad
  80 .RS 16n
  81 \fIclientout\fR and \fIclientoutlen\fR are created. They contain the initial
  82 client response to send to the server. It is the job of the client to send them
  83 over the network to the server. Any protocol specific encodingthat is
  84 necessary, for example \fBbase64\fR encoding, must be done by the client.
  85 .RE
  86
  87 .sp
  88 .ne 2
  89 .na
  90 \fB\fIprompt_need\fR\fR
  91 .ad
  92 .RS 16n
  93 A list of prompts that are needed to continue, if necessary.
  94 .RE
  95
  96 .SH RETURN VALUES
  97 .sp
  98 .LP
  99 \fBsasl_client_step()\fR returns an integer that corresponds to a SASL error
 100 code.
 101 .SH ERRORS
 102 .sp
 103 .ne 2
 104 .na
 105 \fB\fBSASL_OK\fR\fR
 106 .ad
 107 .RS 17n
 108 The call to \fBsasl_client_start()\fR was successful. Authentication is
 109 complete.
 110 .RE
 111
 112 .sp
 113 .ne 2
 114 .na
 115 \fB\fBSASL_CONTINUE\fR\fR
 116 .ad
 117 .RS 17n
 118 The call to \fBsasl_client_start()\fR was successful, but at least one more
 119 step is required for authentication.
 120 .RE
 121
 122 .sp
 123 .ne 2
 124 .na
 125 \fB\fBSASL_INTERACT\fR\fR
 126 .ad
 127 .RS 17n
 128 The library requires some values before \fBsasl_client_step()\fR can proceed.
 129 .RE
 130
 131 .sp
 132 .LP
 133 All other error codes indicate an error situation that must be handled, or the
 134 authentication session should be quit. See \fBsasl_errors\fR(3SASL) for
 135 information on SASL error codes.
 136 .SH ATTRIBUTES
 137 .sp
 138 .LP
 139 See \fBattributes\fR(5) for descriptions of the following attributes:
 140 .sp
 141
 142 .sp
 143 .TS
 144 box;
 145 c | c
 146 l | l .
 147 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 148 _
 149 Interface Stability     Evolving
 150 _
 151 MT-Level        Safe
 152 .TE
 153
 154 .SH SEE ALSO
 155 .sp
 156 .LP
 157 \fBsasl_errors\fR(3SASL), \fBattributes\fR(5)