From d318389eff0fb80d4a88c7af1cc314f185ba94e1 Mon Sep 17 00:00:00 2001 From: Rich Salz Date: Fri, 18 Oct 2019 12:24:39 -0400 Subject: [PATCH] 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 Reviewed-by: Richard Levitte (Merged from https://github.com/openssl/openssl/pull/10216) --- crypto/rand/drbg_lib.c | 2 +- doc/man3/BIO_get_ex_new_index.pod | 36 ++++++++++++--- doc/man3/CRYPTO_get_ex_new_index.pod | 5 +- doc/man3/RAND_DRBG_set_ex_data.pod | 68 ---------------------------- doc/man3/SSL_CTX_set_ex_data.pod | 52 --------------------- doc/man3/SSL_SESSION_get_ex_data.pod | 47 ------------------- include/openssl/crypto.h | 3 +- include/openssl/rand_drbg.h | 2 +- test/drbgtest.c | 2 +- util/missingmacro.txt | 14 ------ 10 files changed, 38 insertions(+), 193 deletions(-) delete mode 100644 doc/man3/RAND_DRBG_set_ex_data.pod delete mode 100644 doc/man3/SSL_CTX_set_ex_data.pod delete mode 100644 doc/man3/SSL_SESSION_get_ex_data.pod diff --git a/crypto/rand/drbg_lib.c b/crypto/rand/drbg_lib.c index 90e37786e6..52e6743230 100644 --- a/crypto/rand/drbg_lib.c +++ b/crypto/rand/drbg_lib.c @@ -503,7 +503,7 @@ void RAND_DRBG_free(RAND_DRBG *drbg) drbg->meth->uninstantiate(drbg); rand_pool_free(drbg->adin_pool); CRYPTO_THREAD_lock_free(drbg->lock); - CRYPTO_free_ex_data(CRYPTO_EX_INDEX_DRBG, drbg, &drbg->ex_data); + CRYPTO_free_ex_data(CRYPTO_EX_INDEX_RAND_DRBG, drbg, &drbg->ex_data); if (drbg->secure) OPENSSL_secure_clear_free(drbg, sizeof(*drbg)); 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 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 set to zero. +TYPE_get_app_data() is a macro that invokes TYPE_get_ex_data() with +B set to zero. +Note that these functions are not defined for the B 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 name is reserved for use by application code. + 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. 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 - - 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 in a RAND_DRBG instance B. The index B 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. The B value should be the same as that -used when originally storing the data. - -For more detailed information see L and -L which implement these functions and -L 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, -L, -L, -L - -=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. - -=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 - - 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, or B 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 and -L which implement these functions and -L 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, L, -L - -=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. - -=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 - - 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 in an SSL_SESSION structure B. The index B should -be a value previously returned from a call to L. - -SSL_SESSION_get_ex_data() retrieves application specific data previously stored -in an SSL_SESSION structure B. The B 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, -L - -=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. - -=cut diff --git a/include/openssl/crypto.h b/include/openssl/crypto.h index 7a74f3d4eb..28c8939e96 100644 --- a/include/openssl/crypto.h +++ b/include/openssl/crypto.h @@ -113,7 +113,8 @@ DEFINE_STACK_OF(void) # define CRYPTO_EX_INDEX_BIO 12 # define CRYPTO_EX_INDEX_APP 13 # define CRYPTO_EX_INDEX_UI_METHOD 14 -# define CRYPTO_EX_INDEX_DRBG 15 +# define CRYPTO_EX_INDEX_RAND_DRBG 15 +# define CRYPTO_EX_INDEX_DRBG CRYPTO_EX_INDEX_RAND_DRBG # define CRYPTO_EX_INDEX_OPENSSL_CTX 16 # define CRYPTO_EX_INDEX__COUNT 17 diff --git a/include/openssl/rand_drbg.h b/include/openssl/rand_drbg.h index 0aef0da5a3..f52e5ee041 100644 --- a/include/openssl/rand_drbg.h +++ b/include/openssl/rand_drbg.h @@ -123,7 +123,7 @@ RAND_DRBG *RAND_DRBG_get0_private(void); * EXDATA */ # define RAND_DRBG_get_ex_new_index(l, p, newf, dupf, freef) \ - CRYPTO_get_ex_new_index(CRYPTO_EX_INDEX_DRBG, l, p, newf, dupf, freef) + CRYPTO_get_ex_new_index(CRYPTO_EX_INDEX_RAND_DRBG, l, p, newf, dupf, freef) int RAND_DRBG_set_ex_data(RAND_DRBG *drbg, int idx, void *arg); void *RAND_DRBG_get_ex_data(const RAND_DRBG *drbg, int idx); diff --git a/test/drbgtest.c b/test/drbgtest.c index 93adb48d08..b8dcbf7b7b 100644 --- a/test/drbgtest.c +++ b/test/drbgtest.c @@ -589,7 +589,7 @@ static void unhook_drbg(RAND_DRBG *drbg) HOOK_CTX *ctx = get_hook_ctx(drbg); drbg->get_entropy = ctx->get_entropy; - CRYPTO_free_ex_data(CRYPTO_EX_INDEX_DRBG, drbg, &drbg->ex_data); + CRYPTO_free_ex_data(CRYPTO_EX_INDEX_RAND_DRBG, drbg, &drbg->ex_data); } /* Resets the given hook context */ diff --git a/util/missingmacro.txt b/util/missingmacro.txt index 4b7cdd77df..86142892a6 100644 --- a/util/missingmacro.txt +++ b/util/missingmacro.txt @@ -9,8 +9,6 @@ BIO_get_retry_flags BIO_CB_return BIO_cb_pre BIO_cb_post -BIO_set_app_data -BIO_get_app_data BIO_set_conn_mode BIO_dup_state BIO_buffer_get_num_lines @@ -138,8 +136,6 @@ PKCS7_type_is_digest PKCS7_set_detached PKCS7_get_detached PKCS7_is_detached -RSA_set_app_data -RSA_get_app_data STACK_OF SKM_DEFINE_STACK_OF U64 @@ -150,12 +146,6 @@ SSL_CTX_set_cert_flags SSL_set_cert_flags SSL_CTX_clear_cert_flags SSL_clear_cert_flags -SSL_set_app_data -SSL_get_app_data -SSL_SESSION_set_app_data -SSL_SESSION_get_app_data -SSL_CTX_get_app_data -SSL_CTX_set_app_data SSLeay_add_ssl_algorithms DTLSv1_get_timeout DTLSv1_handle_timeout @@ -200,13 +190,9 @@ OSSL_TRACE5 OSSL_TRACE6 OSSL_TRACE7 OSSL_TRACE8 -UI_set_app_data -UI_get_app_data X509_extract_key X509_REQ_extract_key X509_name_cmp -X509_STORE_CTX_set_app_data -X509_STORE_CTX_get_app_data X509_LOOKUP_load_file X509_LOOKUP_add_dir X509V3_conf_err -- 2.25.1