=item * Request parameters of some object
-The caller (the I<requestor>) sets up the B<OSSL_PARAM> array and
+The caller (the I<requester>) sets up the B<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 memory prepared by the
-I<requestor> and pointed at with the B<OSSL_PARAM> I<data>.
+I<requester> and pointed at with the B<OSSL_PARAM> I<data>.
=item * Request parameter descriptors
This can also be specified using L<OSSL_PARAM_END(3)>.
+=head2 Functional support
+
+Libcrypto offers a limited set of helper functions to handle
+B<OSSL_PARAM> items and arrays, please see L<OSSL_PARAM_get_int(3)>.
+Developers are free to extend or replace those as they see fit.
+
=head2 B<OSSL_PARAM> fields
=over 4
and I<data_size> is its size in bytes.
The organization of the data depends on the parameter type and flag.
+The I<data_size> needs special attention with the parameter type
+B<OSSL_PARAM_UTF8_STRING> in relation to C strings. When setting
+parameters, the size should be set to the length of the string, not
+counting the terminating NUL byte. When requesting parameters, the
+size should be set to the size of the buffer to be populated, which
+should accommodate enough space for a terminating NUL byte.
+
When I<requesting parameters>, it's acceptable for I<data> to be NULL.
-This can be used by the I<requestor> to figure out dynamically exactly
+This can be used by the I<requester> to figure out dynamically exactly
how much buffer space is needed to store the parameter data.
In this case, I<data_size> is ignored.
=item *
+If I<data> for a B<OSSL_PARAM_OCTET_STRING> or a
+B<OSSL_PARAM_UTF8_STRING> is NULL, the I<responder> should
+set I<return_size> to the size of the item to be returned
+and return success. Later the responder will be called again
+with I<data> pointing at the place for the value to be put.
+
+=item *
+
If a I<responder> finds that some data sizes are too small for the
requested data, it must set I<return_size> for each such
B<OSSL_PARAM> item to the minimum required size, and eventually return
#include <openssl/core.h>
const char *foo = "some string";
- size_t foo_l = strlen(foo) + 1;
+ size_t foo_l = strlen(foo);
const char bar[] = "some other string";
OSSL_PARAM set[] = {
- { "foo", OSSL_PARAM_UTF8_STRING_PTR, &foo, foo_l, 0 },
- { "bar", OSSL_PARAM_UTF8_STRING, &bar, sizeof(bar), 0 },
+ { "foo", OSSL_PARAM_UTF8_PTR, &foo, foo_l, 0 },
+ { "bar", OSSL_PARAM_UTF8_STRING, (void *)&bar, sizeof(bar) - 1, 0 },
{ NULL, 0, NULL, 0, 0 }
};
char bar[1024];
size_t bar_l;
OSSL_PARAM request[] = {
- { "foo", OSSL_PARAM_UTF8_STRING_PTR, &foo, 0 /*irrelevant*/, 0 },
+ { "foo", OSSL_PARAM_UTF8_PTR, &foo, 0 /*irrelevant*/, 0 },
{ "bar", OSSL_PARAM_UTF8_STRING, &bar, sizeof(bar), 0 },
{ NULL, 0, NULL, 0, 0 }
};
for (i = 0; params[i].key != NULL; i++) {
if (strcmp(params[i].key, "foo") == 0) {
*(char **)params[i].data = "foo value";
- params[i].return_size = 10; /* size of "foo value" */
+ params[i].return_size = 9; /* length of "foo value" string */
} else if (strcmp(params[i].key, "bar") == 0) {
memcpy(params[i].data, "bar value", 10);
- params[i].return_size = 10; /* size of "bar value" */
+ params[i].return_size = 9; /* length of "bar value" string */
}
/* Ignore stuff we don't know */
}
=head1 SEE ALSO
-L<openssl-core.h(7)>, L<OSSL_PARAM_get_int(3)>
+L<openssl-core.h(7)>, L<OSSL_PARAM_get_int(3)>, L<OSSL_PARAM_dup(3)>
=head1 HISTORY
=head1 COPYRIGHT
-Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2019-2023 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