1.\" $OpenBSD: CRYPTO_set_ex_data.3,v 1.15 2023/09/18 14:49:43 schwarze Exp $ 2.\" 3.\" Copyright (c) 2023 Ingo Schwarze <schwarze@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: September 18 2023 $ 18.Dt CRYPTO_SET_EX_DATA 3 19.Os 20.Sh NAME 21.Nm CRYPTO_get_ex_new_index , 22.Nm CRYPTO_EX_new , 23.Nm CRYPTO_EX_free , 24.Nm CRYPTO_EX_dup , 25.Nm CRYPTO_new_ex_data , 26.Nm CRYPTO_set_ex_data , 27.Nm CRYPTO_get_ex_data , 28.Nm CRYPTO_free_ex_data 29.Nd low-level functions for application specific data 30.Sh SYNOPSIS 31.In openssl/crypto.h 32.Ft int 33.Fo CRYPTO_get_ex_new_index 34.Fa "int class_index" 35.Fa "long argl" 36.Fa "void *argp" 37.Fa "CRYPTO_EX_new *new_func" 38.Fa "CRYPTO_EX_dup *dup_func" 39.Fa "CRYPTO_EX_free *free_func" 40.Fc 41.Ft typedef int 42.Fo CRYPTO_EX_new 43.Fa "void *parent" 44.Fa "void *data" 45.Fa "CRYPTO_EX_DATA *ad" 46.Fa "int idx" 47.Fa "long argl" 48.Fa "void *argp" 49.Fc 50.Ft typedef void 51.Fo CRYPTO_EX_free 52.Fa "void *parent" 53.Fa "void *data" 54.Fa "CRYPTO_EX_DATA *ad" 55.Fa "int idx" 56.Fa "long argl" 57.Fa "void *argp" 58.Fc 59.Ft typedef int 60.Fo CRYPTO_EX_dup 61.Fa "CRYPTO_EX_DATA *to" 62.Fa "const CRYPTO_EX_DATA *from" 63.Fa "void *datap" 64.Fa "int idx" 65.Fa "long argl" 66.Fa "void *argp" 67.Fc 68.Ft int 69.Fo CRYPTO_new_ex_data 70.Fa "int class_index" 71.Fa "void *parent" 72.Fa "CRYPTO_EX_DATA *ad" 73.Fc 74.Ft int 75.Fo CRYPTO_set_ex_data 76.Fa "CRYPTO_EX_DATA *ad" 77.Fa "int idx" 78.Fa "void *data" 79.Fc 80.Ft void * 81.Fo CRYPTO_get_ex_data 82.Fa "CRYPTO_EX_DATA *ad" 83.Fa "int idx" 84.Fc 85.Ft void 86.Fo CRYPTO_free_ex_data 87.Fa "int class_index" 88.Fa "void *parent" 89.Fa "CRYPTO_EX_DATA *ad" 90.Fc 91.Sh DESCRIPTION 92The library implements the functions documented in the 93.Xr RSA_get_ex_new_index 3 94manual page and similar functions for other parent object types 95using the functions documented in the present manual page. 96Application programs almost never need 97to call the functions documented here directly. 98.Pp 99.Fn CRYPTO_get_ex_new_index 100behaves in the same way as 101.Xr RSA_get_ex_new_index 3 102except that the parent object type that the new 103.Fa idx 104is reserved for is not part of the function name 105but instead specified by the additional 106.Fa class_index 107argument receiving one of the 108.Dv CRYPTO_EX_INDEX_* 109constants defined in 110.In openssl/crypto.h . 111The recommendation given in 112.Xr RSA_get_ex_new_index 3 113to set the 114.Fa argl 115argument to 0 and the last four arguments all to 116.Dv NULL 117applies. 118The library passes the 119.Fa argl 120and 121.Fa argp 122arguments through to the callback functions for the respective 123.Fa idx , 124but ignores them otherwise. 125.Pp 126If a function pointer is passed for the 127.Fa new_func 128argument, that function is called for the returned 129.Fa idx 130whenever a new parent object is allocated with 131.Xr RSA_new 3 132or a similar function. 133.Pp 134If a function pointer is passed for the 135.Fa free_func 136argument, that function is called for the returned 137.Fa idx 138when a parent object is freed with 139.Xr RSA_free 3 140or a similar function. 141.Pp 142The arguments of 143.Fa new_func 144and 145.Fa free_func 146are as follows: 147.Pp 148.Bl -tag -width Ds -compact 149.It Fa parent 150the parent object that contains the 151.Fa data 152.It Fa data 153the 154.Fa data 155previously set by 156.Fn CRYPTO_set_ex_data 157at 158.Fa idx 159in 160.Fa parent 161.It Fa ad 162the 163.Vt CRYPTO_EX_DATA 164subobject of the 165.Fa parent 166object 167.It Fa idx 168return value of 169.Fn CRYPTO_get_ex_new_index 170that set this callback 171.It Fa argl 172the 173.Fa argl 174passed to 175.Fn CRYPTO_get_ex_new_index 176for this 177.Fa idx 178.It Fa argp 179the 180.Fa argp 181passed to 182.Fn CRYPTO_get_ex_new_index 183for this 184.Fa idx 185.El 186.Pp 187If a function pointer is passed for the 188.Fa dup_func , 189that function is supposed to be called for the returned 190.Fa idx 191whenever a parent object of the respective type is copied. 192Actually, the only functions doing that are 193.Xr BIO_dup_chain 3 , 194.Xr EC_KEY_copy 3 , 195and 196.Xr SSL_dup 3 , 197and the TLS 1.3 network stack does it internally when duplicating a 198.Vt SSL_SESSION 199object after receiving a new session ticket message. 200Most other object types supporting ex_data do not support 201copying in the first place, whereas 202.Xr DSA_dup_DH 3 203and 204.Xr X509_dup 3 205simply ignore 206.Fa dup_func . 207.Pp 208The arguments of 209.Fa dup_func 210are as follows: 211.Pp 212.Bl -tag -width Ds -compact 213.It Fa to 214the 215.Vt CRYPTO_EX_DATA 216subobject of the new parent object 217.It Fa from 218the 219.Vt CRYPTO_EX_DATA 220subobject of the original parent object 221.It Fa datap 222a pointer to a copy of the pointer to the original ex_data 223.It Fa idx 224return value of 225.Fn CRYPTO_get_ex_new_index 226that set this callback 227.It Fa argl 228the 229.Fa argl 230passed to 231.Fn CRYPTO_get_ex_new_index 232for this 233.Fa idx 234.It Fa argp 235the 236.Fa argp 237passed to 238.Fn CRYPTO_get_ex_new_index 239for this 240.Fa idx 241.El 242.Pp 243Inside 244.Fa dup_func , 245the 246.Fa data 247pointer contained in the original parent object being copied 248can be accessed by casting and dereferencing 249.Fa datap , 250for example: 251.Pp 252.Dl char *orig_data = *(char **)datap; 253.Pp 254If the original data is copied, for example in a manner similar to 255.Bd -literal -offset indent 256char *new_data; 257if ((new_data = strdup(orig_data)) == NULL) 258 return 0; 259.Ed 260.Pp 261then the pointer to the newly allocated memory needs to be passed 262back to the caller in the 263.Fa datap 264argument, for example: 265.Bd -literal -offset indent 266*(char **)datap = new_data; 267return 1; 268.Ed 269.Pp 270Calling 271.Fn CRYPTO_set_ex_data to idx new_data 272from inside 273.Fa dup_func 274has no effect because the code calling 275.Fa dup_func 276unconditionally calls 277.Fn CRYPTO_set_ex_data to idx *datap 278after 279.Fa dup_func 280returns successfully. 281Consequently, if 282.Fa dup_func 283does not change 284.Pf * Fa datap , 285the new parent object ends up containing a pointer to the same memory 286as the original parent object and any memory allocated in 287.Fa dup_func 288is leaked. 289.Pp 290When multiple callback functions are called, 291they are called in increasing order of their 292.Fa idx 293value. 294.Pp 295.Fn CRYPTO_new_ex_data 296is an internal function that initializes the 297.Fa ad 298subobject of the 299.Fa parent 300object, with the type of the parent object specified by the 301.Fa class_index 302argument. 303Initialization includes calling the respective 304.Fa new_func 305callbacks for all reserved 306.Fa idx 307values that have such callbacks configured. 308Despite its name, 309.Fn CRYPTO_new_ex_data 310does not create a new object but requires that 311.Fa ad 312points to an already allocated but still uninitialized object. 313.Pp 314.Fn CRYPTO_set_ex_data 315and 316.Fn CRYPTO_get_ex_data 317behave in the same way as 318.Xr RSA_set_ex_data 3 319and 320.Xr RSA_get_ex_data 3 , 321respectively, except that they do not accept a pointer 322to the parent object but instead require a pointer to the 323.Vt CRYPTO_EX_DATA 324subobject of that parent object. 325.Pp 326.Fn CRYPTO_free_ex_data 327is an internal function that frees any memory used inside the 328.Fa ad 329subobject of the 330.Fa parent 331object, with the type of the parent object specified by the 332.Fa class_index 333argument. 334This includes calling the respective 335.Fa free_func 336callbacks for all reserved 337.Fa idx 338values that have such callbacks configured. 339Despite its name, 340.Fn CRYPTO_free_ex_data 341does not free 342.Fa ad 343itself. 344.Sh RETURN VALUES 345.Fn CRYPTO_get_ex_new_index 346returns a new index equal to or greater than 1 347or \-1 if memory allocation fails. 348.Pp 349.Fn CRYPTO_EX_new 350and 351.Fn CRYPTO_EX_dup 352functions are supposed to return 1 on success or 0 on failure. 353.Pp 354.Fn CRYPTO_new_ex_data 355and 356.Fn CRYPTO_set_ex_data 357return 1 on success or 0 if memory allocation fails. 358.Pp 359.Fn CRYPTO_get_ex_data 360returns the application specific data or 361.Dv NULL 362if the parent object that contains 363.Fa ad 364does not contain application specific data at the given 365.Fa idx . 366.Sh ERRORS 367After failure of 368.Fn CRYPTO_get_ex_new_index , 369.Fn CRYPTO_new_ex_data , 370or 371.Fn CRYPTO_set_ex_data , 372the following diagnostic can be retrieved with 373.Xr ERR_get_error 3 , 374.Xr ERR_GET_REASON 3 , 375and 376.Xr ERR_reason_error_string 3 : 377.Bl -tag -width Ds 378.It Dv ERR_R_MALLOC_FAILURE Qq "malloc failure" 379Memory allocation failed. 380.El 381.Pp 382In a few unusual failure cases, 383.Xr ERR_get_error 3 384may report different errors caused by 385.Xr OPENSSL_init_crypto 3 386or even none at all. 387.Pp 388Even though it cannot indicate failure, 389.Fn CRYPTO_free_ex_data 390may occasionally also set an error code that can be retrieved with 391.Xr ERR_get_error 3 . 392.Pp 393.Fn CRYPTO_get_ex_data 394does not distinguish success from failure. 395Consequently, after 396.Fn CRYPTO_get_ex_data 397returns 398.Dv NULL , 399.Xr ERR_get_error 3 400returns 0 unless there is still an earlier error in the queue. 401.Sh SEE ALSO 402.Xr BIO_get_ex_new_index 3 , 403.Xr DH_get_ex_new_index 3 , 404.Xr DSA_get_ex_new_index 3 , 405.Xr RSA_get_ex_new_index 3 , 406.Xr SSL_CTX_get_ex_new_index 3 , 407.Xr SSL_get_ex_new_index 3 , 408.Xr SSL_SESSION_get_ex_new_index 3 , 409.Xr X509_STORE_CTX_get_ex_new_index 3 , 410.Xr X509_STORE_get_ex_new_index 3 411.Sh HISTORY 412.Fn CRYPTO_get_ex_new_index , 413.Fn CRYPTO_new_ex_data , 414.Fn CRYPTO_set_ex_data , 415.Fn CRYPTO_get_ex_data , 416and 417.Fn CRYPTO_free_ex_data 418first appeared in SSLeay 0.9.0 and have been available since 419.Ox 2.4 . 420.Pp 421.Fn CRYPTO_EX_new , 422.Fn CRYPTO_EX_free , 423and 424.Fn CRYPTO_EX_dup 425first appeared in OpenSSL 0.9.5 and have been available since 426.Ox 2.7 . 427.Sh CAVEATS 428If an program installs callback functions, the last call to 429.Fn CRYPTO_get_ex_new_index 430installing a function of a certain type for a certain 431.Fa class_index 432needs to be complete before the first object of that 433.Fa class_index 434can be created, freed, or copied, respectively. 435Otherwise, incomplete initialization or cleanup will result. 436.Pp 437At the time 438.Fa new_func 439is called, the 440.Fa parent 441object is only partially initialized, 442so trying to access any data in it is strongly discouraged. 443The 444.Fa data 445argument is typically 446.Dv NULL 447in 448.Fa new_func . 449.Pp 450At the time 451.Fa free_func 452is called, the 453.Fa parent 454object is already mostly deconstructed 455and part of its content may have been cleared and freed. 456Consequently, trying to access any data in 457.Fa parent 458is strongly discouraged. 459According to the OpenSSL API documentation, the library code calling 460.Fa free_func 461would even be permitted to pass a 462.Dv NULL 463pointer for the 464.Fa parent 465argument. 466.Pp 467.Fn CRYPTO_set_ex_data 468and 469.Fn CRYPTO_get_ex_data 470cannot reasonably be used outside the callback functions 471because no API function provides access to any pointers of the type 472.Vt CRYPTO_EX_DATA * . 473.Pp 474Inside 475.Fa new_func , 476calling 477.Fn CRYPTO_get_ex_data 478makes no sense because it always returns 479.Dv NULL , 480and calling 481.Fn CRYPTO_set_ex_data 482makes no sense because 483.Fa new_func 484does not have access to any meaningful 485.Fa data 486it could store, and the absence of application specific data at any given 487.Fa idx 488is already sufficiently indicated by the default return value 489.Dv NULL 490of 491.Fn CRYPTO_get_ex_data , 492.Xr RSA_get_ex_data 3 , 493and similar functions. 494.Pp 495Inside 496.Fa free_func , 497calling 498.Fn CRYPTO_get_ex_data 499makes no sense because the return value is already available in 500.Fa data , 501and calling 502.Fn CRYPTO_set_ex_data 503makes no sense because the parent object, including any ex_data 504contained in it, is already being deconstructed and will no longer 505exist by the time application code regains control. 506.Pp 507Inside 508.Fa dup_func , 509calling 510.Fn CRYPTO_get_ex_data 511makes no sense because the return value for 512.Fa from 513is already available as 514.Pf * Fa datap , 515and the return value for 516.Fa to 517is 518.Dv NULL . 519Calling 520.Fn CRYPTO_set_ex_data 521makes no sense because changing 522.Fa from 523would cause an undesirable side effect in this context 524and trying to change 525.Fa to 526is ineffective as explained above. 527.Pp 528Consequently, application code can never use 529.Fn CRYPTO_set_ex_data 530or 531.Fn CRYPTO_get_ex_data 532in a meaningful way. 533.Pp 534The fact that the functions documented in the present manual page 535are part of the public API might create the impression 536that application programs could add ex_data support 537to additional object types not offering it by default. 538However, for built-in object types not offering ex_support, this 539is not possible because such objects do not contain the required 540.Vt CRYPTO_EX_DATA 541subobject. 542.Pp 543It is theoretically possible to add ex_data support to an 544application-defined object type by adding a 545.Vt CRYPTO_EX_DATA 546field to the struct declaration, a call to 547.Fn CRYPTO_new_ex_data 548to the object constructor, and a call to 549.Fn CRYPTO_free_ex_data 550to the object destructor. 551The OpenSSL documentation mentions that the constant 552.Dv CRYPTO_EX_INDEX_APP 553is reserved for this very purpose. 554However, doing this would hardly be useful. 555It is much more straightforward to just add 556all the required data fields to the struct declaration itself. 557.Sh BUGS 558If 559.Fa new_func 560or 561.Fa dup_func 562fails, the failure is silently ignored by the library, potentially 563resulting in an incompletely initialized object. 564The application program cannot detect this kind of failure. 565