lib/libcrypto/man/RSA_get_ex_new_index.3

   1 .\"     $OpenBSD: RSA_get_ex_new_index.3,v 1.7 2017/08/01 14:57:03 schwarze Exp $
   2 .\"     OpenSSL 35cb565a Nov 19 15:49:30 2015 -0500
   3 .\"
   4 .\" This file was written by Ulf Moeller <ulf@openssl.org> and
   5 .\" Dr. Stephen Henson <steve@openssl.org>.
   6 .\" Copyright (c) 2000, 2006 The OpenSSL Project.  All rights reserved.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\"
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\"
  15 .\" 2. Redistributions in binary form must reproduce the above copyright
  16 .\"    notice, this list of conditions and the following disclaimer in
  17 .\"    the documentation and/or other materials provided with the
  18 .\"    distribution.
  19 .\"
  20 .\" 3. All advertising materials mentioning features or use of this
  21 .\"    software must display the following acknowledgment:
  22 .\"    "This product includes software developed by the OpenSSL Project
  23 .\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
  24 .\"
  25 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
  26 .\"    endorse or promote products derived from this software without
  27 .\"    prior written permission. For written permission, please contact
  28 .\"    openssl-core@openssl.org.
  29 .\"
  30 .\" 5. Products derived from this software may not be called "OpenSSL"
  31 .\"    nor may "OpenSSL" appear in their names without prior written
  32 .\"    permission of the OpenSSL Project.
  33 .\"
  34 .\" 6. Redistributions of any form whatsoever must retain the following
  35 .\"    acknowledgment:
  36 .\"    "This product includes software developed by the OpenSSL Project
  37 .\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
  38 .\"
  39 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
  40 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  41 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  42 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
  43 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  44 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  45 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  46 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  47 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  48 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  49 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  50 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
  51 .\"
  52 .Dd $Mdocdate: August 1 2017 $
  53 .Dt RSA_GET_EX_NEW_INDEX 3
  54 .Os
  55 .Sh NAME
  56 .Nm RSA_get_ex_new_index ,
  57 .Nm RSA_set_ex_data ,
  58 .Nm RSA_get_ex_data ,
  59 .Nm CRYPTO_EX_new ,
  60 .Nm CRYPTO_EX_dup ,
  61 .Nm CRYPTO_EX_free
  62 .Nd add application specific data to RSA structures
  63 .Sh SYNOPSIS
  64 .In openssl/rsa.h
  65 .Ft int
  66 .Fo RSA_get_ex_new_index
  67 .Fa "long argl"
  68 .Fa "void *argp"
  69 .Fa "CRYPTO_EX_new *new_func"
  70 .Fa "CRYPTO_EX_dup *dup_func"
  71 .Fa "CRYPTO_EX_free *free_func"
  72 .Fc
  73 .Ft int
  74 .Fo RSA_set_ex_data
  75 .Fa "RSA *r"
  76 .Fa "int idx"
  77 .Fa "void *arg"
  78 .Fc
  79 .Ft void *
  80 .Fo RSA_get_ex_data
  81 .Fa "RSA *r"
  82 .Fa "int idx"
  83 .Fc
  84 .Ft typedef int
  85 .Fo CRYPTO_EX_new
  86 .Fa "void *parent"
  87 .Fa "void *ptr"
  88 .Fa "CRYPTO_EX_DATA *ad"
  89 .Fa "int idx"
  90 .Fa "long argl"
  91 .Fa "void *argp"
  92 .Fc
  93 .Ft typedef void
  94 .Fo CRYPTO_EX_free
  95 .Fa "void *parent"
  96 .Fa "void *ptr"
  97 .Fa "CRYPTO_EX_DATA *ad"
  98 .Fa "int idx"
  99 .Fa "long argl"
 100 .Fa "void *argp"
 101 .Fc
 102 .Ft typedef int
 103 .Fo CRYPTO_EX_dup
 104 .Fa "CRYPTO_EX_DATA *to"
 105 .Fa "CRYPTO_EX_DATA *from"
 106 .Fa "void *from_d"
 107 .Fa "int idx"
 108 .Fa "long argl"
 109 .Fa "void *argp"
 110 .Fc
 111 .Sh DESCRIPTION
 112 Several OpenSSL structures can have application specific data attached
 113 to them.
 114 This has several potential uses: it can be used to cache data associated
 115 with a structure (for example the hash of some part of the structure) or
 116 some additional data (for example a handle to the data in an external
 117 library).
 118 .Pp
 119 Since the application data can be anything at all it is passed and
 120 retrieved as a
 121 .Vt void *
 122 type.
 123 .Pp
 124 The
 125 .Fn RSA_get_ex_new_index
 126 function is initially called to "register" some new application specific
 127 data.
 128 It takes three optional function pointers which are called when the
 129 parent structure (in this case an RSA structure) is initially created,
 130 when it is copied and when it is freed up.
 131 If any or all of these function pointer arguments are not used, they
 132 should be set to
 133 .Dv NULL .
 134 The precise manner in which these function pointers are called is
 135 described in more detail below.
 136 .Fn RSA_get_ex_new_index
 137 also takes additional long and pointer parameters which will be passed
 138 to the supplied functions but which otherwise have no special meaning.
 139 It returns an index which should be stored (typically in a static
 140 variable) and passed as the
 141 .Fa idx
 142 parameter in the remaining functions.
 143 Each successful call to
 144 .Fn RSA_get_ex_new_index
 145 will return an index greater than any previously returned.
 146 This is
 147 important because the optional functions are called in order of
 148 increasing index value.
 149 .Pp
 150 .Fn RSA_set_ex_data
 151 is used to set application specific data.
 152 The data is supplied in the
 153 .Fa arg
 154 parameter and its precise meaning is up to the application.
 155 .Pp
 156 .Fn RSA_get_ex_data
 157 is used to retrieve application specific data.
 158 The data is returned to the application, which will be the same value as
 159 supplied to a previous
 160 .Fn RSA_set_ex_data
 161 call.
 162 .Pp
 163 .Fa new_func
 164 is called when a structure is initially allocated (for example with
 165 .Xr RSA_new 3 .
 166 The parent structure members will not have any meaningful values at this
 167 point.
 168 This function will typically be used to allocate any application
 169 specific structure.
 170 .Pp
 171 .Fa free_func
 172 is called when a structure is being freed up.
 173 The dynamic parent structure members should not be accessed because they
 174 will be freed up when this function is called.
 175 .Pp
 176 .Fa new_func
 177 and
 178 .Fa free_func
 179 take the same parameters.
 180 .Fa parent
 181 is a pointer to the parent
 182 .Vt RSA
 183 structure.
 184 .Fa ptr
 185 is the application specific data (this won't be of much use in
 186 .Fa new_func ) .
 187 .Fa ad
 188 is a pointer to the
 189 .Vt CRYPTO_EX_DATA
 190 structure from the parent
 191 .Vt RSA
 192 structure: the functions
 193 .Fn CRYPTO_get_ex_data
 194 and
 195 .Fn CRYPTO_set_ex_data
 196 can be called to manipulate it.
 197 The
 198 .Fa idx
 199 parameter is the index: this will be the same value returned by
 200 .Fn RSA_get_ex_new_index
 201 when the functions were initially registered.
 202 Finally the
 203 .Fa argl
 204 and
 205 .Fa argp
 206 parameters are the values originally passed to the same corresponding
 207 parameters when
 208 .Fn RSA_get_ex_new_index
 209 was called.
 210 .Pp
 211 .Fa dup_func
 212 is called when a structure is being copied.
 213 Pointers to the destination and source
 214 .Vt CRYPTO_EX_DATA
 215 structures are passed in the
 216 .Fa to
 217 and
 218 .Fa from
 219 parameters, respectively.
 220 The
 221 .Fa from_d
 222 parameter is passed a pointer to the source application data when the
 223 function is called.
 224 When the function returns, the value is copied to the destination:
 225 the application can thus modify the data pointed to by
 226 .Fa from_d
 227 and have different values in the source and destination.
 228 The
 229 .Fa idx ,
 230 .Fa argl ,
 231 and
 232 .Fa argp
 233 parameters are the same as those in
 234 .Fa new_func
 235 and
 236 .Fa free_func .
 237 .Sh RETURN VALUES
 238 .Fn RSA_get_ex_new_index
 239 returns a new index or -1 on failure.
 240 Note that 0 is a valid index value.
 241 .Pp
 242 .Fn RSA_set_ex_data
 243 returns 1 on success or 0 on failure.
 244 .Pp
 245 .Fn RSA_get_ex_data
 246 returns the application data or
 247 .Dv NULL
 248 on failure.
 249 .Dv NULL
 250 may also be valid application data, but currently it can only fail if
 251 given an invalid
 252 .Fa idx
 253 parameter.
 254 .Pp
 255 .Fa new_func
 256 and
 257 .Fa dup_func
 258 should return 0 for failure and 1 for success.
 259 .Pp
 260 On failure an error code can be obtained from
 261 .Xr ERR_get_error 3 .
 262 .Sh SEE ALSO
 263 .Xr BIO_set_ex_data 3 ,
 264 .Xr CRYPTO_set_ex_data 3 ,
 265 .Xr DH_set_ex_data 3 ,
 266 .Xr DSA_set_ex_data 3 ,
 267 .Xr RSA_new 3 ,
 268 .Xr X509_STORE_CTX_set_ex_data 3
 269 .Sh HISTORY
 270 .Fn RSA_get_ex_new_index ,
 271 .Fn RSA_set_ex_data ,
 272 and
 273 .Fn RSA_get_ex_data
 274 are available since SSLeay 0.9.0.
 275 .Sh BUGS
 276 .Fa dup_func
 277 is currently never called.
 278 .Pp
 279 The return value of
 280 .Fa new_func
 281 is ignored.
 282 .Pp
 283 The
 284 .Fa new_func
 285 function isn't very useful because no meaningful values are present in
 286 the parent RSA structure when it is called.