mirrors/openssl
0
0
Fork 0
mirror of https://github.com/openssl/openssl.git synced 2024-11-23 18:13:39 +08:00
Code Issues Packages Projects Releases Wiki Activity

Document "get/set-app-data" macros.

Browse Source 
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)
This commit is contained in:
Rich Salz 2019-10-18 12:24:39 -04:00
parent c89799605b
commit d318389eff
10 changed files with 38 additions and 193 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
crypto/rand/drbg_lib.c
View File

@ -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));

36
doc/man3/BIO_get_ex_new_index.pod
View File

@ -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.

5
doc/man3/CRYPTO_get_ex_new_index.pod
View File

@ -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.

68
doc/man3/RAND_DRBG_set_ex_data.pod
View File

@ -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

52
doc/man3/SSL_CTX_set_ex_data.pod
View File

@ -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

47
doc/man3/SSL_SESSION_get_ex_data.pod
View File

@ -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

3
include/openssl/crypto.h
View File

@ -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

2
include/openssl/rand_drbg.h
View File

@ -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);

2
test/drbgtest.c
View File

@ -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 */

14
util/missingmacro.txt
View File

@ -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