diff options
author | Rich Salz <rsalz@akamai.com> | 2015-07-21 10:06:03 -0400 |
---|---|---|
committer | Rich Salz <rsalz@openssl.org> | 2015-12-01 11:48:37 -0500 |
commit | e6390acac925f952cfd06ccdbba0b273b8f71551 (patch) | |
tree | 219e865d2b4e0a2b362429e56829d5caf1b69ced /doc | |
parent | d59c7c81e3850dc667d61047850c3b6936eb5fca (diff) | |
download | openssl-e6390acac925f952cfd06ccdbba0b273b8f71551.tar.gz |
ex_data part 2: doc fixes and CRYPTO_free_ex_index.
Add CRYPTO_free_ex_index (for shared libraries)
Unify and complete the documentation for all "ex_data" API's and objects.
Replace xxx_get_ex_new_index functions with a macro.
Added an exdata test.
Renamed the ex_data internal datatypes.
Reviewed-by: Matt Caswell <matt@openssl.org>
Diffstat (limited to 'doc')
-rw-r--r-- | doc/crypto/BIO_get_ex_new_index.pod | 45 | ||||
-rw-r--r-- | doc/crypto/CRYPTO_get_ex_new_index.pod | 145 | ||||
-rw-r--r-- | doc/crypto/CRYPTO_set_ex_data.pod | 49 | ||||
-rw-r--r-- | doc/crypto/DH_get_ex_new_index.pod | 31 | ||||
-rw-r--r-- | doc/crypto/DSA_get_ex_new_index.pod | 31 | ||||
-rw-r--r-- | doc/crypto/RSA_get_ex_new_index.pod | 115 | ||||
-rw-r--r-- | doc/crypto/X509_STORE_CTX_get_ex_new_index.pod | 36 | ||||
-rw-r--r-- | doc/crypto/dh.pod | 5 | ||||
-rw-r--r-- | doc/crypto/dsa.pod | 5 | ||||
-rw-r--r-- | doc/crypto/ecdsa.pod | 7 | ||||
-rw-r--r-- | doc/crypto/engine.pod | 6 | ||||
-rw-r--r-- | doc/crypto/rsa.pod | 5 | ||||
-rw-r--r-- | doc/ssl/SSL_CTX_get_ex_new_index.pod | 53 | ||||
-rw-r--r-- | doc/ssl/SSL_SESSION_get_ex_new_index.pod | 61 | ||||
-rw-r--r-- | doc/ssl/SSL_get_ex_data_X509_STORE_CTX_idx.pod | 61 | ||||
-rw-r--r-- | doc/ssl/SSL_get_ex_new_index.pod | 59 |
16 files changed, 190 insertions, 524 deletions
diff --git a/doc/crypto/BIO_get_ex_new_index.pod b/doc/crypto/BIO_get_ex_new_index.pod new file mode 100644 index 0000000000..4824b5d9a0 --- /dev/null +++ b/doc/crypto/BIO_get_ex_new_index.pod @@ -0,0 +1,45 @@ +=pod + +=head1 NAME + +BIO_get_ex_new_index, BIO_set_ex_data, BIO_get_ex_data, +ENGINE_get_ex_new_index, ENGINE_set_ex_data, ENGINE_get_ex_data, +UI_get_ex_new_index, UI_set_ex_data, UI_get_ex_data, +X509_get_ex_new_index, X509_set_ex_data, X509_get_ex_data, +X509_STORE_get_ex_new_index, X509_STORE_set_ex_data, X509_STORE_get_ex_data, +X509_STORE_CTX_get_ex_new_index, X509_STORE_CTX_set_ex_data, X509_STORE_CTX_get_ex_data, +DH_get_ex_new_index, DH_set_ex_data, DH_get_ex_data, +DSA_get_ex_new_index, DSA_set_ex_data, DSA_get_ex_data, +ECDH_get_ex_new_index, ECDH_set_ex_data, ECDH_get_ex_data, +ECDSA_get_ex_new_index, ECDSA_set_ex_data, ECDSA_get_ex_data, +RSA_get_ex_new_index, RSA_set_ex_data, RSA_get_ex_data +- application-specific data + +=head1 SYNOPSIS + +The synopsis below is for the X509 structure, but is the same for all +crypto structures: + + #include <openssl/x509.h> + + int X509_get_ex_new_index(long argl, void *argp, + CRYPTO_EX_new *new_func, + CRYPTO_EX_dup *dup_func, + CRYPTO_EX_free *free_func); + + int X509_set_ex_data(X509 *d, int idx, void *arg); + + void *X509_get_ex_data(X509 *d, int idx); + +=head1 DESCRIPTION + +These functions handle application-specific data for OpenSSL crypto +structures. + +For details, see L<CRYPTO_get_ex_new_index(3)>. + +=head1 SEE ALSO + +L<CRYPTO_get_ex_new_index(3)>. + +=cut diff --git a/doc/crypto/CRYPTO_get_ex_new_index.pod b/doc/crypto/CRYPTO_get_ex_new_index.pod new file mode 100644 index 0000000000..9d047a4685 --- /dev/null +++ b/doc/crypto/CRYPTO_get_ex_new_index.pod @@ -0,0 +1,145 @@ +=pod + +=head1 NAME + +CRYPTO_free_ex_index, CRYPTO_get_ex_new_index, CRYPTO_set_ex_data, +CRYPTO_get_ex_data, CRYPTO_free_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, CRYPTO_EX_DATA *from, + void *from_d, int idx, long argl, void *argp); + + 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 + ECDH + ECDSA + 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. + +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 crash. + +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, +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. + +=cut diff --git a/doc/crypto/CRYPTO_set_ex_data.pod b/doc/crypto/CRYPTO_set_ex_data.pod deleted file mode 100644 index 68ac6fa1c6..0000000000 --- a/doc/crypto/CRYPTO_set_ex_data.pod +++ /dev/null @@ -1,49 +0,0 @@ -=pod - -=head1 NAME - -CRYPTO_set_ex_data, CRYPTO_get_ex_data - internal application specific data functions - -=head1 SYNOPSIS - - #include <openssl/crypto.h> - - int CRYPTO_set_ex_data(CRYPTO_EX_DATA *r, int idx, void *arg); - - void *CRYPTO_get_ex_data(CRYPTO_EX_DATA *r, int idx); - -=head1 DESCRIPTION - -Several OpenSSL structures can have application specific data attached to them. -These functions are used internally by OpenSSL to manipulate application -specific data attached to a specific structure. - -These functions should only be used by applications to manipulate -B<CRYPTO_EX_DATA> structures passed to the new_func(), free_func() and -dup_func() callbacks: as passed to RSA_get_ex_new_index() for example. - -CRYPTO_set_ex_data() is used to set application specific data, the data is -supplied in the B<arg> parameter and its precise meaning is up to the -application. - -CRYPTO_get_ex_data() is used to retrieve application specific data. The data -is returned to the application, this will be the same value as supplied to -a previous CRYPTO_set_ex_data() call. - -=head1 RETURN VALUES - -CRYPTO_set_ex_data() returns 1 on success or 0 on failure. - -CRYPTO_get_ex_data() returns the application data or 0 on failure. 0 may also -be valid application data but currently it can only fail if given an invalid B<idx> -parameter. - -On failure an error code can be obtained from L<ERR_get_error(3)>. - -=head1 SEE ALSO - -L<RSA_get_ex_new_index(3)>, -L<DSA_get_ex_new_index(3)>, -L<DH_get_ex_new_index(3)> - -=cut diff --git a/doc/crypto/DH_get_ex_new_index.pod b/doc/crypto/DH_get_ex_new_index.pod deleted file mode 100644 index 0c113c7304..0000000000 --- a/doc/crypto/DH_get_ex_new_index.pod +++ /dev/null @@ -1,31 +0,0 @@ -=pod - -=head1 NAME - -DH_get_ex_new_index, DH_set_ex_data, DH_get_ex_data - add application specific data to DH structures - -=head1 SYNOPSIS - - #include <openssl/dh.h> - - int DH_get_ex_new_index(long argl, void *argp, - CRYPTO_EX_new *new_func, - CRYPTO_EX_dup *dup_func, - CRYPTO_EX_free *free_func); - - int DH_set_ex_data(DH *d, int idx, void *arg); - - char *DH_get_ex_data(DH *d, int idx); - -=head1 DESCRIPTION - -These functions handle application specific data in DH -structures. Their usage is identical to that of -RSA_get_ex_new_index(), RSA_set_ex_data() and RSA_get_ex_data() -as described in L<RSA_get_ex_new_index(3)>. - -=head1 SEE ALSO - -L<RSA_get_ex_new_index(3)>, L<dh(3)> - -=cut diff --git a/doc/crypto/DSA_get_ex_new_index.pod b/doc/crypto/DSA_get_ex_new_index.pod deleted file mode 100644 index b9ed01b01a..0000000000 --- a/doc/crypto/DSA_get_ex_new_index.pod +++ /dev/null @@ -1,31 +0,0 @@ -=pod - -=head1 NAME - -DSA_get_ex_new_index, DSA_set_ex_data, DSA_get_ex_data - add application specific data to DSA structures - -=head1 SYNOPSIS - - #include <openssl/dsa.h> - - int DSA_get_ex_new_index(long argl, void *argp, - CRYPTO_EX_new *new_func, - CRYPTO_EX_dup *dup_func, - CRYPTO_EX_free *free_func); - - int DSA_set_ex_data(DSA *d, int idx, void *arg); - - char *DSA_get_ex_data(DSA *d, int idx); - -=head1 DESCRIPTION - -These functions handle application specific data in DSA -structures. Their usage is identical to that of -RSA_get_ex_new_index(), RSA_set_ex_data() and RSA_get_ex_data() -as described in L<RSA_get_ex_new_index(3)>. - -=head1 SEE ALSO - -L<RSA_get_ex_new_index(3)>, L<dsa(3)> - -=cut diff --git a/doc/crypto/RSA_get_ex_new_index.pod b/doc/crypto/RSA_get_ex_new_index.pod deleted file mode 100644 index 7022459f1b..0000000000 --- a/doc/crypto/RSA_get_ex_new_index.pod +++ /dev/null @@ -1,115 +0,0 @@ -=pod - -=head1 NAME - -RSA_get_ex_new_index, RSA_set_ex_data, RSA_get_ex_data - add application specific data to RSA structures - -=head1 SYNOPSIS - - #include <openssl/rsa.h> - - int RSA_get_ex_new_index(long argl, void *argp, - CRYPTO_EX_new *new_func, - CRYPTO_EX_dup *dup_func, - CRYPTO_EX_free *free_func); - - int RSA_set_ex_data(RSA *r, int idx, void *arg); - - void *RSA_get_ex_data(RSA *r, int idx); - - 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, CRYPTO_EX_DATA *from, void *from_d, - int idx, long argl, void *argp); - -=head1 DESCRIPTION - -Several OpenSSL structures can have application specific data attached to them. -This has several potential uses, it can be used to cache data associated with -a structure (for example the hash of some part of the structure) or some -additional data (for example a handle to the data in an external library). - -Since the application data can be anything at all it is passed and retrieved -as a B<void *> type. - -The RSA_get_ex_new_index() function is initially called to "register" some -new application specific data. It takes three optional function pointers which -are called when the parent structure (in this case an RSA structure) is -initially created, when it is copied and when it is freed up. If any or all of -these function pointer arguments are not used they should be set to NULL. The -precise manner in which these function pointers are called is described in more -detail below. RSA_get_ex_new_index() also takes additional long and pointer -parameters which will be passed to the supplied functions but which otherwise -have no special meaning. It returns an B<index> which should be stored -(typically in a static variable) and passed used in the B<idx> parameter in -the remaining functions. Each successful call to RSA_get_ex_new_index() -will return an index greater than any previously returned, this is important -because the optional functions are called in order of increasing index value. - -RSA_set_ex_data() is used to set application specific data, the data is -supplied in the B<arg> parameter and its precise meaning is up to the -application. - -RSA_get_ex_data() is used to retrieve application specific data. The data -is returned to the application, this will be the same value as supplied to -a previous RSA_set_ex_data() call. - -new_func() is called when a structure is initially allocated (for example -with RSA_new(). The parent structure members will not have any meaningful -values at this point. This function will typically be used to allocate any -application specific structure. - -free_func() is called when a structure is being freed up. The dynamic parent -structure members should not be accessed because they will be freed up when -this function is called. - -new_func() and free_func() take the same parameters. B<parent> is a -pointer to the parent RSA structure. B<ptr> is a the application specific data -(this wont be of much use in new_func(). B<ad> is a pointer to the -B<CRYPTO_EX_DATA> structure from the parent RSA structure: the functions -CRYPTO_get_ex_data() and CRYPTO_set_ex_data() can be called to manipulate -it. The B<idx> parameter is the index: this will be the same value returned by -RSA_get_ex_new_index() when the functions were initially registered. Finally -the B<argl> and B<argp> parameters are the values originally passed to the same -corresponding parameters when RSA_get_ex_new_index() was called. - -dup_func() is called when a structure is being copied. Pointers to the -destination and source B<CRYPTO_EX_DATA> structures are passed in the B<to> and -B<from> parameters respectively. The B<from_d> parameter is passed a pointer to -the source application data when the function is called, when the function returns -the value is copied to the destination: the application can thus modify the data -pointed to by B<from_d> and have different values in the source and destination. -The B<idx>, B<argl> and B<argp> parameters are the same as those in new_func() -and free_func(). - -=head1 RETURN VALUES - -RSA_get_ex_new_index() returns a new index or -1 on failure (note 0 is a valid -index value). - -RSA_set_ex_data() returns 1 on success or 0 on failure. - -RSA_get_ex_data() returns the application data or 0 on failure. 0 may also -be valid application data but currently it can only fail if given an invalid B<idx> -parameter. - -new_func() and dup_func() should return 0 for failure and 1 for success. - -On failure an error code can be obtained from L<ERR_get_error(3)>. - -=head1 BUGS - -dup_func() is currently never called. - -The return value of new_func() is ignored. - -The new_func() function isn't very useful because no meaningful values are -present in the parent RSA structure when it is called. - -=head1 SEE ALSO - -L<rsa(3)>, L<CRYPTO_set_ex_data(3)> - -=cut diff --git a/doc/crypto/X509_STORE_CTX_get_ex_new_index.pod b/doc/crypto/X509_STORE_CTX_get_ex_new_index.pod deleted file mode 100644 index f708329b5b..0000000000 --- a/doc/crypto/X509_STORE_CTX_get_ex_new_index.pod +++ /dev/null @@ -1,36 +0,0 @@ -=pod - -=head1 NAME - -X509_STORE_CTX_get_ex_new_index, X509_STORE_CTX_set_ex_data, X509_STORE_CTX_get_ex_data - add application specific data to X509_STORE_CTX structures - -=head1 SYNOPSIS - - #include <openssl/x509_vfy.h> - - int X509_STORE_CTX_get_ex_new_index(long argl, void *argp, - CRYPTO_EX_new *new_func, - CRYPTO_EX_dup *dup_func, - CRYPTO_EX_free *free_func); - - int X509_STORE_CTX_set_ex_data(X509_STORE_CTX *d, int idx, void *arg); - - void *X509_STORE_CTX_get_ex_data(X509_STORE_CTX *d, int idx); - -=head1 DESCRIPTION - -These functions handle application specific data in X509_STORE_CTX structures. -Their usage is identical to that of RSA_get_ex_new_index(), RSA_set_ex_data() -and RSA_get_ex_data() as described in L<RSA_get_ex_new_index(3)>. - -=head1 NOTES - -This mechanism is used internally by the B<ssl> library to store the B<SSL> -structure associated with a verification operation in an B<X509_STORE_CTX> -structure. - -=head1 SEE ALSO - -L<RSA_get_ex_new_index(3)> - -=cut diff --git a/doc/crypto/dh.pod b/doc/crypto/dh.pod index 6115e8c257..ce6a110895 100644 --- a/doc/crypto/dh.pod +++ b/doc/crypto/dh.pod @@ -25,11 +25,6 @@ dh - Diffie-Hellman key agreement DH *DH_new_method(ENGINE *engine); const DH_METHOD *DH_OpenSSL(void); - int DH_get_ex_new_index(long argl, char *argp, int (*new_func)(), - int (*dup_func)(), void (*free_func)()); - int DH_set_ex_data(DH *d, int idx, char *arg); - char *DH_get_ex_data(DH *d, int idx); - DH * d2i_DHparams(DH **a, unsigned char **pp, long length); int i2d_DHparams(const DH *a, unsigned char **pp); diff --git a/doc/crypto/dsa.pod b/doc/crypto/dsa.pod index f0b74c1f4e..9cf1c49c87 100644 --- a/doc/crypto/dsa.pod +++ b/doc/crypto/dsa.pod @@ -35,11 +35,6 @@ dsa - Digital Signature Algorithm DSA *DSA_new_method(ENGINE *engine); const DSA_METHOD *DSA_OpenSSL(void); - int DSA_get_ex_new_index(long argl, char *argp, int (*new_func)(), - int (*dup_func)(), void (*free_func)()); - int DSA_set_ex_data(DSA *d, int idx, char *arg); - char *DSA_get_ex_data(DSA *d, int idx); - DSA_SIG *DSA_SIG_new(void); void DSA_SIG_free(DSA_SIG *a); int i2d_DSA_SIG(const DSA_SIG *a, unsigned char **pp); diff --git a/doc/crypto/ecdsa.pod b/doc/crypto/ecdsa.pod index 1af4feb4db..be0f4826c2 100644 --- a/doc/crypto/ecdsa.pod +++ b/doc/crypto/ecdsa.pod @@ -40,13 +40,6 @@ ECDSA_SIG_new, ECDSA_SIG_free, i2d_ECDSA_SIG, d2i_ECDSA_SIG, ECDSA_size, ECDSA_s const ECDSA_METHOD* ECDSA_get_default_method(void); int ECDSA_set_method(EC_KEY *eckey,const ECDSA_METHOD *meth); - int ECDSA_get_ex_new_index(long argl, void *argp, - CRYPTO_EX_new *new_func, - CRYPTO_EX_dup *dup_func, - CRYPTO_EX_free *free_func); - int ECDSA_set_ex_data(EC_KEY *d, int idx, void *arg); - void* ECDSA_get_ex_data(EC_KEY *d, int idx); - =head1 DESCRIPTION The B<ECDSA_SIG> structure consists of two BIGNUMs for the diff --git a/doc/crypto/engine.pod b/doc/crypto/engine.pod index 4d11b4ab9f..7d2d5d8cd0 100644 --- a/doc/crypto/engine.pod +++ b/doc/crypto/engine.pod @@ -94,12 +94,6 @@ engine - ENGINE cryptographic module support int ENGINE_ctrl_cmd_string(ENGINE *e, const char *cmd_name, const char *arg, int cmd_optional); - int ENGINE_set_ex_data(ENGINE *e, int idx, void *arg); - void *ENGINE_get_ex_data(const ENGINE *e, int idx); - - int ENGINE_get_ex_new_index(long argl, void *argp, CRYPTO_EX_new *new_func, - CRYPTO_EX_dup *dup_func, CRYPTO_EX_free *free_func); - ENGINE *ENGINE_new(void); int ENGINE_free(ENGINE *e); int ENGINE_up_ref(ENGINE *e); diff --git a/doc/crypto/rsa.pod b/doc/crypto/rsa.pod index ac32415e32..9c42923abd 100644 --- a/doc/crypto/rsa.pod +++ b/doc/crypto/rsa.pod @@ -46,11 +46,6 @@ rsa - RSA public key cryptosystem int RSA_print(BIO *bp, RSA *x, int offset); int RSA_print_fp(FILE *fp, RSA *x, int offset); - int RSA_get_ex_new_index(long argl, char *argp, int (*new_func)(), - int (*dup_func)(), void (*free_func)()); - int RSA_set_ex_data(RSA *r,int idx,char *arg); - char *RSA_get_ex_data(RSA *r, int idx); - int RSA_sign_ASN1_OCTET_STRING(int dummy, unsigned char *m, unsigned int m_len, unsigned char *sigret, unsigned int *siglen, RSA *rsa); diff --git a/doc/ssl/SSL_CTX_get_ex_new_index.pod b/doc/ssl/SSL_CTX_get_ex_new_index.pod deleted file mode 100644 index fc72837731..0000000000 --- a/doc/ssl/SSL_CTX_get_ex_new_index.pod +++ /dev/null @@ -1,53 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_get_ex_new_index, SSL_CTX_set_ex_data, SSL_CTX_get_ex_data - internal application specific data functions - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_CTX_get_ex_new_index(long argl, void *argp, - CRYPTO_EX_new *new_func, - CRYPTO_EX_dup *dup_func, - CRYPTO_EX_free *free_func); - - int SSL_CTX_set_ex_data(SSL_CTX *ctx, int idx, void *arg); - - void *SSL_CTX_get_ex_data(const SSL_CTX *ctx, int idx); - - typedef int new_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad, - int idx, long argl, void *argp); - typedef void free_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad, - int idx, long argl, void *argp); - typedef int dup_func(CRYPTO_EX_DATA *to, CRYPTO_EX_DATA *from, void *from_d, - int idx, long argl, void *argp); - -=head1 DESCRIPTION - -Several OpenSSL structures can have application specific data attached to them. -These functions are used internally by OpenSSL to manipulate application -specific data attached to a specific structure. - -SSL_CTX_get_ex_new_index() is used to register a new index for application -specific data. - -SSL_CTX_set_ex_data() is used to store application data at B<arg> for B<idx> -into the B<ctx> object. - -SSL_CTX_get_ex_data() is used to retrieve the information for B<idx> from -B<ctx>. - -A detailed description for the B<*_get_ex_new_index()> functionality -can be found in L<RSA_get_ex_new_index(3)>. -The B<*_get_ex_data()> and B<*_set_ex_data()> functionality is described in -L<CRYPTO_set_ex_data(3)>. - -=head1 SEE ALSO - -L<ssl(3)>, -L<RSA_get_ex_new_index(3)>, -L<CRYPTO_set_ex_data(3)> - -=cut diff --git a/doc/ssl/SSL_SESSION_get_ex_new_index.pod b/doc/ssl/SSL_SESSION_get_ex_new_index.pod deleted file mode 100644 index f5390c1f3a..0000000000 --- a/doc/ssl/SSL_SESSION_get_ex_new_index.pod +++ /dev/null @@ -1,61 +0,0 @@ -=pod - -=head1 NAME - -SSL_SESSION_get_ex_new_index, SSL_SESSION_set_ex_data, SSL_SESSION_get_ex_data - internal application specific data functions - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_SESSION_get_ex_new_index(long argl, void *argp, - CRYPTO_EX_new *new_func, - CRYPTO_EX_dup *dup_func, - CRYPTO_EX_free *free_func); - - int SSL_SESSION_set_ex_data(SSL_SESSION *session, int idx, void *arg); - - void *SSL_SESSION_get_ex_data(const SSL_SESSION *session, int idx); - - typedef int new_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad, - int idx, long argl, void *argp); - typedef void free_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad, - int idx, long argl, void *argp); - typedef int dup_func(CRYPTO_EX_DATA *to, CRYPTO_EX_DATA *from, void *from_d, - int idx, long argl, void *argp); - -=head1 DESCRIPTION - -Several OpenSSL structures can have application specific data attached to them. -These functions are used internally by OpenSSL to manipulate application -specific data attached to a specific structure. - -SSL_SESSION_get_ex_new_index() is used to register a new index for application -specific data. - -SSL_SESSION_set_ex_data() is used to store application data at B<arg> for B<idx> -into the B<session> object. - -SSL_SESSION_get_ex_data() is used to retrieve the information for B<idx> from -B<session>. - -A detailed description for the B<*_get_ex_new_index()> functionality -can be found in L<RSA_get_ex_new_index(3)>. -The B<*_get_ex_data()> and B<*_set_ex_data()> functionality is described in -L<CRYPTO_set_ex_data(3)>. - -=head1 WARNINGS - -The application data is only maintained for sessions held in memory. The -application data is not included when dumping the session with -i2d_SSL_SESSION() (and all functions indirectly calling the dump functions -like PEM_write_SSL_SESSION() and PEM_write_bio_SSL_SESSION()) and can -therefore not be restored. - -=head1 SEE ALSO - -L<ssl(3)>, -L<RSA_get_ex_new_index(3)>, -L<CRYPTO_set_ex_data(3)> - -=cut diff --git a/doc/ssl/SSL_get_ex_data_X509_STORE_CTX_idx.pod b/doc/ssl/SSL_get_ex_data_X509_STORE_CTX_idx.pod deleted file mode 100644 index 2957a2a330..0000000000 --- a/doc/ssl/SSL_get_ex_data_X509_STORE_CTX_idx.pod +++ /dev/null @@ -1,61 +0,0 @@ -=pod - -=head1 NAME - -SSL_get_ex_data_X509_STORE_CTX_idx - get ex_data index to access SSL structure -from X509_STORE_CTX - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_get_ex_data_X509_STORE_CTX_idx(void); - -=head1 DESCRIPTION - -SSL_get_ex_data_X509_STORE_CTX_idx() returns the index number under which -the pointer to the SSL object is stored into the X509_STORE_CTX object. - -=head1 NOTES - -Whenever a X509_STORE_CTX object is created for the verification of the -peers certificate during a handshake, a pointer to the SSL object is -stored into the X509_STORE_CTX object to identify the connection affected. -To retrieve this pointer the X509_STORE_CTX_get_ex_data() function can -be used with the correct index. This index is globally the same for all -X509_STORE_CTX objects and can be retrieved using -SSL_get_ex_data_X509_STORE_CTX_idx(). The index value is set when -SSL_get_ex_data_X509_STORE_CTX_idx() is first called either by the application -program directly or indirectly during other SSL setup functions or during -the handshake. - -The value depends on other index values defined for X509_STORE_CTX objects -before the SSL index is created. - -=head1 RETURN VALUES - -=over 4 - -=item E<gt>=0 - -The index value to access the pointer. - -=item E<lt>0 - -An error occurred, check the error stack for a detailed error message. - -=back - -=head1 EXAMPLES - -The index returned from SSL_get_ex_data_X509_STORE_CTX_idx() allows to -access the SSL object for the connection to be accessed during the -verify_callback() when checking the peers certificate. Please check -the example in L<SSL_CTX_set_verify(3)>, - -=head1 SEE ALSO - -L<ssl(3)>, L<SSL_CTX_set_verify(3)>, -L<CRYPTO_set_ex_data(3)> - -=cut diff --git a/doc/ssl/SSL_get_ex_new_index.pod b/doc/ssl/SSL_get_ex_new_index.pod deleted file mode 100644 index 6c2e919dcc..0000000000 --- a/doc/ssl/SSL_get_ex_new_index.pod +++ /dev/null @@ -1,59 +0,0 @@ -=pod - -=head1 NAME - -SSL_get_ex_new_index, SSL_set_ex_data, SSL_get_ex_data - internal application specific data functions - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_get_ex_new_index(long argl, void *argp, - CRYPTO_EX_new *new_func, - CRYPTO_EX_dup *dup_func, - CRYPTO_EX_free *free_func); - - int SSL_set_ex_data(SSL *ssl, int idx, void *arg); - - void *SSL_get_ex_data(const SSL *ssl, int idx); - - typedef int new_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad, - int idx, long argl, void *argp); - typedef void free_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad, - int idx, long argl, void *argp); - typedef int dup_func(CRYPTO_EX_DATA *to, CRYPTO_EX_DATA *from, void *from_d, - int idx, long argl, void *argp); - -=head1 DESCRIPTION - -Several OpenSSL structures can have application specific data attached to them. -These functions are used internally by OpenSSL to manipulate application -specific data attached to a specific structure. - -SSL_get_ex_new_index() is used to register a new index for application -specific data. - -SSL_set_ex_data() is used to store application data at B<arg> for B<idx> into -the B<ssl> object. - -SSL_get_ex_data() is used to retrieve the information for B<idx> from -B<ssl>. - -A detailed description for the B<*_get_ex_new_index()> functionality -can be found in L<RSA_get_ex_new_index(3)>. -The B<*_get_ex_data()> and B<*_set_ex_data()> functionality is described in -L<CRYPTO_set_ex_data(3)>. - -=head1 EXAMPLES - -An example on how to use the functionality is included in the example -verify_callback() in L<SSL_CTX_set_verify(3)>. - -=head1 SEE ALSO - -L<ssl(3)>, -L<RSA_get_ex_new_index(3)>, -L<CRYPTO_set_ex_data(3)>, -L<SSL_CTX_set_verify(3)> - -=cut |