=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
However, if the I<responder> can handle multiple elements with the
same key, those elements must be handled in the order they are in.
+An B<OSSL_PARAM> array must have a terminating element, where I<key>
+is NULL. The usual full terminating template is:
+
+ { NULL, 0, NULL, 0, 0 }
+
+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
The identity of the parameter in the form of a string.
+In an B<OSSL_PARAM> array, an item with this field set to NULL is
+considered a terminating item.
+
=item I<data_type>
The I<data_type> is a value that describes the type and organization of
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 I<return_size>
When an array of B<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 I<data_size> is too small for the data, the I<responder>
-must still set this field to indicate the minimum data size required.
+I<responder> must set this field to indicate size of the parameter
+data, including padding as the case may be.
+In case the I<data_size> is an unsuitable size for the data, the
+I<responder> must still set this field to indicate the minimum data
+size required.
+(further notes on this in L</NOTES> below).
When the B<OSSL_PARAM> is used as a parameter descriptor,
I<return_size> should be ignored.
The difference between this and B<OSSL_PARAM_UTF8_STRING> is that I<data>
doesn't point directly at the data, but to a pointer that points to the data.
+If there is any uncertainty about which to use, B<OSSL_PARAM_UTF8_STRING> is
+almost certainly the correct choice.
+
This is used to indicate that constant data is or will be passed,
and there is therefore no need to copy the data that is passed, just
the pointer to it.
I<data> doesn't point directly at the data, but to a pointer that
points to the data.
+If there is any uncertainty about which to use, B<OSSL_PARAM_OCTET_STRING> is
+almost certainly the correct choice.
+
This is used to indicate that constant data is or will be passed, and
there is therefore no need to copy the data that is passed, just the
pointer to it.
=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 required size, and eventually return an
-error.
+B<OSSL_PARAM> item to the minimum required size, and eventually return
+an error.
+
+=item *
+
+For the integer type parameters (B<OSSL_PARAM_UNSIGNED_INTEGER> and
+B<OSSL_PARAM_INTEGER>), a I<responder> may choose to return an error
+if the I<data_size> isn't a suitable size (even if I<data_size> is
+bigger than needed). If the I<responder> finds the size suitable, it
+must fill all I<data_size> bytes and ensure correct padding for the
+native endianness, and set I<return_size> to the same value as
+I<data_size>.
=back
#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 },
- { NULL, 0, NULL, 0, NULL }
+ { "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 }
};
=head3 Example 2
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, NULL }
+ { NULL, 0, NULL, 0, 0 }
};
A I<responder> that receives this array (as I<params> in this example)
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 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
projects / openssl.git / blobdiff