951dd6b0c4938ef8d7bded6ddb0a4c971478cc6b
[dragonfly.git] / secure / lib / libssl / man / SSL_clear.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_clear 3"
136 .TH SSL_clear 3 "2015-06-11" "1.0.1n" "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_clear \- reset SSL object to allow another connection
143 .SH "SYNOPSIS"
144 .IX Header "SYNOPSIS"
145 .Vb 1
146 \& #include <openssl/ssl.h>
147 \&
148 \& int SSL_clear(SSL *ssl);
149 .Ve
150 .SH "DESCRIPTION"
151 .IX Header "DESCRIPTION"
152 Reset \fBssl\fR to allow another connection. All settings (method, ciphers,
153 BIOs) are kept.
154 .SH "NOTES"
155 .IX Header "NOTES"
156 SSL_clear is used to prepare an \s-1SSL\s0 object for a new connection. While all
157 settings are kept, a side effect is the handling of the current \s-1SSL\s0 session.
158 If a session is still \fBopen\fR, it is considered bad and will be removed
159 from the session cache, as required by \s-1RFC2246. A\s0 session is considered open,
160 if \fISSL_shutdown\fR\|(3) was not called for the connection
161 or at least \fISSL_set_shutdown\fR\|(3) was used to
162 set the \s-1SSL_SENT_SHUTDOWN\s0 state.
163 .PP
164 If a session was closed cleanly, the session object will be kept and all
165 settings corresponding. This explicitly means, that e.g. the special method
166 used during the session will be kept for the next handshake. So if the
167 session was a TLSv1 session, a \s-1SSL\s0 client object will use a TLSv1 client
168 method for the next handshake and a \s-1SSL\s0 server object will use a TLSv1
169 server method, even if SSLv23_*_methods were chosen on startup. This
170 will might lead to connection failures (see \fISSL_new\fR\|(3))
171 for a description of the method's properties.
172 .SH "WARNINGS"
173 .IX Header "WARNINGS"
174 \&\fISSL_clear()\fR resets the \s-1SSL\s0 object to allow for another connection. The
175 reset operation however keeps several settings of the last sessions
176 (some of these settings were made automatically during the last
177 handshake). It only makes sense for a new connection with the exact
178 same peer that shares these settings, and may fail if that peer
179 changes its settings between connections. Use the sequence
180 \&\fISSL_get_session\fR\|(3);
181 \&\fISSL_new\fR\|(3);
182 \&\fISSL_set_session\fR\|(3);
183 \&\fISSL_free\fR\|(3)
184 instead to avoid such failures
185 (or simply \fISSL_free\fR\|(3); \fISSL_new\fR\|(3)
186 if session reuse is not desired).
187 .SH "RETURN VALUES"
188 .IX Header "RETURN VALUES"
189 The following return values can occur:
190 .IP "0" 4
191 The \fISSL_clear()\fR operation could not be performed. Check the error stack to
192 find out the reason.
193 .IP "1" 4
194 .IX Item "1"
195 The \fISSL_clear()\fR operation was successful.
196 .PP
197 \&\fISSL_new\fR\|(3), \fISSL_free\fR\|(3),
198 \&\fISSL_shutdown\fR\|(3), \fISSL_set_shutdown\fR\|(3),
199 \&\fISSL_CTX_set_options\fR\|(3), \fIssl\fR\|(3),
200 \&\fISSL_CTX_set_client_cert_cb\fR\|(3)