openssl: Adjust manual pages for 1.0.1o.
[dragonfly.git] / secure / lib / libssl / man / SSL_CTX_set_mode.3
1 .\" Automatically generated by Pod::Man 2.27 (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 "2015-06-12" "1.0.1o" "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.