Debian Codegraph @

upstream/debian-unstable/man3/SSL_clear.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "SSL_CLEAR 3SSL"
58 .TH SSL_CLEAR 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 SSL_clear \- reset SSL object to allow another connection
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 1
68 \& #include <openssl/ssl.h>
69 \&
70 \& int SSL_clear(SSL *ssl);
71 .Ve
72 .SH DESCRIPTION
73 .IX Header "DESCRIPTION"
74 Reset \fBssl\fR to allow another connection. All settings (method, ciphers,
75 BIOs) are kept.
76 .SH NOTES
77 .IX Header "NOTES"
78 SSL_clear is used to prepare an SSL object for a new connection. While all
79 settings are kept, a side effect is the handling of the current SSL session.
80 If a session is still \fBopen\fR, it is considered bad and will be removed
81 from the session cache, as required by RFC2246. A session is considered open,
82 if \fBSSL_shutdown\fR\|(3) was not called for the connection
83 or at least \fBSSL_set_shutdown\fR\|(3) was used to
84 set the SSL_SENT_SHUTDOWN state.
85 .PP
86 If a session was closed cleanly, the session object will be kept and all
87 settings corresponding. This explicitly means, that e.g. the special method
88 used during the session will be kept for the next handshake. So if the
89 session was a TLSv1 session, an SSL client object will use a TLSv1 client
90 method for the next handshake and an SSL server object will use a TLSv1
91 server method, even if TLS_*_methods were chosen on startup. This
92 will might lead to connection failures (see \fBSSL_new\fR\|(3))
93 for a description of the method's properties.
94 .PP
95 This function is not supported on QUIC SSL objects and returns failure if called
96 on such an object.
97 .SH WARNINGS
98 .IX Header "WARNINGS"
99 \&\fBSSL_clear()\fR resets the SSL object to allow for another connection. The
100 reset operation however keeps several settings of the last sessions
101 (some of these settings were made automatically during the last
102 handshake). It only makes sense for a new connection with the exact
103 same peer that shares these settings, and may fail if that peer
104 changes its settings between connections. Use the sequence
105 \&\fBSSL_get_session\fR\|(3);
106 \&\fBSSL_new\fR\|(3);
107 \&\fBSSL_set_session\fR\|(3);
108 \&\fBSSL_free\fR\|(3)
109 instead to avoid such failures
110 (or simply \fBSSL_free\fR\|(3); \fBSSL_new\fR\|(3)
111 if session reuse is not desired).
112 .SH "RETURN VALUES"
113 .IX Header "RETURN VALUES"
114 The following return values can occur:
115 .IP 0 4
116 The \fBSSL_clear()\fR operation could not be performed. Check the error stack to
117 find out the reason.
118 .IP 1 4
119 .IX Item "1"
120 The \fBSSL_clear()\fR operation was successful.
121 .PP
122 \&\fBSSL_new\fR\|(3), \fBSSL_free\fR\|(3),
123 \&\fBSSL_shutdown\fR\|(3), \fBSSL_set_shutdown\fR\|(3),
124 \&\fBSSL_CTX_set_options\fR\|(3), \fBssl\fR\|(7),
125 \&\fBSSL_CTX_set_client_cert_cb\fR\|(3)
126 .SH COPYRIGHT
127 .IX Header "COPYRIGHT"
128 Copyright 2000\-2023 The OpenSSL Project Authors. All Rights Reserved.
129 .PP
130 Licensed under the Apache License 2.0 (the "License"). You may not use
131 this file except in compliance with the License. You can obtain a copy
132 in the file LICENSE in the source distribution or at
133 <https://www.openssl.org/source/license.html>.