share/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 "Nov 26, 2017"
   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 .LP
  24 Use the \fBsasl_client_step()\fR interface performs a step in the
  25 authentication negotiation. \fBsasl_client_step()\fR returns \fBSASL_OK\fR if
  26 the complete negotiation is successful. If the negotiation on step is completed
  27 successfully, but at least one more step is required, \fBsasl_client_step()\fR
  28 returns \fBSASL_CONTINUE\fR. A client should not assume an authentication
  29 negotiaion is successful because the server signaled success through the
  30 protocol. For example, if the server signaled \fBOK Authentication succeeded\fR
  31 in IMAP, \fBsasl_client_step()\fR should be called one more time with a
  32 \fIserverinlen\fR of zero.
  33 .sp
  34 .LP
  35 If a call to \fBsasl_client_step()\fR returns \fBSASL_INTERACT\fR, the library
  36 requires some values before \fBsasl_client_step()\fR can proceed. The
  37 \fIprompt_need\fR structure will be filled with the requests. The application
  38 should fulfull these requests and call \fBsasl_client_step()\fR again with
  39 identical parameters. The \fIprompt_need\fR parameter will be the same pointer
  40 as before, but it will have been filled in by the application.
  41 .SH PARAMETERS
  42 .ne 2
  43 .na
  44 \fB\fIconn\fR\fR
  45 .ad
  46 .RS 16n
  47 The SASL connection context.
  48 .RE
  49
  50 .sp
  51 .ne 2
  52 .na
  53 \fB\fIserverin\fR\fR
  54 .ad
  55 .RS 16n
  56 The data given by the server. The data is decoded if the protocol encodes
  57 requests sent over the wire.
  58 .RE
  59
  60 .sp
  61 .ne 2
  62 .na
  63 \fB\fIserverinlen\fR\fR
  64 .ad
  65 .RS 16n
  66 The length of the \fIserverin\fR.
  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 .RE
  84
  85 .sp
  86 .ne 2
  87 .na
  88 \fB\fIprompt_need\fR\fR
  89 .ad
  90 .RS 16n
  91 A list of prompts that are needed to continue, if necessary.
  92 .RE
  93
  94 .SH RETURN VALUES
  95 .LP
  96 \fBsasl_client_step()\fR returns an integer that corresponds to a SASL error
  97 code.
  98 .SH ERRORS
  99 .ne 2
 100 .na
 101 \fB\fBSASL_OK\fR\fR
 102 .ad
 103 .RS 17n
 104 The call to \fBsasl_client_start()\fR was successful. Authentication is
 105 complete.
 106 .RE
 107
 108 .sp
 109 .ne 2
 110 .na
 111 \fB\fBSASL_CONTINUE\fR\fR
 112 .ad
 113 .RS 17n
 114 The call to \fBsasl_client_start()\fR was successful, but at least one more
 115 step is required for authentication.
 116 .RE
 117
 118 .sp
 119 .ne 2
 120 .na
 121 \fB\fBSASL_INTERACT\fR\fR
 122 .ad
 123 .RS 17n
 124 The library requires some values before \fBsasl_client_step()\fR can proceed.
 125 .RE
 126
 127 .sp
 128 .LP
 129 All other error codes indicate an error situation that must be handled, or the
 130 authentication session should be quit. See \fBsasl_errors\fR(3SASL) for
 131 information on SASL error codes.
 132 .SH ATTRIBUTES
 133 .LP
 134 See \fBattributes\fR(5) for descriptions of the following attributes:
 135 .sp
 136
 137 .sp
 138 .TS
 139 box;
 140 c | c
 141 l | l .
 142 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 143 _
 144 Interface Stability     Evolving
 145 _
 146 MT-Level        Safe
 147 .TE
 148
 149 .SH SEE ALSO
 150 .LP
 151 \fBsasl_errors\fR(3SASL), \fBattributes\fR(5)