Merge from vendor branch OPENSSL:
[dragonfly.git] / secure / lib / libssl / man / SSL_get_session.3
CommitLineData
e056f0e0
JR
1.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14
2.\"
3.\" Standard preamble:
4.\" ========================================================================
5.de Sh \" Subsection heading
984263bc
MD
6.br
7.if t .Sp
8.ne 5
9.PP
10\fB\\$1\fR
11.PP
12..
e056f0e0 13.de Sp \" Vertical space (when we can't use .PP)
984263bc
MD
14.if t .sp .5v
15.if n .sp
16..
e056f0e0 17.de Vb \" Begin verbatim text
984263bc
MD
18.ft CW
19.nf
20.ne \\$1
21..
e056f0e0 22.de Ve \" End verbatim text
984263bc 23.ft R
984263bc
MD
24.fi
25..
e056f0e0
JR
26.\" Set up some character translations and predefined strings. \*(-- will
27.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
28.\" double quote, and \*(R" will give a right double quote. | will give a
29.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
30.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
31.\" expand to `' in nroff, nothing in troff, for use with C<>.
984263bc 32.tr \(*W-|\(bv\*(Tr
e056f0e0 33.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
984263bc 34.ie n \{\
e056f0e0
JR
35. ds -- \(*W-
36. ds PI pi
37. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
39. ds L" ""
40. ds R" ""
41. ds C` ""
42. ds C' ""
984263bc
MD
43'br\}
44.el\{\
e056f0e0
JR
45. ds -- \|\(em\|
46. ds PI \(*p
47. ds L" ``
48. ds R" ''
984263bc 49'br\}
e056f0e0
JR
50.\"
51.\" If the F register is turned on, we'll generate index entries on stderr for
52.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
53.\" entries marked with X<> in POD. Of course, you'll have to process the
54.\" output yourself in some meaningful fashion.
55.if \nF \{\
56. de IX
57. tm Index:\\$1\t\\n%\t"\\$2"
984263bc 58..
e056f0e0
JR
59. nr % 0
60. rr F
984263bc 61.\}
e056f0e0
JR
62.\"
63.\" For nroff, turn off justification. Always turn off hyphenation; it makes
64.\" way too many mistakes in technical documents.
65.hy 0
984263bc 66.if n .na
e056f0e0
JR
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
984263bc 71.if n \{\
e056f0e0
JR
72. ds #H 0
73. ds #V .8m
74. ds #F .3m
75. ds #[ \f1
76. ds #] \fP
984263bc
MD
77.\}
78.if t \{\
e056f0e0
JR
79. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
80. ds #V .6m
81. ds #F 0
82. ds #[ \&
83. ds #] \&
984263bc 84.\}
e056f0e0 85. \" simple accents for nroff and troff
984263bc 86.if n \{\
e056f0e0
JR
87. ds ' \&
88. ds ` \&
89. ds ^ \&
90. ds , \&
91. ds ~ ~
92. ds /
984263bc
MD
93.\}
94.if t \{\
e056f0e0
JR
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'
984263bc 101.\}
e056f0e0 102. \" troff and (daisy-wheel) nroff accents
984263bc
MD
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
e056f0e0 112. \" corrections for vroff
984263bc
MD
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'
e056f0e0 115. \" for low resolution devices (crt and lpr)
984263bc
MD
116.if \n(.H>23 .if \n(.V>19 \
117\{\
e056f0e0
JR
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
984263bc
MD
127.\}
128.rm #[ #] #H #V #F C
e056f0e0
JR
129.\" ========================================================================
130.\"
131.IX Title "SSL_get_session 3"
132.TH SSL_get_session 3 "2004-12-22" "0.9.7e" "OpenSSL"
984263bc 133.SH "NAME"
a7d27d5a 134SSL_get_session \- retrieve TLS/SSL session data
984263bc 135.SH "SYNOPSIS"
e056f0e0 136.IX Header "SYNOPSIS"
984263bc
MD
137.Vb 1
138\& #include <openssl/ssl.h>
139.Ve
e056f0e0 140.PP
984263bc
MD
141.Vb 3
142\& SSL_SESSION *SSL_get_session(SSL *ssl);
143\& SSL_SESSION *SSL_get0_session(SSL *ssl);
144\& SSL_SESSION *SSL_get1_session(SSL *ssl);
145.Ve
146.SH "DESCRIPTION"
e056f0e0
JR
147.IX Header "DESCRIPTION"
148\&\fISSL_get_session()\fR returns a pointer to the \fB\s-1SSL_SESSION\s0\fR actually used in
149\&\fBssl\fR. The reference count of the \fB\s-1SSL_SESSION\s0\fR is not incremented, so
984263bc
MD
150that the pointer can become invalid by other operations.
151.PP
e056f0e0 152\&\fISSL_get0_session()\fR is the same as \fISSL_get_session()\fR.
984263bc 153.PP
e056f0e0
JR
154\&\fISSL_get1_session()\fR is the same as \fISSL_get_session()\fR, but the reference
155count of the \fB\s-1SSL_SESSION\s0\fR is incremented by one.
984263bc 156.SH "NOTES"
e056f0e0 157.IX Header "NOTES"
984263bc
MD
158The ssl session contains all information required to re-establish the
159connection without a new handshake.
160.PP
e056f0e0 161\&\fISSL_get0_session()\fR returns a pointer to the actual session. As the
984263bc 162reference counter is not incremented, the pointer is only valid while
e056f0e0
JR
163the connection is in use. If \fISSL_clear\fR\|(3) or
164\&\fISSL_free\fR\|(3) is called, the session may be removed completely
984263bc
MD
165(if considered bad), and the pointer obtained will become invalid. Even
166if the session is valid, it can be removed at any time due to timeout
e056f0e0 167during \fISSL_CTX_flush_sessions\fR\|(3).
984263bc
MD
168.PP
169If the data is to be kept, \fISSL_get1_session()\fR will increment the reference
170count, so that the session will not be implicitly removed by other operations
171but stays in memory. In order to remove the session
e056f0e0 172\&\fISSL_SESSION_free\fR\|(3) must be explicitly called once
984263bc
MD
173to decrement the reference count again.
174.PP
e056f0e0
JR
175\&\s-1SSL_SESSION\s0 objects keep internal link information about the session cache
176list, when being inserted into one \s-1SSL_CTX\s0 object's session cache.
177One \s-1SSL_SESSION\s0 object, regardless of its reference count, must therefore
178only be used with one \s-1SSL_CTX\s0 object (and the \s-1SSL\s0 objects created
179from this \s-1SSL_CTX\s0 object).
984263bc 180.SH "RETURN VALUES"
e056f0e0 181.IX Header "RETURN VALUES"
984263bc 182The following return values can occur:
e056f0e0
JR
183.IP "\s-1NULL\s0" 4
184.IX Item "NULL"
984263bc 185There is no session available in \fBssl\fR.
e056f0e0
JR
186.IP "Pointer to an \s-1SSL\s0" 4
187.IX Item "Pointer to an SSL"
984263bc
MD
188The return value points to the data of an \s-1SSL\s0 session.
189.SH "SEE ALSO"
a7d27d5a 190.IX Header "SEE ALSO"
e056f0e0
JR
191\&\fIssl\fR\|(3), \fISSL_free\fR\|(3),
192\&\fISSL_clear\fR\|(3),
193\&\fISSL_SESSION_free\fR\|(3)