d2i_SSL_SESSION.pod revision 160815
1227825Stheraven=pod 2227825Stheraven 3227825Stheraven=head1 NAME 4227825Stheraven 5227825Stheravend2i_SSL_SESSION, i2d_SSL_SESSION - convert SSL_SESSION object from/to ASN1 representation 6227825Stheraven 7227825Stheraven=head1 SYNOPSIS 8227825Stheraven 9227825Stheraven #include <openssl/ssl.h> 10227825Stheraven 11227825Stheraven SSL_SESSION *d2i_SSL_SESSION(SSL_SESSION **a, const unsigned char **pp, long length); 12227825Stheraven int i2d_SSL_SESSION(SSL_SESSION *in, unsigned char **pp); 13227825Stheraven 14227825Stheraven=head1 DESCRIPTION 15227825Stheraven 16227825Stheravend2i_SSL_SESSION() transforms the external ASN1 representation of an SSL/TLS 17227825Stheravensession, stored as binary data at location B<pp> with length B<length>, into 18227825Stheravenan SSL_SESSION object. 19227825Stheraven 20227825Stheraveni2d_SSL_SESSION() transforms the SSL_SESSION object B<in> into the ASN1 21227825Stheravenrepresentation and stores it into the memory location pointed to by B<pp>. 22227825StheravenThe length of the resulting ASN1 representation is returned. If B<pp> is 23227825Stheraventhe NULL pointer, only the length is calculated and returned. 24227825Stheraven 25227825Stheraven=head1 NOTES 26227825Stheraven 27227825StheravenThe SSL_SESSION object is built from several malloc()ed parts, it can 28227825Stheraventherefore not be moved, copied or stored directly. In order to store 29227825Stheravensession data on disk or into a database, it must be transformed into 30227825Stheravena binary ASN1 representation. 31227825Stheraven 32227825StheravenWhen using d2i_SSL_SESSION(), the SSL_SESSION object is automatically 33227825Stheravenallocated. The reference count is 1, so that the session must be 34227825Stheravenexplicitly removed using L<SSL_SESSION_free(3)|SSL_SESSION_free(3)>, 35227825Stheravenunless the SSL_SESSION object is completely taken over, when being called 36227825Stheraveninside the get_session_cb() (see 37227825StheravenL<SSL_CTX_sess_set_get_cb(3)|SSL_CTX_sess_set_get_cb(3)>). 38227825Stheraven 39227825StheravenSSL_SESSION objects keep internal link information about the session cache 40227825Stheravenlist, when being inserted into one SSL_CTX object's session cache. 41227825StheravenOne SSL_SESSION object, regardless of its reference count, must therefore 42227825Stheravenonly be used with one SSL_CTX object (and the SSL objects created 43227825Stheravenfrom this SSL_CTX object). 44227825Stheraven 45227825StheravenWhen using i2d_SSL_SESSION(), the memory location pointed to by B<pp> must be 46227825Stheravenlarge enough to hold the binary representation of the session. There is no 47227825Stheravenknown limit on the size of the created ASN1 representation, so the necessary 48227825Stheravenamount of space should be obtained by first calling i2d_SSL_SESSION() with 49227825StheravenB<pp=NULL>, and obtain the size needed, then allocate the memory and 50227825Stheravencall i2d_SSL_SESSION() again. 51227825Stheraven 52227825Stheraven=head1 RETURN VALUES 53227825Stheraven 54227825Stheravend2i_SSL_SESSION() returns a pointer to the newly allocated SSL_SESSION 55227825Stheravenobject. In case of failure the NULL-pointer is returned and the error message 56227825Stheravencan be retrieved from the error stack. 57227825Stheraven 58227825Stheraveni2d_SSL_SESSION() returns the size of the ASN1 representation in bytes. 59227825StheravenWhen the session is not valid, B<0> is returned and no operation is performed. 60227825Stheraven 61227825Stheraven=head1 SEE ALSO 62227825Stheraven 63227825StheravenL<ssl(3)|ssl(3)>, L<SSL_SESSION_free(3)|SSL_SESSION_free(3)>, 64227825StheravenL<SSL_CTX_sess_set_get_cb(3)|SSL_CTX_sess_set_get_cb(3)> 65227825Stheraven 66227825Stheraven=cut 67227825Stheraven