lib/libssl/man/d2i_SSL_SESSION.3

   1 .\"     $OpenBSD: d2i_SSL_SESSION.3,v 1.4 2018/03/21 05:07:04 schwarze 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: March 21 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 the necessary amount of space should be obtained by first calling
 135 .Fn i2d_SSL_SESSION
 136 with
 137 .Fa pp Ns
 138 = Ns
 139 .Dv NULL ,
 140 and obtain the size needed, then allocate the memory and call
 141 .Fn i2d_SSL_SESSION
 142 again.
 143 Note that this will advance the value contained in
 144 .Fa *pp
 145 so it is necessary to save a copy of the original allocation.
 146 For example:
 147 .Bd -literal
 148 int i, j;
 149
 150 char *p, *temp;
 151
 152  i = i2d_SSL_SESSION(sess, NULL);
 153  p = temp = malloc(i);
 154  if (temp != NULL) {
 155         j = i2d_SSL_SESSION(sess, &temp);
 156         assert(i == j);
 157         assert(p + i == temp);
 158  }
 159 .Ed
 160 .Sh RETURN VALUES
 161 .Fn d2i_SSL_SESSION
 162 returns a pointer to the newly allocated
 163 .Vt SSL_SESSION
 164 object.
 165 In case of failure a
 166 .Dv NULL
 167 pointer is returned and the error message can be retrieved from the error
 168 stack.
 169 .Pp
 170 .Fn i2d_SSL_SESSION
 171 returns the size of the ASN1 representation in bytes.
 172 When the session is not valid, 0 is returned and no operation is performed.
 173 .Sh SEE ALSO
 174 .Xr d2i_X509 3 ,
 175 .Xr ssl 3 ,
 176 .Xr SSL_CTX_sess_set_get_cb 3 ,
 177 .Xr SSL_SESSION_free 3
 178 .Sh HISTORY
 179 .Fn d2i_SSL_SESSION
 180 and
 181 .Fn i2d_SSL_SESSION
 182 appeared before SSLeay 0.8 and have been available since
 183 .Ox 2.4 .