'\" te
.\" Copyright (C) 1998-2003, Carnegie Mellon Univeristy.  All Rights Reserved.
.\" Portions Copyright (C) 2003, Sun Microsystems, Inc. All Rights Reserved
.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
_
Availabilitysystem/library/security/libsasl
_
Interface StabilityCommitted
_
MT-LevelSafe
.TE

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