secure/lib/libssl/man/SSL_CTX_set_mode.3

   1 .\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.35)
   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 >0, 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 .if !\nF .nr F 0
  58 .if \nF>0 \{\
  59 .    de IX
  60 .    tm Index:\\$1\t\\n%\t"\\$2"
  61 ..
  62 .    if !\nF==2 \{\
  63 .        nr % 0
  64 .        nr F 2
  65 .    \}
  66 .\}
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "SSL_CTX_set_mode 3"
 132 .TH SSL_CTX_set_mode 3 "2017-11-02" "1.0.2m" "OpenSSL"
 133 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 134 .\" way too many mistakes in technical documents.
 135 .if n .ad l
 136 .nh
 137 .SH "NAME"
 138 SSL_CTX_set_mode, SSL_set_mode, SSL_CTX_get_mode, SSL_get_mode \- manipulate SSL engine mode
 139 .SH "SYNOPSIS"
 140 .IX Header "SYNOPSIS"
 141 .Vb 1
 142 \& #include <openssl/ssl.h>
 143 \&
 144 \& long SSL_CTX_set_mode(SSL_CTX *ctx, long mode);
 145 \& long SSL_set_mode(SSL *ssl, long mode);
 146 \&
 147 \& long SSL_CTX_get_mode(SSL_CTX *ctx);
 148 \& long SSL_get_mode(SSL *ssl);
 149 .Ve
 150 .SH "DESCRIPTION"
 151 .IX Header "DESCRIPTION"
 152 \&\fISSL_CTX_set_mode()\fR adds the mode set via bitmask in \fBmode\fR to \fBctx\fR.
 153 Options already set before are not cleared.
 154 .PP
 155 \&\fISSL_set_mode()\fR adds the mode set via bitmask in \fBmode\fR to \fBssl\fR.
 156 Options already set before are not cleared.
 157 .PP
 158 \&\fISSL_CTX_get_mode()\fR returns the mode set for \fBctx\fR.
 159 .PP
 160 \&\fISSL_get_mode()\fR returns the mode set for \fBssl\fR.
 161 .SH "NOTES"
 162 .IX Header "NOTES"
 163 The following mode changes are available:
 164 .IP "\s-1SSL_MODE_ENABLE_PARTIAL_WRITE\s0" 4
 165 .IX Item "SSL_MODE_ENABLE_PARTIAL_WRITE"
 166 Allow SSL_write(..., n) to return r with 0 < r < n (i.e. report success
 167 when just a single record has been written). When not set (the default),
 168 \&\fISSL_write()\fR will only report success once the complete chunk was written.
 169 Once \fISSL_write()\fR returns with r, r bytes have been successfully written
 170 and the next call to \fISSL_write()\fR must only send the n\-r bytes left,
 171 imitating the behaviour of \fIwrite()\fR.
 172 .IP "\s-1SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER\s0" 4
 173 .IX Item "SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER"
 174 Make it possible to retry \fISSL_write()\fR with changed buffer location
 175 (the buffer contents must stay the same). This is not the default to avoid
 176 the misconception that non-blocking \fISSL_write()\fR behaves like
 177 non-blocking \fIwrite()\fR.
 178 .IP "\s-1SSL_MODE_AUTO_RETRY\s0" 4
 179 .IX Item "SSL_MODE_AUTO_RETRY"
 180 Never bother the application with retries if the transport is blocking.
 181 If a renegotiation take place during normal operation, a
 182 \&\fISSL_read\fR\|(3) or \fISSL_write\fR\|(3) would return
 183 with \-1 and indicate the need to retry with \s-1SSL_ERROR_WANT_READ.\s0
 184 In a non-blocking environment applications must be prepared to handle
 185 incomplete read/write operations.
 186 In a blocking environment, applications are not always prepared to
 187 deal with read/write operations returning without success report. The
 188 flag \s-1SSL_MODE_AUTO_RETRY\s0 will cause read/write operations to only
 189 return after the handshake and successful completion.
 190 .IP "\s-1SSL_MODE_RELEASE_BUFFERS\s0" 4
 191 .IX Item "SSL_MODE_RELEASE_BUFFERS"
 192 When we no longer need a read buffer or a write buffer for a given \s-1SSL,\s0
 193 then release the memory we were using to hold it.  Released memory is
 194 either appended to a list of unused \s-1RAM\s0 chunks on the \s-1SSL_CTX,\s0 or simply
 195 freed if the list of unused chunks would become longer than
 196 \&\s-1SSL_CTX\-\s0>freelist_max_len, which defaults to 32.  Using this flag can
 197 save around 34k per idle \s-1SSL\s0 connection.
 198 This flag has no effect on \s-1SSL\s0 v2 connections, or on \s-1DTLS\s0 connections.
 199 .IP "\s-1SSL_MODE_SEND_FALLBACK_SCSV\s0" 4
 200 .IX Item "SSL_MODE_SEND_FALLBACK_SCSV"
 201 Send \s-1TLS_FALLBACK_SCSV\s0 in the ClientHello.
 202 To be set only by applications that reconnect with a downgraded protocol
 203 version; see draft\-ietf\-tls\-downgrade\-scsv\-00 for details.
 204 .Sp
 205 \&\s-1DO NOT ENABLE THIS\s0 if your application attempts a normal handshake.
 206 Only use this in explicit fallback retries, following the guidance
 207 in draft\-ietf\-tls\-downgrade\-scsv\-00.
 208 .SH "RETURN VALUES"
 209 .IX Header "RETURN VALUES"
 210 \&\fISSL_CTX_set_mode()\fR and \fISSL_set_mode()\fR return the new mode bitmask
 211 after adding \fBmode\fR.
 212 .PP
 213 \&\fISSL_CTX_get_mode()\fR and \fISSL_get_mode()\fR return the current bitmask.
 214 .SH "SEE ALSO"
 215 .IX Header "SEE ALSO"
 216 \&\fIssl\fR\|(3), \fISSL_read\fR\|(3), \fISSL_write\fR\|(3)
 217 .SH "HISTORY"
 218 .IX Header "HISTORY"
 219 \&\s-1SSL_MODE_AUTO_RETRY\s0 as been added in OpenSSL 0.9.6.