Upgrade to OpenSSL 0.9.8h.
[dragonfly.git] / secure / lib / libssl / man / d2i_SSL_SESSION.3
CommitLineData
aac4ff6f 1.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
e056f0e0
JR
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
aac4ff6f
PA
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<>.
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 62.\"
aac4ff6f
PA
63.\" For nroff, turn off justification. Always turn off hyphenation; it makes
64.\" way too many mistakes in technical documents.
65.hy 0
66.if n .na
67.\"
e056f0e0
JR
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 "d2i_SSL_SESSION 3"
aac4ff6f 132.TH d2i_SSL_SESSION 3 "2008-09-06" "0.9.8h" "OpenSSL"
984263bc 133.SH "NAME"
a7d27d5a 134d2i_SSL_SESSION, i2d_SSL_SESSION \- convert SSL_SESSION object from/to ASN1 representation
984263bc 135.SH "SYNOPSIS"
e056f0e0 136.IX Header "SYNOPSIS"
984263bc
MD
137.Vb 1
138\& #include <openssl/ssl.h>
aac4ff6f
PA
139.Ve
140.PP
141.Vb 2
a561f9ff 142\& SSL_SESSION *d2i_SSL_SESSION(SSL_SESSION **a, const unsigned char **pp, long length);
984263bc
MD
143\& int i2d_SSL_SESSION(SSL_SESSION *in, unsigned char **pp);
144.Ve
145.SH "DESCRIPTION"
e056f0e0
JR
146.IX Header "DESCRIPTION"
147\&\fId2i_SSL_SESSION()\fR transforms the external \s-1ASN1\s0 representation of an \s-1SSL/TLS\s0
984263bc 148session, stored as binary data at location \fBpp\fR with length \fBlength\fR, into
e056f0e0 149an \s-1SSL_SESSION\s0 object.
984263bc 150.PP
e056f0e0 151\&\fIi2d_SSL_SESSION()\fR transforms the \s-1SSL_SESSION\s0 object \fBin\fR into the \s-1ASN1\s0
984263bc 152representation and stores it into the memory location pointed to by \fBpp\fR.
e056f0e0
JR
153The length of the resulting \s-1ASN1\s0 representation is returned. If \fBpp\fR is
154the \s-1NULL\s0 pointer, only the length is calculated and returned.
984263bc 155.SH "NOTES"
e056f0e0
JR
156.IX Header "NOTES"
157The \s-1SSL_SESSION\s0 object is built from several \fImalloc()\fRed parts, it can
984263bc
MD
158therefore not be moved, copied or stored directly. In order to store
159session data on disk or into a database, it must be transformed into
e056f0e0 160a binary \s-1ASN1\s0 representation.
984263bc 161.PP
e056f0e0 162When using \fId2i_SSL_SESSION()\fR, the \s-1SSL_SESSION\s0 object is automatically
984263bc 163allocated. The reference count is 1, so that the session must be
e056f0e0
JR
164explicitly removed using \fISSL_SESSION_free\fR\|(3),
165unless the \s-1SSL_SESSION\s0 object is completely taken over, when being called
984263bc 166inside the \fIget_session_cb()\fR (see
e056f0e0 167\&\fISSL_CTX_sess_set_get_cb\fR\|(3)).
984263bc 168.PP
e056f0e0
JR
169\&\s-1SSL_SESSION\s0 objects keep internal link information about the session cache
170list, when being inserted into one \s-1SSL_CTX\s0 object's session cache.
171One \s-1SSL_SESSION\s0 object, regardless of its reference count, must therefore
172only be used with one \s-1SSL_CTX\s0 object (and the \s-1SSL\s0 objects created
173from this \s-1SSL_CTX\s0 object).
984263bc
MD
174.PP
175When using \fIi2d_SSL_SESSION()\fR, the memory location pointed to by \fBpp\fR must be
176large enough to hold the binary representation of the session. There is no
e056f0e0 177known limit on the size of the created \s-1ASN1\s0 representation, so the necessary
984263bc 178amount of space should be obtained by first calling \fIi2d_SSL_SESSION()\fR with
e056f0e0 179\&\fBpp=NULL\fR, and obtain the size needed, then allocate the memory and
984263bc
MD
180call \fIi2d_SSL_SESSION()\fR again.
181.SH "RETURN VALUES"
e056f0e0
JR
182.IX Header "RETURN VALUES"
183\&\fId2i_SSL_SESSION()\fR returns a pointer to the newly allocated \s-1SSL_SESSION\s0
184object. In case of failure the NULL-pointer is returned and the error message
984263bc
MD
185can be retrieved from the error stack.
186.PP
e056f0e0 187\&\fIi2d_SSL_SESSION()\fR returns the size of the \s-1ASN1\s0 representation in bytes.
984263bc
MD
188When the session is not valid, \fB0\fR is returned and no operation is performed.
189.SH "SEE ALSO"
a7d27d5a 190.IX Header "SEE ALSO"
e056f0e0
JR
191\&\fIssl\fR\|(3), \fISSL_SESSION_free\fR\|(3),
192\&\fISSL_CTX_sess_set_get_cb\fR\|(3)