From aa4d426b4d3527d7e166df1a05058c9a4a0f6683 Mon Sep 17 00:00:00 2001 From: Wojtek Kosior Date: Fri, 30 Apr 2021 00:33:56 +0200 Subject: initial/final commit --- .../doc/crypto/CRYPTO_get_ex_new_index.pod | 166 +++++++++++++++++++++ 1 file changed, 166 insertions(+) create mode 100644 openssl-1.1.0h/doc/crypto/CRYPTO_get_ex_new_index.pod (limited to 'openssl-1.1.0h/doc/crypto/CRYPTO_get_ex_new_index.pod') diff --git a/openssl-1.1.0h/doc/crypto/CRYPTO_get_ex_new_index.pod b/openssl-1.1.0h/doc/crypto/CRYPTO_get_ex_new_index.pod new file mode 100644 index 0000000..a5bf620 --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/CRYPTO_get_ex_new_index.pod @@ -0,0 +1,166 @@ +=pod + +=head1 NAME + +CRYPTO_EX_new, CRYPTO_EX_free, CRYPTO_EX_dup, +CRYPTO_free_ex_index, CRYPTO_get_ex_new_index, CRYPTO_set_ex_data, +CRYPTO_get_ex_data, CRYPTO_free_ex_data, CRYPTO_new_ex_data +- functions supporting application-specific data + +=head1 SYNOPSIS + + #include + + int CRYPTO_get_ex_new_index(int class_index, + long argl, void *argp, + CRYPTO_EX_new *new_func, + CRYPTO_EX_dup *dup_func, + CRYPTO_EX_free *free_func); + + typedef void CRYPTO_EX_new(void *parent, void *ptr, CRYPTO_EX_DATA *ad, + int idx, long argl, void *argp); + typedef void CRYPTO_EX_free(void *parent, void *ptr, CRYPTO_EX_DATA *ad, + int idx, long argl, void *argp); + typedef int CRYPTO_EX_dup(CRYPTO_EX_DATA *to, const CRYPTO_EX_DATA *from, + void *from_d, int idx, long argl, void *argp); + + int CRYPTO_new_ex_data(int class_index, void *obj, CRYPTO_EX_DATA *ad) + + int CRYPTO_set_ex_data(CRYPTO_EX_DATA *r, int idx, void *arg); + + void *CRYPTO_get_ex_data(CRYPTO_EX_DATA *r, int idx); + + void CRYPTO_free_ex_data(int class_index, void *obj, CRYPTO_EX_DATA *r); + + int CRYPTO_free_ex_index(int class_index, int idx); + +=head1 DESCRIPTION + +Several OpenSSL structures can have application-specific data attached to them, +known as "exdata." +The specific structures are: + + SSL + SSL_CTX + SSL_SESSION + X509 + X509_STORE + X509_STORE_CTX + DH + DSA + EC_KEY + RSA + ENGINE + UI + UI_METHOD + BIO + +Each is identified by an B define in the B +header file. In addition, B is reserved for +applications to use this facility for their own structures. + +The API described here is used by OpenSSL to manipulate exdata for specific +structures. Since the application data can be anything at all it is passed +and retrieved as a B type. + +The B type is opaque. To initialize the exdata part of +a structure, call CRYPTO_new_ex_data(). This is only necessary for +B objects. + +Exdata types are identified by an B, an integer guaranteed to be +unique within structures for the lifetime of the program. Applications +using exdata typically call B at startup, and +store the result in a global variable, or write a wrapper function to +provide lazy evaluation. The B should be one of the +B values. The B and B parameters are saved +to be passed to the callbacks but are otherwise not used. In order to +transparently manipulate exdata, three callbacks must be provided. The +semantics of those callbacks are described below. + +When copying or releasing objects with exdata, the callback functions +are called in increasing order of their B value. + +If a dynamic library can be unloaded, it should call CRYPTO_free_ex_index() +when this is done. +This will replace the callbacks with no-ops +so that applications don't crash. Any existing exdata will be leaked. + +To set or get the exdata on an object, the appropriate type-specific +routine must be used. This is because the containing structure is opaque +and the B field is not accessible. In both API's, the +B parameter should be an already-created index value. + +When setting exdata, the pointer specified with a particular index is saved, +and returned on a subsequent "get" call. If the application is going to +release the data, it must make sure to set a B value at the index, +to avoid likely double-free crashes. + +The function B is used to free all exdata attached +to a structure. The appropriate type-specific routine must be used. +The B identifies the structure type, the B is +be the pointer to the actual structure, and B is a pointer to the +structure's exdata field. + +=head2 Callback Functions + +This section describes how the callback functions are used. Applications +that are defining their own exdata using B must +call them as described here. + +When a structure is initially allocated (such as RSA_new()) then the +new_func() is called for every defined index. There is no requirement +that the entire parent, or containing, structure has been set up. +The new_func() is typically used only to allocate memory to store the +exdata, and perhaps an "initialized" flag within that memory. +The exdata value should be set by calling CRYPTO_set_ex_data(). + +When a structure is free'd (such as SSL_CTX_free()) then the +free_func() is called for every defined index. Again, the state of the +parent structure is not guaranteed. The free_func() may be called with a +NULL pointer. + +Both new_func() and free_func() take the same parameters. +The B is the pointer to the structure that contains the exdata. +The B is the current exdata item; for new_func() this will typically +be NULL. The B parameter is a pointer to the exdata field of the object. +The B is the index and is the value returned when the callbacks were +initially registered via CRYPTO_get_ex_new_index() and can be used if +the same callback handles different types of exdata. + +dup_func() is called when a structure is being copied. This is only done +for B, B, B objects and B chains via +BIO_dup_chain(). The B and B parameters +are pointers to the destination and source B structures, +respectively. The B parameter needs to be cast to a B +as the API has currently the wrong signature; that will be changed in a +future version. The B<*pptr> is a pointer to the source exdata. +When the dup_func() returns, the value in B<*pptr> is copied to the +destination ex_data. If the pointer contained in B<*pptr> is not modified +by the dup_func(), then both B and B will point to the same data. +The B, B and B parameters are as described for the other +two callbacks. If the dup_func() returns B<0> the whole CRYPTO_dup_ex_data() +will fail. + +=head1 RETURN VALUES + +CRYPTO_get_ex_new_index() returns a new index or -1 on failure; the +value B<0> is reserved for the legacy "app_data" API's. + +CRYPTO_free_ex_index() and +CRYPTO_set_ex_data() return 1 on success or 0 on failure. + +CRYPTO_get_ex_data() returns the application data or NULL on failure; +note that NULL may be a valid value. + +dup_func() should return 0 for failure and 1 for success. + +=head1 COPYRIGHT + +Copyright 2015-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut -- cgit v1.2.3