'\" te
.\" Copyright (C) 1998-2003, Carnegie Mellon Univeristy.  All Rights Reserved.
.\" Portions Copyright (C) 2003, Sun Microsystems,
.\" Inc. All Rights Reserved
.\" 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.
.\" 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.
.\" 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]
.TH sasl_client_step 3SASL "28 Aug 2003" "SunOS 5.11" "Simple Authentication Security Layer Library Functions"
.SH NAME
sasl_client_step \- acquire an auxiliary property context
.SH SYNOPSIS
.LP
.nf
\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lsasl\fR   [ \fIlibrary\fR ... ]
#include <sasl/sasl.h>

\fBint\fR \fBsasl_client_step\fR(\fBsasl_conn_t *\fR\fIconn\fR, \fBconst char *\fR\fIserverin\fR,
     \fBsasl_interact_t **\fR\fBunsigned\fR \fIserverinlen\fR, \fIprompt_need\fR,
     \fBconst char **\fR\fIclientout\fR, \fBsasl_interact_t **\fR\fBunsigned *\fR\fIclientoutlen\fR);
.fi

.SH DESCRIPTION
.sp
.LP
Use the \fBsasl_client_step()\fR interface performs a step in the
authentication negotiation. \fBsasl_client_step()\fR returns \fBSASL_OK\fR if
the complete negotiation is successful. If the negotiation on step is completed
successfuly, but at least one more step is required, \fBsasl_client_step()\fR
returns \fBSASL_CONTINUE\fR. A client should not assume an authentication
negotiaion is successful because the server signaled success through the
protocol. For example, if the server signaled \fBOK Authentication succeeded\fR
in IMAP, \fBsasl_client_step()\fR should be called one more time with a
\fIserverinlen\fR of zero.
.sp
.LP
If a call to \fBsasl_client_step()\fR returns \fBSASL_INTERACT\fR, the library
requires some values before \fBsasl_client_step()\fR can proceed. The
\fIprompt_need\fR structure will be filled with the requests. The application
should fulfull these requests and call \fBsasl_client_step()\fR again with
identical parameters. The \fIprompt_need\fR parameter will be the same pointer
as before, but it will have been filled in by the application.
.SH PARAMETERS
.sp
.ne 2
.mk
.na
\fB\fIconn\fR\fR
.ad
.RS 16n
.rt  
The SASL connection context.
.RE

.sp
.ne 2
.mk
.na
\fB\fIserverin\fR\fR
.ad
.RS 16n
.rt  
The data given by the server. The data is decoded if the protocol encodes
requests sent over the wire.
.RE

.sp
.ne 2
.mk
.na
\fB\fIserverinlen\fR\fR
.ad
.RS 16n
.rt  
The length of the \fIserverin\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fIclientout\fR\fR
.ad
.br
.na
\fB\fIclientoutlen\fR\fR
.ad
.RS 16n
.rt  
\fIclientout\fR and \fIclientoutlen\fR are created. They contain the initial
client response to send to the server. It is the job of the client to send them
over the network to the server. Any protocol specific encodingthat is
necessary, for example \fBbase64\fR encoding, must be done by the client.
.RE

.sp
.ne 2
.mk
.na
\fB\fIprompt_need\fR\fR
.ad
.RS 16n
.rt  
A list of prompts that are needed to continue, if necessary.
.RE

.SH RETURN VALUES
.sp
.LP
\fBsasl_client_step()\fR returns an integer that corresponds to a SASL error
code.
.SH ERRORS
.sp
.ne 2
.mk
.na
\fB\fBSASL_OK\fR\fR
.ad
.RS 17n
.rt  
The call to \fBsasl_client_start()\fR was successful. Authentication is
complete.
.RE

.sp
.ne 2
.mk
.na
\fB\fBSASL_CONTINUE\fR\fR
.ad
.RS 17n
.rt  
The call to \fBsasl_client_start()\fR was successful, but at least one more
step is required for authentication.
.RE

.sp
.ne 2
.mk
.na
\fB\fBSASL_INTERACT\fR\fR
.ad
.RS 17n
.rt  
The library requires some values before \fBsasl_client_step()\fR can proceed.
.RE

.sp
.LP
All other error codes indicate an error situation that must be handled, or the
authentication session should be quit. See \fBsasl_errors\fR(3SASL) for
information on SASL error codes.
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Interface StabilityEvolving
_
MT-LevelSafe
.TE

.SH SEE ALSO
.sp
.LP
\fBsasl_errors\fR(3SASL), \fBattributes\fR(5)