From 8c4412ed8fe80a8b92549d7e2db1359012074d65 Mon Sep 17 00:00:00 2001 From: Richard Levitte Date: Mon, 11 Mar 2019 21:51:01 +0100 Subject: [PATCH] Rename 'buffer' to 'data' in OSSL_PARAM The OSSL_PARAM attribute names |buffer| and |buffer_size| may lead to confusion, as they may make some think that the memory pointed at is an intermediate memory are. This is not generally the case, so we rename |buffer| and |buffer_size| to |data| and |data_size| Reviewed-by: Matt Caswell (Merged from https://github.com/openssl/openssl/pull/8451) --- crypto/provider_core.c | 4 ++-- doc/man3/OSSL_PARAM.pod | 37 +++++++++++++++++------------------ include/openssl/core.h | 4 ++-- test/p_test.c | 8 ++++---- test/provider_internal_test.c | 4 ++-- test/provider_test.c | 4 ++-- 6 files changed, 30 insertions(+), 31 deletions(-) diff --git a/crypto/provider_core.c b/crypto/provider_core.c index b3d44f1ac4..9e3d5f3c1a 100644 --- a/crypto/provider_core.c +++ b/crypto/provider_core.c @@ -397,11 +397,11 @@ static int core_get_params(const OSSL_PROVIDER *prov, const OSSL_PARAM params[]) for (i = 0; params[i].key != NULL; i++) { if (strcmp(params[i].key, "openssl-version") == 0) { - *(void **)params[i].buffer = OPENSSL_VERSION_STR; + *(void **)params[i].data = OPENSSL_VERSION_STR; if (params[i].return_size) *params[i].return_size = sizeof(OPENSSL_VERSION_STR); } else if (strcmp(params[i].key, "provider-name") == 0) { - *(void **)params[i].buffer = prov->name; + *(void **)params[i].data = prov->name; if (params[i].return_size) *params[i].return_size = strlen(prov->name) + 1; } diff --git a/doc/man3/OSSL_PARAM.pod b/doc/man3/OSSL_PARAM.pod index 9d4748637c..a90069cd47 100644 --- a/doc/man3/OSSL_PARAM.pod +++ b/doc/man3/OSSL_PARAM.pod @@ -11,9 +11,9 @@ OSSL_PARAM - a structure to pass or request object parameters typedef struct ossl_param_st OSSL_PARAM; struct ossl_param_st { const char *key; /* the name of the parameter */ - unsigned char data_type; /* declare what kind of content is in buffer */ - void *buffer; /* value being passed in or out */ - size_t buffer_size; /* buffer size */ + unsigned char data_type; /* declare what kind of content is in data */ + void *data; /* value being passed in or out */ + size_t data_size; /* data size */ size_t *return_size; /* OPTIONAL: address to content size */ }; @@ -45,8 +45,8 @@ Request parameters of some object. The caller (the I) sets up the C array and calls some function (the I) that has intimate knowledge about the object, which can take the internal data of the object and -copy (possibly convert) that to the buffers prepared by the -I. +copy (possibly convert) that to the memory prepared by the +I and pointed at with the C C. =back @@ -69,13 +69,13 @@ The C is a value that describes the type and organization of the data. See L below for a description of the types. -=item C +=item C -=item C +=item C -C is a pointer to the memory where the parameter data is (when +C is a pointer to the memory where the parameter data is (when setting parameters) or shall (when requesting parameters) be stored, -and C is its size in bytes. +and C is its size in bytes. The organization of the data depends on the parameter type and flag. =item C @@ -83,9 +83,8 @@ The organization of the data depends on the parameter type and flag. When an array of C is used to request data, the I must set this field to indicate the actual size of the parameter data. -In case the C is too small for the data, the I -must still set this field to indicate the minimum buffer size -required. +In case the C is too small for the data, the I +must still set this field to indicate the minimum data size required. =back @@ -139,7 +138,7 @@ Additionally, this flag can be added to any type: =item C -With this flag, C doesn't point directly at the data, but at a +With this flag, C doesn't point directly at the data, but at a pointer that points at the data. This can be used to indicate that constant data is or will be passed, @@ -147,10 +146,10 @@ and there is therefore no need to copy the data that is passed, just the pointer to it. If an C with this flag set is used to set a parameter, -C must be set to the size of the data, not the size of +C must be set to the size of the data, not the size of the pointer to the data. -If this C is used in a parameter request, C +If this C is used in a parameter request, C is not relevant. However, the I will set C<*return_size> to the size of the data (again, not the size of the pointer to the data). @@ -197,7 +196,7 @@ enough set of data, that call should succeed. =item * A I must never change the fields of an C, it -may only change the contents of the buffers that C and +may only change the contents of the memory that C and C point at. =item * @@ -213,7 +212,7 @@ C), but this is in no way mandatory. =item * -If a I finds that some buffers are too small for the +If a I finds that some data sizes are too small for the requested data, it must set C<*return_size> for each such C item to the required size, and eventually return an error. @@ -273,10 +272,10 @@ could fill in the parameters like this: for (i = 0; params[i].key != NULL; i++) { if (strcmp(params[i].key, "foo") == 0) { - *(char **)params[i].buffer = "foo value"; + *(char **)params[i].data = "foo value"; *params[i].return_size = 10; /* size of "foo value" */ } else if (strcmp(params[i].key, "bar") == 0) { - memcpy(params[1].buffer, "bar value", 10); + memcpy(params[1].data, "bar value", 10); *params[1].return_size = 10; /* size of "bar value" */ } /* Ignore stuff we don't know */ diff --git a/include/openssl/core.h b/include/openssl/core.h index 15e88434cd..bbc9fb4d9c 100644 --- a/include/openssl/core.h +++ b/include/openssl/core.h @@ -75,8 +75,8 @@ struct ossl_algorithm_st { struct ossl_param_st { const char *key; /* the name of the parameter */ unsigned int data_type; /* declare what kind of content is in buffer */ - void *buffer; /* value being passed in or out */ - size_t buffer_size; /* buffer size */ + void *data; /* value being passed in or out */ + size_t data_size; /* data size */ size_t *return_size; /* OPTIONAL: address to content size */ }; diff --git a/test/p_test.c b/test/p_test.c index 6dc04103c4..6c05cb05dd 100644 --- a/test/p_test.c +++ b/test/p_test.c @@ -63,8 +63,8 @@ static int p_get_params(const OSSL_PROVIDER *prov, OSSL_PARAM params[]) size_t buf_l; if (c_get_params(prov, counter_request)) { - const char *versionp = *(void **)counter_request[0].buffer; - const char *namep = *(void **)counter_request[1].buffer; + const char *versionp = *(void **)counter_request[0].data; + const char *namep = *(void **)counter_request[1].data; sprintf(buf, "Hello OpenSSL %.20s, greetings from %s!", versionp, namep); } else { @@ -72,8 +72,8 @@ static int p_get_params(const OSSL_PROVIDER *prov, OSSL_PARAM params[]) } *p->return_size = buf_l = strlen(buf) + 1; - if (p->buffer_size >= buf_l) - strncpy(p->buffer, buf, buf_l); + if (p->data_size >= buf_l) + strncpy(p->data, buf, buf_l); else ok = 0; } diff --git a/test/provider_internal_test.c b/test/provider_internal_test.c index c423808f3e..8ce382effa 100644 --- a/test/provider_internal_test.c +++ b/test/provider_internal_test.c @@ -37,8 +37,8 @@ static int test_provider(OSSL_PROVIDER *prov) ret = TEST_true(ossl_provider_activate(prov)) && TEST_true(ossl_provider_get_params(prov, greeting_request)) - && TEST_ptr(greeting = greeting_request[0].buffer) - && TEST_size_t_gt(greeting_request[0].buffer_size, 0) + && TEST_ptr(greeting = greeting_request[0].data) + && TEST_size_t_gt(greeting_request[0].data_size, 0) && TEST_str_eq(greeting, expected_greeting); ossl_provider_free(prov); diff --git a/test/provider_test.c b/test/provider_test.c index 738cd7bc45..250eea39ec 100644 --- a/test/provider_test.c +++ b/test/provider_test.c @@ -33,8 +33,8 @@ static int test_provider(const char *name) return TEST_ptr(prov = OSSL_PROVIDER_load(NULL, name)) && TEST_true(OSSL_PROVIDER_get_params(prov, greeting_request)) - && TEST_ptr(greeting = greeting_request[0].buffer) - && TEST_size_t_gt(greeting_request[0].buffer_size, 0) + && TEST_ptr(greeting = greeting_request[0].data) + && TEST_size_t_gt(greeting_request[0].data_size, 0) && TEST_str_eq(greeting, expected_greeting) && TEST_true(OSSL_PROVIDER_unload(prov)); } -- 2.34.1