lib/libssl/man/SSL_get_state.3

   1 .\"     $OpenBSD: SSL_get_state.3,v 1.3 2018/03/21 08:06:34 schwarze Exp $
   2 .\"
   3 .\" Copyright (c) 2016 Ingo Schwarze <schwarze@openbsd.org>
   4 .\"
   5 .\" Permission to use, copy, modify, and distribute this software for any
   6 .\" purpose with or without fee is hereby granted, provided that the above
   7 .\" copyright notice and this permission notice appear in all copies.
   8 .\"
   9 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  10 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  11 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  12 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  13 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  14 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  15 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  16 .\"
  17 .Dd $Mdocdate: March 21 2018 $
  18 .Dt SSL_GET_STATE 3
  19 .Os
  20 .Sh NAME
  21 .Nm SSL_get_state ,
  22 .Nm SSL_state ,
  23 .Nm SSL_in_accept_init ,
  24 .Nm SSL_in_before ,
  25 .Nm SSL_in_connect_init ,
  26 .Nm SSL_in_init ,
  27 .Nm SSL_is_init_finished
  28 .Nd inspect the state of the SSL state machine
  29 .Sh SYNOPSIS
  30 .In openssl/ssl.h
  31 .Ft int
  32 .Fo SSL_get_state
  33 .Fa "const SSL *ssl"
  34 .Fc
  35 .Ft int
  36 .Fo SSL_state
  37 .Fa "const SSL *ssl"
  38 .Fc
  39 .Ft int
  40 .Fo SSL_in_accept_init
  41 .Fa "const SSL *ssl"
  42 .Fc
  43 .Ft int
  44 .Fo SSL_in_before
  45 .Fa "const SSL *ssl"
  46 .Fc
  47 .Ft int
  48 .Fo SSL_in_connect_init
  49 .Fa "const SSL *ssl"
  50 .Fc
  51 .Ft int
  52 .Fo SSL_in_init
  53 .Fa "const SSL *ssl"
  54 .Fc
  55 .Ft int
  56 .Fo SSL_is_init_finished
  57 .Fa "const SSL *ssl"
  58 .Fc
  59 .Sh DESCRIPTION
  60 .Fn SSL_get_state
  61 returns an encoded representation of the current state of the SSL
  62 state machine.
  63 .Fn SSL_state
  64 is a deprecated alias for
  65 .Fn SSL_get_state .
  66 .Pp
  67 The following bits may be set:
  68 .Bl -tag -width Ds
  69 .It Dv SSL_ST_ACCEPT
  70 This bit is set by
  71 .Xr SSL_accept 3
  72 and by
  73 .Xr SSL_set_accept_state 3 .
  74 It indicates that
  75 .Fa ssl
  76 is set up for server mode and no client initiated the TLS handshake yet.
  77 The function
  78 .Fn SSL_in_accept_init
  79 returns non-zero if this bit is set or 0 otherwise.
  80 .It Dv SSL_ST_BEFORE
  81 This bit is set by the
  82 .Xr SSL_accept 3 ,
  83 .Xr SSL_connect 3 ,
  84 .Xr SSL_set_accept_state 3 ,
  85 and
  86 .Xr SSL_set_connect_state 3
  87 functions.
  88 It indicates that the TLS handshake was not initiated yet.
  89 The function
  90 .Fn SSL_in_before
  91 returns non-zero if this bit is set or 0 otherwise.
  92 .It Dv SSL_ST_CONNECT
  93 This bit is set by
  94 .Xr SSL_connect 3
  95 and by
  96 .Xr SSL_set_connect_state 3 .
  97 It indicates that
  98 .Fa ssl
  99 is set up for client mode and no TLS handshake was initiated yet.
 100 The function
 101 .Fn SSL_in_connect_init
 102 returns non-zero if this bit is set or 0 otherwise.
 103 .El
 104 .Pp
 105 The following masks can be used:
 106 .Bl -tag -width Ds
 107 .It Dv SSL_ST_INIT
 108 Set if
 109 .Dv SSL_ST_ACCEPT
 110 or
 111 .Dv SSL_ST_CONNECT
 112 is set.
 113 The function
 114 .Fn SSL_in_init
 115 returns a non-zero value if one of these is set or 0 otherwise.
 116 .It Dv SSL_ST_MASK
 117 This mask includes all bits except
 118 .Dv SSL_ST_ACCEPT ,
 119 .Dv SSL_ST_BEFORE ,
 120 and
 121 .Dv SSL_ST_CONNECT .
 122 .It Dv SSL_ST_OK
 123 The state is set to this value when a connection is established.
 124 The function
 125 .Fn SSL_is_init_finished
 126 returns a non-zero value if the state equals this constant, or 0 otherwise.
 127 .It Dv SSL_ST_RENEGOTIATE
 128 The program is about to renegotiate, for example when entering
 129 .Xr SSL_read 3
 130 or
 131 .Xr SSL_write 3
 132 right after
 133 .Xr SSL_renegotiate 3
 134 was called.
 135 .El
 136 .Pp
 137 The meaning of other bits is protocol-dependent.
 138 Application programs usually do not need to inspect any of those
 139 other bits.
 140 .Pp
 141 All these functions may be implemented as macros.
 142 .Sh SEE ALSO
 143 .Xr SSL_renegotiate 3 ,
 144 .Xr SSL_set_connect_state 3
 145 .Sh HISTORY
 146 .Fn SSL_state ,
 147 .Fn SSL_in_accept_init ,
 148 .Fn SSL_in_before ,
 149 .Fn SSL_in_connect_init ,
 150 .Fn SSL_in_init ,
 151 and
 152 .Fn SSL_is_init_finished
 153 appeared before SSLeay 0.8.
 154 .Fn SSL_get_state
 155 first appeared in SSLeay 0.9.0.
 156 These functions have been available since
 157 .Ox 2.4 .