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 */
+ size_t return_size; /* returned size */
};
=head1 DESCRIPTION
parameters for an object, or wants to find out some parameters of an
object.
-Arrays of this type can be used for two purposes:
+Arrays of this type can be used for the following purposes:
=over 4
-=item *
+=item * Setting parameters for some object
-Setting parameters for some object.
The caller sets up the C<OSSL_PARAM> array and calls some function
(the I<setter>) that has intimate knowledge about the object that can
take the data from the C<OSSL_PARAM> array and assign them in a
suitable form for the internal structure of the object.
-=item *
+=item * Request parameters of some object
-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 memory prepared by the
I<requestor> and pointed at with the C<OSSL_PARAM> C<data>.
+=item * Request parameter descriptors
+
+The caller gets an array of constant C<OSSL_PARAM>, which describe
+available parameters and some of their properties; name, data type and
+expected data size.
+For a detailed description of each field for this use, see the field
+descriptions below.
+
+The caller may then use the information from this descriptor array to
+build up its own C<OSSL_PARAM> array to pass down to a I<setter> or
+I<responder>.
+
=back
=head2 C<OSSL_PARAM> fields
and C<data_size> is its size in bytes.
The organization of the data depends on the parameter type and flag.
+When the C<OSSL_PARAM> is used as a parameter descriptor, C<data>
+should be ignored.
+If C<data_size> is zero, it means that an arbitrary data size is
+accepted, otherwise it specifies the maximum size allowed.
+
=item C<return_size>
When an array of C<OSSL_PARAM> is used to request data, the
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.
+When the C<OSSL_PARAM> is used as a parameter descriptor,
+C<return_size> should be ignored.
+
=back
B<NOTE:>
pointer to the data.
If this 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.
+C<return_size> to the size of the data.
Note that the use of this type is B<fragile> and can only be safely
used for data that remains constant and in a constant location for a
pointer to the data.
If this 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.
+C<return_size> to the size of the data.
Note that the use of this type is B<fragile> and can only be safely
used for data that remains constant and in a constant location for a
=item *
-A I<responder> must never change the fields of an C<OSSL_PARAM>, it
-may only change the contents of the memory that C<data> and
-C<return_size> point at.
+Apart from the C<return_size>, a I<responder> must never change the fields
+of an C<OSSL_PARAM>.
+To return a value, it should change the contents of the memory that
+C<data> points at.
=item *
=item *
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
+requested data, it must set C<return_size> for each such
C<OSSL_PARAM> item to the required size, and eventually return an
error.
const char *foo = "some string";
size_t foo_l = strlen(foo) + 1;
const char bar[] = "some other string";
- const OSSL_PARAM set[] = {
- { "foo", OSSL_PARAM_UTF8_STRING_PTR, &foo, foo_l, NULL },
- { "bar", OSSL_PARAM_UTF8_STRING, &bar, sizeof(bar), NULL },
+ 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 }
};
size_t foo_l;
char bar[1024];
size_t bar_l;
- const OSSL_PARAM request[] = {
- { "foo", OSSL_PARAM_UTF8_STRING_PTR, &foo, 0 /*irrelevant*/, &foo_l },
- { "bar", OSSL_PARAM_UTF8_STRING, &bar, sizeof(bar), &bar_l },
+ OSSL_PARAM request[] = {
+ { "foo", OSSL_PARAM_UTF8_STRING_PTR, &foo, 0 /*irrelevant*/, 0 },
+ { "bar", OSSL_PARAM_UTF8_STRING, &bar, sizeof(bar), 0 },
{ NULL, 0, NULL, 0, NULL }
};
A I<responder> that receives this array (as C<params> in this example)
could fill in the parameters like this:
- /* const OSSL_PARAM *params */
+ /* OSSL_PARAM *params */
int i;
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 = 10; /* size of "foo value" */
} 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 = 10; /* size of "bar value" */
}
/* Ignore stuff we don't know */
}
=head1 SEE ALSO
-L<openssl-core.h(7)>, L<OSSL_PARAM_get_int32_t(3)>
+L<openssl-core.h(7)>, L<OSSL_PARAM_get_int(3)>
=head1 HISTORY
projects / openssl.git / blobdiff