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 <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/8451)

diff --git a/crypto/provider_core.c b/crypto/provider_core.c
index b3d44f1ac431d95a3d471e131b23c9fdd88c8cbf..9e3d5f3c1abd3d58235b2b391a194faae0b49576 100644 (file)
--- 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 9d4748637cbcdb4c097ebc9bfac7408f6b8a1f50..a90069cd479a0cddaa1a2c39b57cc913c0ab82d9 100644 (file)
--- 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<requestor>) sets up the C<OSSL_PARAM> array and
 calls some function (the I<responder>) 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<requestor>.
+copy (possibly convert) that to the memory prepared by the
+I<requestor> and pointed at with the C<OSSL_PARAM> C<data>.
 
 =back
 
@@ -69,13 +69,13 @@ The C<data_type> is a value that describes the type and organization of
 the data.
 See L</Supported types> below for a description of the types.
 
-=item C<buffer>
+=item C<data>
 
-=item C<buffer_size>
+=item C<data_size>
 
-C<buffer> is a pointer to the memory where the parameter data is (when
+C<data> is a pointer to the memory where the parameter data is (when
 setting parameters) or shall (when requesting parameters) be stored,
-and C<buffer_size> is its size in bytes.
+and C<data_size> is its size in bytes.
 The organization of the data depends on the parameter type and flag.
 
 =item C<return_size>
@@ -83,9 +83,8 @@ The organization of the data depends on the parameter type and flag.
 When an array of C<OSSL_PARAM> is used to request data, the
 I<responder> must set this field to indicate the actual size of the
 parameter data.
-In case the C<buffer_size> is too small for the data, the I<responder>
-must still set this field to indicate the minimum buffer size
-required.
+In case the C<data_size> is too small for the data, the I<responder>
+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<OSSL_PARAM_POINTER_FLAG>
 
-With this flag, C<buffer> doesn't point directly at the data, but at a
+With this flag, C<data> 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<OSSL_PARAM> with this flag set is used to set a parameter,
-C<buffer_size> must be set to the size of the data, not the size of
+C<data_size> must be set to the size of the data, not the size of
 the pointer to the data.
 
-If this C<OSSL_PARAM> is used in a parameter request, C<buffer_size>
+If this C<OSSL_PARAM> is used in a parameter request, C<data_size>
 is not relevant.
 However, the I<responder> 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<responder> must never change the fields of an C<OSSL_PARAM>, it
-may only change the contents of the buffers that C<buffer> and
+may only change the contents of the memory that C<data> and
 C<return_size> point at.
 
 =item *
@@ -213,7 +212,7 @@ C<OSSL_PARAM_OCTET_STRING>), but this is in no way mandatory.
 
 =item *
 
-If a I<responder> finds that some buffers are too small for the
+If a I<responder> finds that some data sizes are too small for the
 requested data, it must set C<*return_size> for each such
 C<OSSL_PARAM> 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 15e88434cd06d1119f26303974c365c7304b1457..bbc9fb4d9cfa14ef3ce4179b801cf691583d56d4 100644 (file)
--- 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 6dc04103c44ec2b12ac95995e7f8ce8981e63f2d..6c05cb05ddc6e5ee49e7f7a00763536645464cdc 100644 (file)
--- 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 c423808f3e4c8e8fdc699d0486cfe2c7bf01e2f4..8ce382effa3c957a87f4495274dcb3706c996c05 100644 (file)
--- 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 738cd7bc4588085e49938326e71bda718d5f116a..250eea39ecdd76bc033227b4c435aa4152a59417 100644 (file)
--- 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));
 }