lib/libssl/man/d2i_SSL_SESSION.3

   1 .\"     $OpenBSD: d2i_SSL_SESSION.3,v 1.6 2018/08/27 15:42:39 jsing Exp $
   2 .\"     OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100
   3 .\"
   4 .\" This file was written by Lutz Jaenicke <jaenicke@openssl.org>.
   5 .\" Copyright (c) 2001, 2005, 2014 The OpenSSL Project.  All rights reserved.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\"
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\"
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in
  16 .\"    the documentation and/or other materials provided with the
  17 .\"    distribution.
  18 .\"
  19 .\" 3. All advertising materials mentioning features or use of this
  20 .\"    software must display the following acknowledgment:
  21 .\"    "This product includes software developed by the OpenSSL Project
  22 .\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
  23 .\"
  24 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
  25 .\"    endorse or promote products derived from this software without
  26 .\"    prior written permission. For written permission, please contact
  27 .\"    openssl-core@openssl.org.
  28 .\"
  29 .\" 5. Products derived from this software may not be called "OpenSSL"
  30 .\"    nor may "OpenSSL" appear in their names without prior written
  31 .\"    permission of the OpenSSL Project.
  32 .\"
  33 .\" 6. Redistributions of any form whatsoever must retain the following
  34 .\"    acknowledgment:
  35 .\"    "This product includes software developed by the OpenSSL Project
  36 .\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
  37 .\"
  38 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
  39 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  40 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  41 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
  42 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  43 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  44 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  45 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  46 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  47 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  48 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  49 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
  50 .\"
  51 .Dd $Mdocdate: August 27 2018 $
  52 .Dt D2I_SSL_SESSION 3
  53 .Os
  54 .Sh NAME
  55 .Nm d2i_SSL_SESSION ,
  56 .Nm i2d_SSL_SESSION
  57 .Nd convert SSL_SESSION object from/to ASN1 representation
  58 .Sh SYNOPSIS
  59 .In openssl/ssl.h
  60 .Ft  SSL_SESSION *
  61 .Fn d2i_SSL_SESSION "SSL_SESSION **a" "const unsigned char **pp" "long length"
  62 .Ft  int
  63 .Fn i2d_SSL_SESSION "SSL_SESSION *in" "unsigned char **pp"
  64 .Sh DESCRIPTION
  65 .Fn d2i_SSL_SESSION
  66 transforms the external ASN1 representation of an SSL/TLS session,
  67 stored as binary data at location
  68 .Fa pp
  69 with length
  70 .Fa length ,
  71 into
  72 an
  73 .Vt SSL_SESSION
  74 object.
  75 .Pp
  76 .Fn i2d_SSL_SESSION
  77 transforms the
  78 .Vt SSL_SESSION
  79 object
  80 .Fa in
  81 into the ASN1 representation and stores it into the memory location pointed to
  82 by
  83 .Fa pp .
  84 The length of the resulting ASN1 representation is returned.
  85 If
  86 .Fa pp
  87 is the
  88 .Dv NULL
  89 pointer, only the length is calculated and returned.
  90 .Sh NOTES
  91 The
  92 .Vt SSL_SESSION
  93 object is built from several
  94 .Xr malloc 3 Ns
  95 -ed parts; it can therefore not be moved, copied or stored directly.
  96 In order to store session data on disk or into a database,
  97 it must be transformed into a binary ASN1 representation.
  98 .Pp
  99 When using
 100 .Fn d2i_SSL_SESSION ,
 101 the
 102 .Vt SSL_SESSION
 103 object is automatically allocated.
 104 The reference count is 1, so that the session must be explicitly removed using
 105 .Xr SSL_SESSION_free 3 ,
 106 unless the
 107 .Vt SSL_SESSION
 108 object is completely taken over, when being called inside the
 109 .Fn get_session_cb ,
 110 see
 111 .Xr SSL_CTX_sess_set_get_cb 3 .
 112 .Pp
 113 .Vt SSL_SESSION
 114 objects keep internal link information about the session cache list when being
 115 inserted into one
 116 .Vt SSL_CTX
 117 object's session cache.
 118 One
 119 .Vt SSL_SESSION
 120 object, regardless of its reference count, must therefore only be used with one
 121 .Vt SSL_CTX
 122 object (and the
 123 .Vt SSL
 124 objects created from this
 125 .Vt SSL_CTX
 126 object).
 127 .Pp
 128 When using
 129 .Fn i2d_SSL_SESSION ,
 130 the memory location pointed to by
 131 .Fa pp
 132 must be large enough to hold the binary representation of the session.
 133 There is no known limit on the size of the created ASN1 representation,
 134 so call
 135 .Fn i2d_SSL_SESSION
 136 first with
 137 .Fa pp Ns = Ns Dv NULL
 138 to obtain the encoded size, before allocating the required amount of memory and
 139 calling
 140 .Fn i2d_SSL_SESSION
 141 again.
 142 Note that this will advance the value contained in
 143 .Fa *pp
 144 so it is necessary to save a copy of the original allocation.
 145 For example:
 146 .Bd -literal -offset indent
 147 char    *p, *pp;
 148 int      elen, len;
 149
 150 elen = i2d_SSL_SESSION(sess, NULL);
 151 p = pp = malloc(elen);
 152 if (p != NULL) {
 153         len = i2d_SSL_SESSION(sess, &pp);
 154         assert(elen == len);
 155         assert(p + len == pp);
 156 }
 157 .Ed
 158 .Sh RETURN VALUES
 159 .Fn d2i_SSL_SESSION
 160 returns a pointer to the newly allocated
 161 .Vt SSL_SESSION
 162 object.
 163 In case of failure a
 164 .Dv NULL
 165 pointer is returned and the error message can be retrieved from the error
 166 stack.
 167 .Pp
 168 .Fn i2d_SSL_SESSION
 169 returns the size of the ASN1 representation in bytes.
 170 When the session is not valid, 0 is returned and no operation is performed.
 171 .Sh SEE ALSO
 172 .Xr d2i_X509 3 ,
 173 .Xr ssl 3 ,
 174 .Xr SSL_CTX_sess_set_get_cb 3 ,
 175 .Xr SSL_SESSION_free 3
 176 .Sh HISTORY
 177 .Fn d2i_SSL_SESSION
 178 and
 179 .Fn i2d_SSL_SESSION
 180 first appeared in SSLeay 0.5.2 and have been available since
 181 .Ox 2.4 .