diff options
author | Rich Salz <rsalz@openssl.org> | 2016-10-26 13:56:48 -0400 |
---|---|---|
committer | Rich Salz <rsalz@openssl.org> | 2016-10-26 13:59:52 -0400 |
commit | 99d63d4662e16afbeff49f29b48f1c87d5558ed0 (patch) | |
tree | 6512ff02cd93985526080f05ab2b5408235b19a9 /doc/crypto/CRYPTO_get_ex_new_index.pod | |
parent | 4f3015bb30b7d95bb97408776b70e6a35fb91e8a (diff) |
Move manpages to man[1357] structure.
Move manpages to manX directories
Add Windows/VMS install fix from Richard Levitte
Update README
Fix typo's
Remove some duplicates
Reviewed-by: Richard Levitte <levitte@openssl.org>
Diffstat (limited to 'doc/crypto/CRYPTO_get_ex_new_index.pod')
-rw-r--r-- | doc/crypto/CRYPTO_get_ex_new_index.pod | 161 |
1 files changed, 0 insertions, 161 deletions
diff --git a/doc/crypto/CRYPTO_get_ex_new_index.pod b/doc/crypto/CRYPTO_get_ex_new_index.pod deleted file mode 100644 index 98085f525b..0000000000 --- a/doc/crypto/CRYPTO_get_ex_new_index.pod +++ /dev/null @@ -1,161 +0,0 @@ -=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 <openssl/crypto.h> - - 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 int 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 - BIO - -Each is identified by an B<CRYPTO_EX_INDEX_xxx> define in the B<crypto.h> -header file. In addition, B<CRYPTO_EX_INDEX_APP> 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<void *> type. - -The B<CRYPTO_EX_DATA> type is opaque. To initialize the exdata part of -a structure, call CRYPTO_new_ex_data(). This is only necessary for -B<CRYPTO_EX_INDEX_APP> objects. - -Exdata types are identified by an B<index>, an integer guaranteed to be -unique within structures for the lifetime of the program. Applications -using exdata typically call B<CRYPTO_get_ex_new_index> at startup, and -store the result in a global variable, or write a wrapper function to -provide lazy evaluation. The B<class_index> should be one of the -B<CRYPTO_EX_INDEX_xxx> values. The B<argl> and B<argp> 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<index> 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<CRYPTO_EX_DATA> field is not accessible. In both API's, the -B<idx> 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<NULL> value at the index, -to avoid likely double-free crashes. - -The function B<CRYPTO_free_ex_data> is used to free all exdata attached -to a structure. The appropriate type-specific routine must be used. -The B<class_index> identifies the structure type, the B<obj> is -be the pointer to the actual structure, and B<r> 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<CYPRTO_EX_INDEX_APP> 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<parent> is the pointer to the structure that contains the exdata. -The B<ptr> is the current exdata item; for new_func() this will typically -be NULL. The B<r> parameter is a pointer to the exdata field of the object. -The B<idx> 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<SSL> and B<SSL_SESSION> objects. The B<to> and B<from> parameters -are pointers to the destination and source B<CRYPTO_EX_DATA> structures, -respectively. The B<srcp> parameter is a pointer to the source exdata. -When the dup_func() returns, the value in B<srcp> is copied to the -destination ex_data. If the pointer contained in B<srcp> is not modified -by the dup_func(), then both B<to> and B<from> will point to the same data. -The B<idx>, B<argl> and B<argp> parameters are as described for the other -two callbacks. - -=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-2016 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<https://www.openssl.org/source/license.html>. - -=cut |