1 files changed, 126 insertions, 0 deletions

diff --git a/src/lib/libssl/doc/d2i_SSL_SESSION.3 b/src/lib/libssl/doc/d2i_SSL_SESSION.3
new file mode 100644
index 0000000000..3a40c32e69
--- /dev/null
+++ b/src/lib/libssl/doc/d2i_SSL_SESSION.3
@@ -0,0 +1,126 @@
+.Dd $Mdocdate: October 12 2014 $
+.Dt D2I_SSL_SESSION 3
+.Os
+.Sh NAME
+.Nm d2i_SSL_SESSION ,
+.Nm i2d_SSL_SESSION
+.Nd convert SSL_SESSION object from/to ASN1 representation
+.Sh SYNOPSIS
+.In openssl/ssl.h
+.Ft  SSL_SESSION *
+.Fn d2i_SSL_SESSION "SSL_SESSION **a" "const unsigned char **pp" "long length"
+.Ft  int
+.Fn i2d_SSL_SESSION "SSL_SESSION *in" "unsigned char **pp"
+.Sh DESCRIPTION
+.Fn d2i_SSL_SESSION
+transforms the external ASN1 representation of an SSL/TLS session,
+stored as binary data at location
+.Fa pp
+with length
+.Fa length ,
+into
+an
+.Vt SSL_SESSION
+object.
+.Pp
+.Fn i2d_SSL_SESSION
+transforms the
+.Vt SSL_SESSION
+object
+.Fa in
+into the ASN1 representation and stores it into the memory location pointed to
+by
+.Fa pp .
+The length of the resulting ASN1 representation is returned.
+If
+.Fa pp
+is the
+.Dv NULL
+pointer, only the length is calculated and returned.
+.Sh NOTES
+The
+.Vt SSL_SESSION
+object is built from several
+.Xr malloc 3 Ns
+-ed parts; it can therefore not be moved, copied or stored directly.
+In order to store session data on disk or into a database,
+it must be transformed into a binary ASN1 representation.
+.Pp
+When using
+.Fn d2i_SSL_SESSION ,
+the
+.Vt SSL_SESSION
+object is automatically allocated.
+The reference count is 1, so that the session must be explicitly removed using
+.Xr SSL_SESSION_free 3 ,
+unless the
+.Vt SSL_SESSION
+object is completely taken over, when being called inside the
+.Xr get_session_cb 3
+(see
+.Xr SSL_CTX_sess_set_get_cb 3 ) .
+.Pp
+.Vt SSL_SESSION
+objects keep internal link information about the session cache list when being
+inserted into one
+.Vt SSL_CTX
+object's session cache.
+One
+.Vt SSL_SESSION
+object, regardless of its reference count, must therefore only be used with one
+.Vt SSL_CTX
+object (and the
+.Vt SSL
+objects created from this
+.Vt SSL_CTX
+object).
+.Pp
+When using
+.Fn i2d_SSL_SESSION ,
+the memory location pointed to by
+.Fa pp
+must be large enough to hold the binary representation of the session.
+There is no known limit on the size of the created ASN1 representation,
+so the necessary amount of space should be obtained by first calling
+.Fn i2d_SSL_SESSION
+with
+.Fa pp Ns
+= Ns
+.Dv NULL ,
+and obtain the size needed, then allocate the memory and call
+.Fn i2d_SSL_SESSION
+again.
+Note that this will advance the value contained in
+.Fa *pp
+so it is necessary to save a copy of the original allocation.
+For example:
+.Bd -literal
+int i, j;
+
+char *p, *temp;
+
+ i = i2d_SSL_SESSION(sess, NULL);
+ p = temp = malloc(i);
+ if (temp != NULL) {
+        j = i2d_SSL_SESSION(sess, &temp);
+        assert(i == j);
+        assert(p + i == temp);
+ }
+.Ed
+.Sh RETURN VALUES
+.Fn d2i_SSL_SESSION
+returns a pointer to the newly allocated
+.Vt SSL_SESSION
+object.
+In case of failure a
+.Dv NULL
+pointer is returned and the error message can be retrieved from the error
+stack.
+.Pp
+.Fn i2d_SSL_SESSION
+returns the size of the ASN1 representation in bytes.
+When the session is not valid, 0 is returned and no operation is performed.
+.Sh SEE ALSO
+.Xr ssl 3 ,
+.Xr SSL_CTX_sess_set_get_cb 3 ,
+.Xr SSL_SESSION_free 3