1ebfedea0SLionel Sambuc=pod 2ebfedea0SLionel Sambuc 3ebfedea0SLionel Sambuc=head1 NAME 4ebfedea0SLionel Sambuc 5ebfedea0SLionel Sambucd2i_SSL_SESSION, i2d_SSL_SESSION - convert SSL_SESSION object from/to ASN1 representation 6ebfedea0SLionel Sambuc 7ebfedea0SLionel Sambuc=head1 SYNOPSIS 8ebfedea0SLionel Sambuc 9ebfedea0SLionel Sambuc #include <openssl/ssl.h> 10ebfedea0SLionel Sambuc 11ebfedea0SLionel Sambuc SSL_SESSION *d2i_SSL_SESSION(SSL_SESSION **a, const unsigned char **pp, long length); 12ebfedea0SLionel Sambuc int i2d_SSL_SESSION(SSL_SESSION *in, unsigned char **pp); 13ebfedea0SLionel Sambuc 14ebfedea0SLionel Sambuc=head1 DESCRIPTION 15ebfedea0SLionel Sambuc 16ebfedea0SLionel Sambucd2i_SSL_SESSION() transforms the external ASN1 representation of an SSL/TLS 17ebfedea0SLionel Sambucsession, stored as binary data at location B<pp> with length B<length>, into 18ebfedea0SLionel Sambucan SSL_SESSION object. 19ebfedea0SLionel Sambuc 20ebfedea0SLionel Sambuci2d_SSL_SESSION() transforms the SSL_SESSION object B<in> into the ASN1 21ebfedea0SLionel Sambucrepresentation and stores it into the memory location pointed to by B<pp>. 22ebfedea0SLionel SambucThe length of the resulting ASN1 representation is returned. If B<pp> is 23ebfedea0SLionel Sambucthe NULL pointer, only the length is calculated and returned. 24ebfedea0SLionel Sambuc 25ebfedea0SLionel Sambuc=head1 NOTES 26ebfedea0SLionel Sambuc 27ebfedea0SLionel SambucThe SSL_SESSION object is built from several malloc()ed parts, it can 28ebfedea0SLionel Sambuctherefore not be moved, copied or stored directly. In order to store 29ebfedea0SLionel Sambucsession data on disk or into a database, it must be transformed into 30ebfedea0SLionel Sambuca binary ASN1 representation. 31ebfedea0SLionel Sambuc 32ebfedea0SLionel SambucWhen using d2i_SSL_SESSION(), the SSL_SESSION object is automatically 33ebfedea0SLionel Sambucallocated. The reference count is 1, so that the session must be 34ebfedea0SLionel Sambucexplicitly removed using L<SSL_SESSION_free(3)|SSL_SESSION_free(3)>, 35ebfedea0SLionel Sambucunless the SSL_SESSION object is completely taken over, when being called 36ebfedea0SLionel Sambucinside the get_session_cb() (see 37ebfedea0SLionel SambucL<SSL_CTX_sess_set_get_cb(3)|SSL_CTX_sess_set_get_cb(3)>). 38ebfedea0SLionel Sambuc 39ebfedea0SLionel SambucSSL_SESSION objects keep internal link information about the session cache 40ebfedea0SLionel Sambuclist, when being inserted into one SSL_CTX object's session cache. 41ebfedea0SLionel SambucOne SSL_SESSION object, regardless of its reference count, must therefore 42ebfedea0SLionel Sambuconly be used with one SSL_CTX object (and the SSL objects created 43ebfedea0SLionel Sambucfrom this SSL_CTX object). 44ebfedea0SLionel Sambuc 45ebfedea0SLionel SambucWhen using i2d_SSL_SESSION(), the memory location pointed to by B<pp> must be 46ebfedea0SLionel Sambuclarge enough to hold the binary representation of the session. There is no 47ebfedea0SLionel Sambucknown limit on the size of the created ASN1 representation, so the necessary 48ebfedea0SLionel Sambucamount of space should be obtained by first calling i2d_SSL_SESSION() with 49ebfedea0SLionel SambucB<pp=NULL>, and obtain the size needed, then allocate the memory and 50ebfedea0SLionel Sambuccall i2d_SSL_SESSION() again. 51*0a6a1f1dSLionel SambucNote that this will advance the value contained in B<*pp> so it is necessary 52*0a6a1f1dSLionel Sambucto save a copy of the original allocation. 53*0a6a1f1dSLionel SambucFor example: 54*0a6a1f1dSLionel Sambuc int i,j; 55*0a6a1f1dSLionel Sambuc char *p, *temp; 56*0a6a1f1dSLionel Sambuc i = i2d_SSL_SESSION(sess, NULL); 57*0a6a1f1dSLionel Sambuc p = temp = malloc(i); 58*0a6a1f1dSLionel Sambuc j = i2d_SSL_SESSION(sess, &temp); 59*0a6a1f1dSLionel Sambuc assert(i == j); 60*0a6a1f1dSLionel Sambuc assert(p+i == temp); 61ebfedea0SLionel Sambuc 62ebfedea0SLionel Sambuc=head1 RETURN VALUES 63ebfedea0SLionel Sambuc 64ebfedea0SLionel Sambucd2i_SSL_SESSION() returns a pointer to the newly allocated SSL_SESSION 65ebfedea0SLionel Sambucobject. In case of failure the NULL-pointer is returned and the error message 66ebfedea0SLionel Sambuccan be retrieved from the error stack. 67ebfedea0SLionel Sambuc 68ebfedea0SLionel Sambuci2d_SSL_SESSION() returns the size of the ASN1 representation in bytes. 69ebfedea0SLionel SambucWhen the session is not valid, B<0> is returned and no operation is performed. 70ebfedea0SLionel Sambuc 71ebfedea0SLionel Sambuc=head1 SEE ALSO 72ebfedea0SLionel Sambuc 73ebfedea0SLionel SambucL<ssl(3)|ssl(3)>, L<SSL_SESSION_free(3)|SSL_SESSION_free(3)>, 74ebfedea0SLionel SambucL<SSL_CTX_sess_set_get_cb(3)|SSL_CTX_sess_set_get_cb(3)> 75ebfedea0SLionel Sambuc 76ebfedea0SLionel Sambuc=cut 77