1: =pod
    2: 
    3: =head1 NAME
    4: 
    5: d2i_SSL_SESSION, i2d_SSL_SESSION - convert SSL_SESSION object from/to ASN1 representation
    6: 
    7: =head1 SYNOPSIS
    8: 
    9:  #include <openssl/ssl.h>
   10: 
   11:  SSL_SESSION *d2i_SSL_SESSION(SSL_SESSION **a, const unsigned char **pp, long length);
   12:  int i2d_SSL_SESSION(SSL_SESSION *in, unsigned char **pp);
   13: 
   14: =head1 DESCRIPTION
   15: 
   16: d2i_SSL_SESSION() transforms the external ASN1 representation of an SSL/TLS
   17: session, stored as binary data at location B<pp> with length B<length>, into
   18: an SSL_SESSION object.
   19: 
   20: i2d_SSL_SESSION() transforms the SSL_SESSION object B<in> into the ASN1
   21: representation and stores it into the memory location pointed to by B<pp>.
   22: The length of the resulting ASN1 representation is returned. If B<pp> is
   23: the NULL pointer, only the length is calculated and returned.
   24: 
   25: =head1 NOTES
   26: 
   27: The SSL_SESSION object is built from several malloc()ed parts, it can
   28: therefore not be moved, copied or stored directly. In order to store
   29: session data on disk or into a database, it must be transformed into
   30: a binary ASN1 representation.
   31: 
   32: When using d2i_SSL_SESSION(), the SSL_SESSION object is automatically
   33: allocated. The reference count is 1, so that the session must be
   34: explicitly removed using L<SSL_SESSION_free(3)|SSL_SESSION_free(3)>,
   35: unless the SSL_SESSION object is completely taken over, when being called
   36: inside the get_session_cb() (see
   37: L<SSL_CTX_sess_set_get_cb(3)|SSL_CTX_sess_set_get_cb(3)>).
   38: 
   39: SSL_SESSION objects keep internal link information about the session cache
   40: list, when being inserted into one SSL_CTX object's session cache.
   41: One SSL_SESSION object, regardless of its reference count, must therefore
   42: only be used with one SSL_CTX object (and the SSL objects created
   43: from this SSL_CTX object).
   44: 
   45: When using i2d_SSL_SESSION(), the memory location pointed to by B<pp> must be
   46: large enough to hold the binary representation of the session. There is no
   47: known limit on the size of the created ASN1 representation, so the necessary
   48: amount of space should be obtained by first calling i2d_SSL_SESSION() with
   49: B<pp=NULL>, and obtain the size needed, then allocate the memory and
   50: call i2d_SSL_SESSION() again.
   51: 
   52: =head1 RETURN VALUES
   53: 
   54: d2i_SSL_SESSION() returns a pointer to the newly allocated SSL_SESSION
   55: object. In case of failure the NULL-pointer is returned and the error message
   56: can be retrieved from the error stack.
   57: 
   58: i2d_SSL_SESSION() returns the size of the ASN1 representation in bytes.
   59: When the session is not valid, B<0> is returned and no operation is performed.
   60: 
   61: =head1 SEE ALSO
   62: 
   63: L<ssl(3)|ssl(3)>, L<SSL_SESSION_free(3)|SSL_SESSION_free(3)>,
   64: L<SSL_CTX_sess_set_get_cb(3)|SSL_CTX_sess_set_get_cb(3)>
   65: 
   66: =cut