secure/lib/libssl/man/SSL_accept.3

   1 .rn '' }`
   2 ''' $RCSfile$$Revision$$Date$
   3 '''
   4 ''' $Log$
   5 '''
   6 .de Sh
   7 .br
   8 .if t .Sp
   9 .ne 5
  10 .PP
  11 \fB\\$1\fR
  12 .PP
  13 ..
  14 .de Sp
  15 .if t .sp .5v
  16 .if n .sp
  17 ..
  18 .de Ip
  19 .br
  20 .ie \\n(.$>=3 .ne \\$3
  21 .el .ne 3
  22 .IP "\\$1" \\$2
  23 ..
  24 .de Vb
  25 .ft CW
  26 .nf
  27 .ne \\$1
  28 ..
  29 .de Ve
  30 .ft R
  31
  32 .fi
  33 ..
  34 '''
  35 '''
  36 '''     Set up \*(-- to give an unbreakable dash;
  37 '''     string Tr holds user defined translation string.
  38 '''     Bell System Logo is used as a dummy character.
  39 '''
  40 .tr \(*W-|\(bv\*(Tr
  41 .ie n \{\
  42 .ds -- \(*W-
  43 .ds PI pi
  44 .if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  45 .if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
  46 .ds L" ""
  47 .ds R" ""
  48 '''   \*(M", \*(S", \*(N" and \*(T" are the equivalent of
  49 '''   \*(L" and \*(R", except that they are used on ".xx" lines,
  50 '''   such as .IP and .SH, which do another additional levels of
  51 '''   double-quote interpretation
  52 .ds M" """
  53 .ds S" """
  54 .ds N" """""
  55 .ds T" """""
  56 .ds L' '
  57 .ds R' '
  58 .ds M' '
  59 .ds S' '
  60 .ds N' '
  61 .ds T' '
  62 'br\}
  63 .el\{\
  64 .ds -- \(em\|
  65 .tr \*(Tr
  66 .ds L" ``
  67 .ds R" ''
  68 .ds M" ``
  69 .ds S" ''
  70 .ds N" ``
  71 .ds T" ''
  72 .ds L' `
  73 .ds R' '
  74 .ds M' `
  75 .ds S' '
  76 .ds N' `
  77 .ds T' '
  78 .ds PI \(*p
  79 'br\}
  80 .\"     If the F register is turned on, we'll generate
  81 .\"     index entries out stderr for the following things:
  82 .\"             TH      Title
  83 .\"             SH      Header
  84 .\"             Sh      Subsection
  85 .\"             Ip      Item
  86 .\"             X<>     Xref  (embedded
  87 .\"     Of course, you have to process the output yourself
  88 .\"     in some meaninful fashion.
  89 .if \nF \{
  90 .de IX
  91 .tm Index:\\$1\t\\n%\t"\\$2"
  92 ..
  93 .nr % 0
  94 .rr F
  95 .\}
  96 .TH SSL_accept 3 "0.9.7d" "2/Sep/2004" "OpenSSL"
  97 .UC
  98 .if n .hy 0
  99 .if n .na
 100 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
 101 .de CQ          \" put $1 in typewriter font
 102 .ft CW
 103 'if n "\c
 104 'if t \\&\\$1\c
 105 'if n \\&\\$1\c
 106 'if n \&"
 107 \\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
 108 '.ft R
 109 ..
 110 .\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
 111 .       \" AM - accent mark definitions
 112 .bd B 3
 113 .       \" fudge factors for nroff and troff
 114 .if n \{\
 115 .       ds #H 0
 116 .       ds #V .8m
 117 .       ds #F .3m
 118 .       ds #[ \f1
 119 .       ds #] \fP
 120 .\}
 121 .if t \{\
 122 .       ds #H ((1u-(\\\\n(.fu%2u))*.13m)
 123 .       ds #V .6m
 124 .       ds #F 0
 125 .       ds #[ \&
 126 .       ds #] \&
 127 .\}
 128 .       \" simple accents for nroff and troff
 129 .if n \{\
 130 .       ds ' \&
 131 .       ds ` \&
 132 .       ds ^ \&
 133 .       ds , \&
 134 .       ds ~ ~
 135 .       ds ? ?
 136 .       ds ! !
 137 .       ds /
 138 .       ds q
 139 .\}
 140 .if t \{\
 141 .       ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 142 .       ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 143 .       ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 144 .       ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 145 .       ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 146 .       ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
 147 .       ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
 148 .       ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 149 .       ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
 150 .\}
 151 .       \" troff and (daisy-wheel) nroff accents
 152 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 153 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 154 .ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
 155 .ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
 156 .ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
 157 .ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
 158 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 159 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 160 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 161 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 162 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 163 .ds ae a\h'-(\w'a'u*4/10)'e
 164 .ds Ae A\h'-(\w'A'u*4/10)'E
 165 .ds oe o\h'-(\w'o'u*4/10)'e
 166 .ds Oe O\h'-(\w'O'u*4/10)'E
 167 .       \" corrections for vroff
 168 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 169 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 170 .       \" for low resolution devices (crt and lpr)
 171 .if \n(.H>23 .if \n(.V>19 \
 172 \{\
 173 .       ds : e
 174 .       ds 8 ss
 175 .       ds v \h'-1'\o'\(aa\(ga'
 176 .       ds _ \h'-1'^
 177 .       ds . \h'-1'.
 178 .       ds 3 3
 179 .       ds o a
 180 .       ds d- d\h'-1'\(ga
 181 .       ds D- D\h'-1'\(hy
 182 .       ds th \o'bp'
 183 .       ds Th \o'LP'
 184 .       ds ae ae
 185 .       ds Ae AE
 186 .       ds oe oe
 187 .       ds Oe OE
 188 .\}
 189 .rm #[ #] #H #V #F C
 190 .SH "NAME"
 191 SSL_accept \- wait for a TLS/SSL client to initiate a TLS/SSL handshake
 192 .SH "SYNOPSIS"
 193 .PP
 194 .Vb 1
 195 \& #include <openssl/ssl.h>
 196 .Ve
 197 .Vb 1
 198 \& int SSL_accept(SSL *ssl);
 199 .Ve
 200 .SH "DESCRIPTION"
 201 \fISSL_accept()\fR waits for a TLS/SSL client to initiate the TLS/SSL handshake.
 202 The communication channel must already have been set and assigned to the
 203 \fBssl\fR by setting an underlying \fBBIO\fR.
 204 .SH "NOTES"
 205 The behaviour of \fISSL_accept()\fR depends on the underlying BIO.
 206 .PP
 207 If the underlying BIO is \fBblocking\fR, \fISSL_accept()\fR will only return once the
 208 handshake has been finished or an error occurred, except for SGC (Server
 209 Gated Cryptography). For SGC, \fISSL_accept()\fR may return with \-1, but
 210 \fISSL_get_error()\fR will yield \fBSSL_ERROR_WANT_READ/WRITE\fR and \fISSL_accept()\fR
 211 should be called again.
 212 .PP
 213 If the underlying BIO is \fBnon-blocking\fR, \fISSL_accept()\fR will also return
 214 when the underlying BIO could not satisfy the needs of \fISSL_accept()\fR
 215 to continue the handshake, indicating the problem by the return value \-1.
 216 In this case a call to \fISSL_get_error()\fR with the
 217 return value of \fISSL_accept()\fR will yield \fBSSL_ERROR_WANT_READ\fR or
 218 \fBSSL_ERROR_WANT_WRITE\fR. The calling process then must repeat the call after
 219 taking appropriate action to satisfy the needs of \fISSL_accept()\fR.
 220 The action depends on the underlying BIO. When using a non-blocking socket,
 221 nothing is to be done, but \fIselect()\fR can be used to check for the required
 222 condition. When using a buffering BIO, like a BIO pair, data must be written
 223 into or retrieved out of the BIO before being able to continue.
 224 .SH "RETURN VALUES"
 225 The following return values can occur:
 226 .Ip "1" 4
 227 The \s-1TLS/SSL\s0 handshake was successfully completed, a \s-1TLS/SSL\s0 connection has been
 228 established.
 229 .Ip "0" 4
 230 The \s-1TLS/SSL\s0 handshake was not successful but was shut down controlled and
 231 by the specifications of the \s-1TLS/SSL\s0 protocol. Call \fISSL_get_error()\fR with the
 232 return value \fBret\fR to find out the reason.
 233 .Ip "<0" 4
 234 The \s-1TLS/SSL\s0 handshake was not successful because a fatal error occurred either
 235 at the protocol level or a connection failure occurred. The shutdown was
 236 not clean. It can also occur of action is need to continue the operation
 237 for non-blocking BIOs. Call \fISSL_get_error()\fR with the return value \fBret\fR
 238 to find out the reason.
 239 .SH "SEE ALSO"
 240 SSL_get_error(3), SSL_connect(3),
 241 SSL_shutdown(3), ssl(3), bio(3),
 242 SSL_set_connect_state(3),
 243 SSL_do_handshake(3),
 244 SSL_CTX_new(3)
 245
 246 .rn }` ''
 247 .IX Title "SSL_accept 3"
 248 .IX Name "SSL_accept - wait for a TLS/SSL client to initiate a TLS/SSL handshake"
 249
 250 .IX Header "NAME"
 251
 252 .IX Header "SYNOPSIS"
 253
 254 .IX Header "DESCRIPTION"
 255
 256 .IX Header "NOTES"
 257
 258 .IX Header "RETURN VALUES"
 259
 260 .IX Item "1"
 261
 262 .IX Item "0"
 263
 264 .IX Item "<0"
 265
 266 .IX Header "SEE ALSO"
 267