secure/lib/libssl/man/SSL_CTX_set_mode.3

   1 .\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 .    ds C`
  42 .    ds C'
  43 'br\}
  44 .\"
  45 .\" Escape single quotes in literal strings from groff's Unicode transform.
  46 .ie \n(.g .ds Aq \(aq
  47 .el       .ds Aq '
  48 .\"
  49 .\" If the F register is turned on, we'll generate index entries on stderr for
  50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  52 .\" output yourself in some meaningful fashion.
  53 .\"
  54 .\" Avoid warning from groff about undefined register 'F'.
  55 .de IX
  56 ..
  57 .nr rF 0
  58 .if \n(.g .if rF .nr rF 1
  59 .if (\n(rF:(\n(.g==0)) \{
  60 .    if \nF \{
  61 .        de IX
  62 .        tm Index:\\$1\t\\n%\t"\\$2"
  63 ..
  64 .        if !\nF==2 \{
  65 .            nr % 0
  66 .            nr F 2
  67 .        \}
  68 .    \}
  69 .\}
  70 .rr rF
  71 .\"
  72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  73 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  74 .    \" fudge factors for nroff and troff
  75 .if n \{\
  76 .    ds #H 0
  77 .    ds #V .8m
  78 .    ds #F .3m
  79 .    ds #[ \f1
  80 .    ds #] \fP
  81 .\}
  82 .if t \{\
  83 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  84 .    ds #V .6m
  85 .    ds #F 0
  86 .    ds #[ \&
  87 .    ds #] \&
  88 .\}
  89 .    \" simple accents for nroff and troff
  90 .if n \{\
  91 .    ds ' \&
  92 .    ds ` \&
  93 .    ds ^ \&
  94 .    ds , \&
  95 .    ds ~ ~
  96 .    ds /
  97 .\}
  98 .if t \{\
  99 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 100 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 101 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 102 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 103 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 104 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 105 .\}
 106 .    \" troff and (daisy-wheel) nroff accents
 107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 114 .ds ae a\h'-(\w'a'u*4/10)'e
 115 .ds Ae A\h'-(\w'A'u*4/10)'E
 116 .    \" corrections for vroff
 117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 119 .    \" for low resolution devices (crt and lpr)
 120 .if \n(.H>23 .if \n(.V>19 \
 121 \{\
 122 .    ds : e
 123 .    ds 8 ss
 124 .    ds o a
 125 .    ds d- d\h'-1'\(ga
 126 .    ds D- D\h'-1'\(hy
 127 .    ds th \o'bp'
 128 .    ds Th \o'LP'
 129 .    ds ae ae
 130 .    ds Ae AE
 131 .\}
 132 .rm #[ #] #H #V #F C
 133 .\" ========================================================================
 134 .\"
 135 .IX Title "SSL_CTX_set_mode 3"
 136 .TH SSL_CTX_set_mode 3 "2016-01-28" "1.0.1r" "OpenSSL"
 137 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 138 .\" way too many mistakes in technical documents.
 139 .if n .ad l
 140 .nh
 141 .SH "NAME"
 142 SSL_CTX_set_mode, SSL_set_mode, SSL_CTX_get_mode, SSL_get_mode \- manipulate SSL engine mode
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 1
 146 \& #include <openssl/ssl.h>
 147 \&
 148 \& long SSL_CTX_set_mode(SSL_CTX *ctx, long mode);
 149 \& long SSL_set_mode(SSL *ssl, long mode);
 150 \&
 151 \& long SSL_CTX_get_mode(SSL_CTX *ctx);
 152 \& long SSL_get_mode(SSL *ssl);
 153 .Ve
 154 .SH "DESCRIPTION"
 155 .IX Header "DESCRIPTION"
 156 \&\fISSL_CTX_set_mode()\fR adds the mode set via bitmask in \fBmode\fR to \fBctx\fR.
 157 Options already set before are not cleared.
 158 .PP
 159 \&\fISSL_set_mode()\fR adds the mode set via bitmask in \fBmode\fR to \fBssl\fR.
 160 Options already set before are not cleared.
 161 .PP
 162 \&\fISSL_CTX_get_mode()\fR returns the mode set for \fBctx\fR.
 163 .PP
 164 \&\fISSL_get_mode()\fR returns the mode set for \fBssl\fR.
 165 .SH "NOTES"
 166 .IX Header "NOTES"
 167 The following mode changes are available:
 168 .IP "\s-1SSL_MODE_ENABLE_PARTIAL_WRITE\s0" 4
 169 .IX Item "SSL_MODE_ENABLE_PARTIAL_WRITE"
 170 Allow SSL_write(..., n) to return r with 0 < r < n (i.e. report success
 171 when just a single record has been written). When not set (the default),
 172 \&\fISSL_write()\fR will only report success once the complete chunk was written.
 173 Once \fISSL_write()\fR returns with r, r bytes have been successfully written
 174 and the next call to \fISSL_write()\fR must only send the n\-r bytes left,
 175 imitating the behaviour of \fIwrite()\fR.
 176 .IP "\s-1SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER\s0" 4
 177 .IX Item "SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER"
 178 Make it possible to retry \fISSL_write()\fR with changed buffer location
 179 (the buffer contents must stay the same). This is not the default to avoid
 180 the misconception that non-blocking \fISSL_write()\fR behaves like
 181 non-blocking \fIwrite()\fR.
 182 .IP "\s-1SSL_MODE_AUTO_RETRY\s0" 4
 183 .IX Item "SSL_MODE_AUTO_RETRY"
 184 Never bother the application with retries if the transport is blocking.
 185 If a renegotiation take place during normal operation, a
 186 \&\fISSL_read\fR\|(3) or \fISSL_write\fR\|(3) would return
 187 with \-1 and indicate the need to retry with \s-1SSL_ERROR_WANT_READ.\s0
 188 In a non-blocking environment applications must be prepared to handle
 189 incomplete read/write operations.
 190 In a blocking environment, applications are not always prepared to
 191 deal with read/write operations returning without success report. The
 192 flag \s-1SSL_MODE_AUTO_RETRY\s0 will cause read/write operations to only
 193 return after the handshake and successful completion.
 194 .IP "\s-1SSL_MODE_RELEASE_BUFFERS\s0" 4
 195 .IX Item "SSL_MODE_RELEASE_BUFFERS"
 196 When we no longer need a read buffer or a write buffer for a given \s-1SSL,\s0
 197 then release the memory we were using to hold it.  Released memory is
 198 either appended to a list of unused \s-1RAM\s0 chunks on the \s-1SSL_CTX,\s0 or simply
 199 freed if the list of unused chunks would become longer than
 200 \&\s-1SSL_CTX\-\s0>freelist_max_len, which defaults to 32.  Using this flag can
 201 save around 34k per idle \s-1SSL\s0 connection.
 202 This flag has no effect on \s-1SSL\s0 v2 connections, or on \s-1DTLS\s0 connections.
 203 .IP "\s-1SSL_MODE_SEND_FALLBACK_SCSV\s0" 4
 204 .IX Item "SSL_MODE_SEND_FALLBACK_SCSV"
 205 Send \s-1TLS_FALLBACK_SCSV\s0 in the ClientHello.
 206 To be set only by applications that reconnect with a downgraded protocol
 207 version; see draft\-ietf\-tls\-downgrade\-scsv\-00 for details.
 208 .Sp
 209 \&\s-1DO NOT ENABLE THIS\s0 if your application attempts a normal handshake.
 210 Only use this in explicit fallback retries, following the guidance
 211 in draft\-ietf\-tls\-downgrade\-scsv\-00.
 212 .SH "RETURN VALUES"
 213 .IX Header "RETURN VALUES"
 214 \&\fISSL_CTX_set_mode()\fR and \fISSL_set_mode()\fR return the new mode bitmask
 215 after adding \fBmode\fR.
 216 .PP
 217 \&\fISSL_CTX_get_mode()\fR and \fISSL_get_mode()\fR return the current bitmask.
 218 .SH "SEE ALSO"
 219 .IX Header "SEE ALSO"
 220 \&\fIssl\fR\|(3), \fISSL_read\fR\|(3), \fISSL_write\fR\|(3)
 221 .SH "HISTORY"
 222 .IX Header "HISTORY"
 223 \&\s-1SSL_MODE_AUTO_RETRY\s0 as been added in OpenSSL 0.9.6.