| blob | 324b6d9006f4ecffcf5487275a20673cf66ca905 |
1 .\" $NetBSD: d2i_SSL_SESSION.3,v 1.14 2015/06/12 17:01:14 christos Exp $
2 .\"
3 .\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
4 .\"
5 .\" Standard preamble:
6 .\" ========================================================================
7 .de Sp \" Vertical space (when we can't use .PP)
8 .if t .sp .5v
9 .if n .sp
10 ..
11 .de Vb \" Begin verbatim text
12 .ft CW
13 .nf
14 .ne \\$1
15 ..
16 .de Ve \" End verbatim text
17 .ft R
18 .fi
19 ..
20 .\" Set up some character translations and predefined strings. \*(-- will
21 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
22 .\" double quote, and \*(R" will give a right double quote. \*(C+ will
23 .\" give a nicer C++. Capital omega is used to do unbreakable dashes and
24 .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
25 .\" nothing in troff, for use with C<>.
26 .tr \(*W-
27 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
28 .ie n \{\
29 . ds -- \(*W-
30 . ds PI pi
31 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
32 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
33 . ds L" ""
34 . ds R" ""
35 . ds C` ""
36 . ds C' ""
37 'br\}
38 .el\{\
39 . ds -- \|\(em\|
40 . ds PI \(*p
41 . ds L" ``
42 . ds R" ''
43 . ds C`
44 . ds C'
45 'br\}
46 .\"
47 .\" Escape single quotes in literal strings from groff's Unicode transform.
48 .ie \n(.g .ds Aq \(aq
49 .el .ds Aq '
50 .\"
51 .\" If the F register is turned on, we'll generate index entries on stderr for
52 .\" titles (.TH), headers (.SH), subsections (.SS), 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 .\"
56 .\" Avoid warning from groff about undefined register 'F'.
57 .de IX
58 ..
59 .nr rF 0
60 .if \n(.g .if rF .nr rF 1
61 .if (\n(rF:(\n(.g==0)) \{
62 . if \nF \{
63 . de IX
64 . tm Index:\\$1\t\\n%\t"\\$2"
65 ..
66 . if !\nF==2 \{
67 . nr % 0
68 . nr F 2
69 . \}
70 . \}
71 .\}
72 .rr rF
73 .\"
74 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
75 .\" Fear. Run. Save yourself. No user-serviceable parts.
76 . \" fudge factors for nroff and troff
77 .if n \{\
78 . ds #H 0
79 . ds #V .8m
80 . ds #F .3m
81 . ds #[ \f1
82 . ds #] \fP
83 .\}
84 .if t \{\
85 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
86 . ds #V .6m
87 . ds #F 0
88 . ds #[ \&
89 . ds #] \&
90 .\}
91 . \" simple accents for nroff and troff
92 .if n \{\
93 . ds ' \&
94 . ds ` \&
95 . ds ^ \&
96 . ds , \&
97 . ds ~ ~
98 . ds /
99 .\}
100 .if t \{\
101 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
102 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
103 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
104 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
105 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
106 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
107 .\}
108 . \" troff and (daisy-wheel) nroff accents
109 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
110 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
111 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
112 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
113 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
114 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
115 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
116 .ds ae a\h'-(\w'a'u*4/10)'e
117 .ds Ae A\h'-(\w'A'u*4/10)'E
118 . \" corrections for vroff
119 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
120 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
121 . \" for low resolution devices (crt and lpr)
122 .if \n(.H>23 .if \n(.V>19 \
123 \{\
124 . ds : e
125 . ds 8 ss
126 . ds o a
127 . ds d- d\h'-1'\(ga
128 . ds D- D\h'-1'\(hy
129 . ds th \o'bp'
130 . ds Th \o'LP'
131 . ds ae ae
132 . ds Ae AE
133 .\}
134 .rm #[ #] #H #V #F C
135 .\" ========================================================================
136 .\"
137 .IX Title "d2i_SSL_SESSION 3"
138 .TH d2i_SSL_SESSION 3 "2014-08-10" "1.0.1n" "OpenSSL"
139 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
140 .\" way too many mistakes in technical documents.
141 .if n .ad l
142 .nh
143 .SH "NAME"
144 d2i_SSL_SESSION, i2d_SSL_SESSION \- convert SSL_SESSION object from/to ASN1 representation
145 .SH "LIBRARY"
146 libcrypto, -lcrypto
147 .SH "SYNOPSIS"
148 .IX Header "SYNOPSIS"
149 .Vb 1
150 \& #include <openssl/ssl.h>
151 \&
152 \& SSL_SESSION *d2i_SSL_SESSION(SSL_SESSION **a, const unsigned char **pp, long length);
153 \& int i2d_SSL_SESSION(SSL_SESSION *in, unsigned char **pp);
154 .Ve
155 .SH "DESCRIPTION"
156 .IX Header "DESCRIPTION"
157 \&\fId2i_SSL_SESSION()\fR transforms the external \s-1ASN1\s0 representation of an \s-1SSL/TLS\s0
158 session, stored as binary data at location \fBpp\fR with length \fBlength\fR, into
159 an \s-1SSL_SESSION\s0 object.
160 .PP
161 \&\fIi2d_SSL_SESSION()\fR transforms the \s-1SSL_SESSION\s0 object \fBin\fR into the \s-1ASN1\s0
162 representation and stores it into the memory location pointed to by \fBpp\fR.
163 The length of the resulting \s-1ASN1\s0 representation is returned. If \fBpp\fR is
164 the \s-1NULL\s0 pointer, only the length is calculated and returned.
165 .SH "NOTES"
166 .IX Header "NOTES"
167 The \s-1SSL_SESSION\s0 object is built from several \fImalloc()\fRed parts, it can
168 therefore not be moved, copied or stored directly. In order to store
169 session data on disk or into a database, it must be transformed into
170 a binary \s-1ASN1\s0 representation.
171 .PP
172 When using \fId2i_SSL_SESSION()\fR, the \s-1SSL_SESSION\s0 object is automatically
173 allocated. The reference count is 1, so that the session must be
174 explicitly removed using \fISSL_SESSION_free\fR\|(3),
175 unless the \s-1SSL_SESSION\s0 object is completely taken over, when being called
176 inside the \fIget_session_cb()\fR (see
177 \&\fISSL_CTX_sess_set_get_cb\fR\|(3)).
178 .PP
179 \&\s-1SSL_SESSION\s0 objects keep internal link information about the session cache
180 list, when being inserted into one \s-1SSL_CTX\s0 object's session cache.
181 One \s-1SSL_SESSION\s0 object, regardless of its reference count, must therefore
182 only be used with one \s-1SSL_CTX\s0 object (and the \s-1SSL\s0 objects created
183 from this \s-1SSL_CTX\s0 object).
184 .PP
185 When using \fIi2d_SSL_SESSION()\fR, the memory location pointed to by \fBpp\fR must be
186 large enough to hold the binary representation of the session. There is no
187 known limit on the size of the created \s-1ASN1\s0 representation, so the necessary
188 amount of space should be obtained by first calling \fIi2d_SSL_SESSION()\fR with
189 \&\fBpp=NULL\fR, and obtain the size needed, then allocate the memory and
190 call \fIi2d_SSL_SESSION()\fR again.
191 Note that this will advance the value contained in \fB*pp\fR so it is necessary
192 to save a copy of the original allocation.
193 For example:
194 int i,j;
195 char *p, *temp;
196 i = i2d_SSL_SESSION(sess, \s-1NULL\s0);
197 p = temp = malloc(i);
198 j = i2d_SSL_SESSION(sess, &temp);
199 assert(i == j);
200 assert(p+i == temp);
201 .SH "RETURN VALUES"
202 .IX Header "RETURN VALUES"
203 \&\fId2i_SSL_SESSION()\fR returns a pointer to the newly allocated \s-1SSL_SESSION\s0
204 object. In case of failure the NULL-pointer is returned and the error message
205 can be retrieved from the error stack.
206 .PP
207 \&\fIi2d_SSL_SESSION()\fR returns the size of the \s-1ASN1\s0 representation in bytes.
208 When the session is not valid, \fB0\fR is returned and no operation is performed.
209 .SH "SEE ALSO"
210 .IX Header "SEE ALSO"
211 \&\fIssl\fR\|(3), \fISSL_SESSION_free\fR\|(3),
212 \&\fISSL_CTX_sess_set_get_cb\fR\|(3)