diff options
author | Rich Salz <rsalz@akamai.com> | 2019-10-18 12:24:39 -0400 |
---|---|---|
committer | Rich Salz <rsalz@akamai.com> | 2019-10-23 08:31:21 -0400 |
commit | d318389eff0fb80d4a88c7af1cc314f185ba94e1 (patch) | |
tree | 5ffff2fcd93266313ffefc4d24585609c7350104 /doc | |
parent | c89799605b833f769ce4cfd879bb291f49b133be (diff) |
Document "get/set-app-data" macros.
Documenting the macros removes 14 undocumented items.
Merged three separate manpages into one.
Rename the DRBG CRYPTO_EX define into RAND_DRBG, but keep the old one
for API compatibility.
Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org>
Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/10216)
Diffstat (limited to 'doc')
-rw-r--r-- | doc/man3/BIO_get_ex_new_index.pod | 36 | ||||
-rw-r--r-- | doc/man3/CRYPTO_get_ex_new_index.pod | 5 | ||||
-rw-r--r-- | doc/man3/RAND_DRBG_set_ex_data.pod | 68 | ||||
-rw-r--r-- | doc/man3/SSL_CTX_set_ex_data.pod | 52 | ||||
-rw-r--r-- | doc/man3/SSL_SESSION_get_ex_data.pod | 47 |
5 files changed, 33 insertions, 175 deletions
diff --git a/doc/man3/BIO_get_ex_new_index.pod b/doc/man3/BIO_get_ex_new_index.pod index 60f49f7e30..0bacb2e0cb 100644 --- a/doc/man3/BIO_get_ex_new_index.pod +++ b/doc/man3/BIO_get_ex_new_index.pod @@ -3,16 +3,27 @@ =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, +BIO_set_app_data, BIO_get_app_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, EC_KEY_get_ex_new_index, EC_KEY_set_ex_data, EC_KEY_get_ex_data, -RSA_get_ex_new_index, RSA_set_ex_data, RSA_get_ex_data +ENGINE_get_ex_new_index, ENGINE_set_ex_data, ENGINE_get_ex_data, +RAND_DRBG_set_ex_data, RAND_DRBG_get_ex_data, RAND_DRBG_get_ex_new_index, +RSA_get_ex_new_index, RSA_set_ex_data, RSA_get_ex_data, +RSA_set_app_data, RSA_get_app_data, +SSL_get_ex_new_index, SSL_set_ex_data, SSL_get_ex_data, +SSL_set_app_data, SSL_get_app_data, +SSL_CTX_get_ex_new_index, SSL_CTX_set_ex_data, SSL_CTX_get_ex_data, +SSL_CTX_set_app_data, SSL_CTX_get_app_data, +SSL_SESSION_get_ex_new_index, SSL_SESSION_set_ex_data, SSL_SESSION_get_ex_data, +SSL_SESSION_set_app_data, SSL_SESSION_get_app_data, +UI_get_ex_new_index, UI_set_ex_data, UI_get_ex_data, +UI_set_app_data, UI_get_app_data, +X509_STORE_CTX_get_ex_new_index, X509_STORE_CTX_set_ex_data, X509_STORE_CTX_get_ex_data, +X509_STORE_CTX_set_app_data, X509_STORE_CTX_get_app_data, +X509_STORE_get_ex_new_index, X509_STORE_set_ex_data, X509_STORE_get_ex_data, +X509_get_ex_new_index, X509_set_ex_data, X509_get_ex_data - application-specific data =head1 SYNOPSIS @@ -30,6 +41,9 @@ RSA_get_ex_new_index, RSA_set_ex_data, RSA_get_ex_data void *TYPE_get_ex_data(TYPE *d, int idx); + #define TYPE_set_app_data(TYPE *d, void *arg) + #define TYPE_get_app_data(TYPE *d) + =head1 DESCRIPTION In the description here, I<TYPE> is used a placeholder @@ -48,6 +62,16 @@ an offset into the opaque exdata part of the TYPE object. TYPE_get_ex_data() is a function that calls CRYPTO_get_ex_data() with an offset into the opaque exdata part of the TYPE object. +For compatibility with previous releases, the exdata index of zero is +reserved for "application data." There are two convenience functions for +this. +TYPE_set_app_data() is a macro that invokes TYPE_set_ex_data() with +B<idx> set to zero. +TYPE_get_app_data() is a macro that invokes TYPE_get_ex_data() with +B<idx> set to zero. +Note that these functions are not defined for the B<RAND_DRBG> type because +there are no backward compatibility concerns. + =head1 RETURN VALUES TYPE_get_new_ex_index() returns a new index on success or -1 on error. diff --git a/doc/man3/CRYPTO_get_ex_new_index.pod b/doc/man3/CRYPTO_get_ex_new_index.pod index b0321b0933..d8cecccdb1 100644 --- a/doc/man3/CRYPTO_get_ex_new_index.pod +++ b/doc/man3/CRYPTO_get_ex_new_index.pod @@ -44,13 +44,12 @@ Several OpenSSL structures can have application-specific data attached to them, known as "exdata." The specific structures are: - APP BIO DH - DRBG DSA EC_KEY ENGINE + RAND_DRBG RSA SSL SSL_CTX @@ -61,6 +60,8 @@ The specific structures are: X509_STORE X509_STORE_CTX +In addition, the B<APP> name is reserved for use by application code. + 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. diff --git a/doc/man3/RAND_DRBG_set_ex_data.pod b/doc/man3/RAND_DRBG_set_ex_data.pod deleted file mode 100644 index 3f2bffa282..0000000000 --- a/doc/man3/RAND_DRBG_set_ex_data.pod +++ /dev/null @@ -1,68 +0,0 @@ -=pod - -=head1 NAME - -RAND_DRBG_set_ex_data, -RAND_DRBG_get_ex_data, -RAND_DRBG_get_ex_new_index -- store and retrieve extra data from the DRBG instance - -=head1 SYNOPSIS - - #include <openssl/rand_drbg.h> - - int RAND_DRBG_set_ex_data(RAND_DRBG *drbg, int idx, void *data); - - void *RAND_DRBG_get_ex_data(const RAND_DRBG *drbg, int idx); - - int RAND_DRBG_get_ex_new_index(long argl, void *argp, - CRYPTO_EX_new *new_func, - CRYPTO_EX_dup *dup_func, - CRYPTO_EX_free *free_func); - - - -=head1 DESCRIPTION - -RAND_DRBG_set_ex_data() enables an application to store arbitrary application -specific data B<data> in a RAND_DRBG instance B<drbg>. The index B<idx> should -be a value previously returned from a call to RAND_DRBG_get_ex_new_index(). - -RAND_DRBG_get_ex_data() retrieves application specific data previously stored -in an RAND_DRBG instance B<drbg>. The B<idx> value should be the same as that -used when originally storing the data. - -For more detailed information see L<CRYPTO_get_ex_data(3)> and -L<CRYPTO_set_ex_data(3)> which implement these functions and -L<CRYPTO_get_ex_new_index(3)> for generating a unique index. - -=head1 RETURN VALUES - -RAND_DRBG_set_ex_data() returns 1 for success or 0 for failure. - -RAND_DRBG_get_ex_data() returns the previously stored value or NULL on -failure. NULL may also be a valid value. - - -=head1 NOTES - -RAND_DRBG_get_ex_new_index(...) is implemented as a macro and equivalent to -CRYPTO_get_ex_new_index(CRYPTO_EX_INDEX_DRBG,...). - -=head1 SEE ALSO - -L<CRYPTO_get_ex_data(3)>, -L<CRYPTO_set_ex_data(3)>, -L<CRYPTO_get_ex_new_index(3)>, -L<RAND_DRBG(7)> - -=head1 COPYRIGHT - -Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved. - -Licensed under the Apache License 2.0 (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 diff --git a/doc/man3/SSL_CTX_set_ex_data.pod b/doc/man3/SSL_CTX_set_ex_data.pod deleted file mode 100644 index 51997c29b1..0000000000 --- a/doc/man3/SSL_CTX_set_ex_data.pod +++ /dev/null @@ -1,52 +0,0 @@ -=pod - -=head1 NAME - -SSL_CTX_get_ex_data, SSL_CTX_set_ex_data, -SSL_get_ex_data, SSL_set_ex_data -- Store and retrieve extra data from the SSL_CTX, SSL or SSL_SESSION - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - void *SSL_CTX_get_ex_data(const SSL_CTX *s, int idx); - - int SSL_CTX_set_ex_data(SSL_CTX *s, int idx, void *arg); - - void *SSL_get_ex_data(const SSL *s, int idx); - - int SSL_set_ex_data(SSL *s, int idx, void *arg); - -=head1 DESCRIPTION - -SSL*_set_ex_data() functions can be used to store arbitrary user data into the -B<SSL_CTX>, or B<SSL> object. The user must supply a unique index -which they can subsequently use to retrieve the data using SSL*_get_ex_data(). - -For more detailed information see L<CRYPTO_get_ex_data(3)> and -L<CRYPTO_set_ex_data(3)> which implement these functions and -L<CRYPTO_get_ex_new_index(3)> for generating a unique index. - -=head1 RETURN VALUES - -The SSL*_set_ex_data() functions return 1 if the item is successfully stored -and 0 if it is not. -The SSL*_get_ex_data() functions return the ex_data pointer if successful, -otherwise NULL. - -=head1 SEE ALSO - -L<CRYPTO_get_ex_data(3)>, L<CRYPTO_set_ex_data(3)>, -L<CRYPTO_get_ex_new_index(3)> - -=head1 COPYRIGHT - -Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. - -Licensed under the Apache License 2.0 (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 diff --git a/doc/man3/SSL_SESSION_get_ex_data.pod b/doc/man3/SSL_SESSION_get_ex_data.pod deleted file mode 100644 index 1cda811b5e..0000000000 --- a/doc/man3/SSL_SESSION_get_ex_data.pod +++ /dev/null @@ -1,47 +0,0 @@ -=pod - -=head1 NAME - -SSL_SESSION_set_ex_data, -SSL_SESSION_get_ex_data -- get and set application specific data on a session - -=head1 SYNOPSIS - - #include <openssl/ssl.h> - - int SSL_SESSION_set_ex_data(SSL_SESSION *ss, int idx, void *data); - void *SSL_SESSION_get_ex_data(const SSL_SESSION *s, int idx); - -=head1 DESCRIPTION - -SSL_SESSION_set_ex_data() enables an application to store arbitrary application -specific data B<data> in an SSL_SESSION structure B<ss>. The index B<idx> should -be a value previously returned from a call to L<CRYPTO_get_ex_new_index(3)>. - -SSL_SESSION_get_ex_data() retrieves application specific data previously stored -in an SSL_SESSION structure B<s>. The B<idx> value should be the same as that -used when originally storing the data. - -=head1 RETURN VALUES - -SSL_SESSION_set_ex_data() returns 1 for success or 0 for failure. - -SSL_SESSION_get_ex_data() returns the previously stored value or NULL on -failure. NULL may also be a valid value. - -=head1 SEE ALSO - -L<ssl(7)>, -L<CRYPTO_get_ex_new_index(3)> - -=head1 COPYRIGHT - -Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. - -Licensed under the Apache License 2.0 (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 |