From: Pauli Date: Mon, 17 Jun 2019 01:34:09 +0000 (+1000) Subject: Better document specific OSSL_PARAM symbols. X-Git-Tag: openssl-3.0.0-alpha1~1939 X-Git-Url: https://git.librecmc.org/?a=commitdiff_plain;h=1313e37ab97c0b24eedf67b343b93a7c964b9767;p=oweals%2Fopenssl.git Better document specific OSSL_PARAM symbols. Reviewed-by: Richard Levitte (Merged from https://github.com/openssl/openssl/pull/9114) --- diff --git a/doc/man3/OSSL_PARAM_TYPE.pod b/doc/man3/OSSL_PARAM_TYPE.pod deleted file mode 100644 index 1b750b2c54..0000000000 --- a/doc/man3/OSSL_PARAM_TYPE.pod +++ /dev/null @@ -1,333 +0,0 @@ -=pod - -=head1 NAME - -OSSL_PARAM_TYPE, OSSL_PARAM_utf8_string, OSSL_PARAM_octet_string, -OSSL_PARAM_utf8_ptr, OSSL_PARAM_octet_ptr, OSSL_PARAM_SIZED_TYPE, -OSSL_PARAM_SIZED_BN, OSSL_PARAM_SIZED_utf8_string, -OSSL_PARAM_SIZED_octet_string, OSSL_PARAM_SIZED_utf8_ptr, -OSSL_PARAM_SIZED_octet_ptr, OSSL_PARAM_END, OSSL_PARAM_construct_TYPE, -OSSL_PARAM_END, -OSSL_PARAM_construct_BN, OSSL_PARAM_construct_utf8_string, -OSSL_PARAM_construct_utf8_ptr, OSSL_PARAM_construct_octet_string, -OSSL_PARAM_construct_octet_ptr, OSSL_PARAM_construct_end, -OSSL_PARAM_locate, OSSL_PARAM_get_TYPE, -OSSL_PARAM_set_TYPE, OSSL_PARAM_get_BN, OSSL_PARAM_set_BN, -OSSL_PARAM_get_utf8_string, OSSL_PARAM_set_utf8_string, -OSSL_PARAM_get_octet_string, OSSL_PARAM_set_octet_string, -OSSL_PARAM_get_utf8_ptr, OSSL_PARAM_set_utf8_ptr, OSSL_PARAM_get_octet_ptr, -OSSL_PARAM_set_octet_ptr -- OSSL_PARAM helpers - -=head1 SYNOPSIS - - #include - - #define OSSL_PARAM_TYPE(key, address) - #define OSSL_PARAM_utf8_string(key, address, size) - #define OSSL_PARAM_octet_string(key, address, size) - #define OSSL_PARAM_utf8_ptr(key, address, size) - #define OSSL_PARAM_octet_ptr(key, address, size) - #define OSSL_PARAM_SIZED_TYPE(key, address, return_size) - #define OSSL_PARAM_SIZED_BN(key, address, size, return_size) - #define OSSL_PARAM_SIZED_utf8_string(key, address, size, return_size) - #define OSSL_PARAM_SIZED_octet_string(key, address, size, return_size) - #define OSSL_PARAM_SIZED_utf8_ptr(key, address, size, return_size) - #define OSSL_PARAM_SIZED_octet_ptr(key, address, size, return_size) - #define OSSL_PARAM_END - - OSSL_PARAM OSSL_PARAM_construct_TYPE(const char *key, TYPE *buf, size_t *ret); - OSSL_PARAM OSSL_PARAM_construct_BN(const char *key, unsigned char *buf, - size_t bsize, size_t *rsize); - OSSL_PARAM OSSL_PARAM_construct_utf8_string(const char *key, char *buf, - size_t bsize, size_t *rsize); - OSSL_PARAM OSSL_PARAM_construct_octet_string(const char *key, void *buf, - size_t bsize, size_t *rsize); - OSSL_PARAM OSSL_PARAM_construct_utf8_ptr(const char *key, char **buf, - size_t bsize, size_t *rsize); - OSSL_PARAM OSSL_PARAM_construct_octet_ptr(const char *key, void **buf, - size_t bsize, size_t *rsize); - OSSL_PARAM OSSL_PARAM_construct_end(void); - - OSSL_PARAM *OSSL_PARAM_locate(OSSL_PARAM *array, const char *key); - - int OSSL_PARAM_get_TYPE(const OSSL_PARAM *p, const char *key, TYPE *val); - int OSSL_PARAM_set_TYPE(const OSSL_PARAM *p, const char *key, TYPE val); - - int OSSL_PARAM_get_BN(const OSSL_PARAM *p, const char *key, BIGNUM **val); - int OSSL_PARAM_set_BN(const OSSL_PARAM *p, const char *key, const BIGNUM *val); - - int OSSL_PARAM_get_utf8_string(const OSSL_PARAM *p, char **val, - size_t max_len); - int OSSL_PARAM_set_utf8_string(const OSSL_PARAM *p, const char *val); - - int OSSL_PARAM_get_octet_string(const OSSL_PARAM *p, void **val, - size_t max_len, size_t *used_len); - int OSSL_PARAM_set_octet_string(const OSSL_PARAM *p, const void *val, - size_t len); - - int OSSL_PARAM_get_utf8_ptr(const OSSL_PARAM *p, char **val); - int OSSL_PARAM_set_utf8_ptr(const OSSL_PARAM *p, char *val); - - int OSSL_PARAM_get_octet_ptr(const OSSL_PARAM *p, void **val, - size_t *used_len); - int OSSL_PARAM_set_octet_ptr(const OSSL_PARAM *p, void *val, size_t used_len); - -=head1 DESCRIPTION - -A collection of utility functions that simplify and add type safety to the -OSSL_PARAM arrays. The following B names are supported: - -=over 1 - -=item * - -double - -=item * - -int - -=item * - -int32 (int32_t) - -=item * - -int64 (int64_t) - -=item * - -long int (long) - -=item * - -size_t - -=item * - -uint32 (uint32_t) - -=item * - -uint64 (uint64_t) - -=item * - -unsigned int (uint) - -=item * - -unsigned long int (ulong) - -=back - -OSSL_PARAM_TYPE() are a series of macros designed to assist initialising an -array of OSSL_PARAM structures. -Each of these macros defines a parameter of the specified B with the -provided B and parameter variable B
. - -OSSL_PARAM_utf8_string(), OSSL_PARAM_octet_string(), OSSL_PARAM_utf8_ptr(), -OSSL_PARAM_octet_ptr() are macros that provide support for defining UTF8 -strings and OCTET strings. -A parameter with name B is defined. -The storage for this parameter is at B
and is of B bytes. - -OSSL_PARAM_SIZED_TYPE() are a second series of macros designed to assist with -the initialisation of OSSL_PARAM structures. -They are similar to the OSSL_PARAM_TYPE() macros but also include a -B argument which contains the address of a size_t variable which -will be populated with the actual size of the parameter upon return from a -OSSL_PARAM_set_TYPE() call. - -OSSL_PARAM_SIZED_BN(), OSSL_PARAM_SIZED_utf8_string(), -OSSL_PARAM_SIZED_octet_string(), OSSL_PARAM_SIZED_utf8_ptr(), -OSSL_PARAM_SIZED_octet_ptr() are macros that provide support for defining large -integers, UTF8 string and OCTET strings in an OSSL_PARAM array. -A parameter with name B is defined. -The storage for this parameter is at B
and is of B bytes. -The size used by the parameter value, in bytes, is written to B. - -OSSL_PARAM_END provides an end of parameter list marker. -This should terminate all OSSL_PARAM arrays. - -OSSL_PARAM_construct_TYPE() are a series of functions that create OSSL_PARAM -records dynamically. -A parameter with name B is created. -The parameter will use storage pointed to by B and return size of B. - -OSSL_PARAM_construct_BN() is a function that constructs a large integer -OSSL_PARAM structure. -A parameter with name B, storage B, size B and return -size B is created. - -OSSL_PARAM_construct_utf8_string() is a function that constructs a UTF8 -string OSSL_PARAM structure. -A parameter with name B, storage B, size B and return -size B is created. - -OSSL_PARAM_construct_octet_string() is a function that constructs an OCTET -string OSSL_PARAM structure. -A parameter with name B, storage B, size B and return -size B is created. - -OSSL_PARAM_construct_utf8_ptr() is a function that constructes a UTF string -pointer OSSL_PARAM structure. -A parameter with name B, storage pointer B<*buf>, size B and -return size B is created. - -OSSL_PARAM_construct_octet_ptr() is a function that constructes an OCTET string -pointer OSSL_PARAM structure. -A parameter with name B, storage pointer B<*buf>, size B and -return size B is created. - -OSSL_PARAM_construct_end() is a function that constructs the terminating -OSSL_PARAM structure. - -OSSL_PARAM_locate() is a function that searches an B of parameters for -the one matching the B name. - -OSSL_PARAM_get_TYPE() retrieves a value of type B from the parameter B

. -The value is copied to the address B. -Type coercion takes place as discussed in the NOTES section. - -OSSL_PARAM_set_TYPE() stores a value B of type B into the paramter -B

. -Type coercion takes place as discussed in the NOTES section. - -OSSL_PARAM_get_BN() retrieves a BIGNUM from the parameter pointed to by B

. -The BIGNUM referenced by B is updated and is allocated if B<*val> is -B. - -OSSL_PARAM_set_BN() stores the BIGNUM B into the paramater B

. - -OSSL_PARAM_get_utf8_string() retrieves a UTF8 string from the parameter -pointed to by B

. -The string is either stored into B<*val> with a length limit of B or, -in the case when B<*val> is B, memory is allocated for the string and -B is ignored. -If memory is allocated by this function, it must be freed by the caller. - -OSSL_PARAM_set_utf8_string() sets a UTF8 string from the parameter pointed to -by B

to the value referenced by B. - -OSSL_PARAM_get_octet_string() retrieves an OCTET string from the parameter -pointed to by B

. -The OCTETs are either stored into B<*val> with a length limit of B or, -in the case when B<*val> is B, memory is allocated and -B is ignored. -If memory is allocated by this function, it must be freed by the caller. - -OSSL_PARAM_set_octet_string() sets an OCTET string from the parameter -pointed to by B

to the value referenced by B. - -OSSL_PARAM_get_utf8_ptr() retrieves the UTF8 string pointer from the parameter -referenced by B

and stores it in B<*val>. - -OSSL_PARAM_set_utf8_ptr() sets the UTF8 string pointer in the parameter -referenced by B

to the values B. - -OSSL_PARAM_get_octet_ptr() retrieves the OCTET string pointer from the parameter -referenced by B

and stores it in B<*val>. -The length of the OCTET string is stored in B<*used_len>. - -OSSL_PARAM_set_octet_ptr() sets the OCTET string pointer in the parameter -referenced by B

to the values B. -The length of the OCTET string is provided by B. - -=head1 RETURN VALUES - -OSSL_PARAM_construct_TYPE(), OSSL_PARAM_construct_BN(), -OSSL_PARAM_construct_utf8_string(), OSSL_PARAM_construct_octet_string(), -OSSL_PARAM_construct_utf8_ptr() and OSSL_PARAM_construct_octet_ptr() -return a populated OSSL_PARAM structure. - -OSSL_PARAM_locate() returns a pointer to the matching OSSL_PARAM object. -It returns B on error or when no object matching B exists in -the B. - -All other functions return B<1> on success and B<0> on failure. - -=head1 NOTES - -Native types will be converted as required only if the value is exactly -representable by the target type or parameter. -Apart from that, the functions must be used appropriately for the -expected type of the parameter. - -For OSSL_PARAM_get_utf8_ptr() and OSSL_PARAM_get_octet_ptr(), B -is not relevant if the purpose is to send the B array to a -I, i.e. to get parameter data back. -In that case, B can safely be given zero. -See L for further information on the -possible purposes. - -=head1 EXAMPLES - -Reusing the examples from L to just show how -C arrays can be handled using the macros and functions -defined herein. - -=head2 Example 1 - -This example is for setting parameters on some object: - - #include - - const char *foo = "some string"; - size_t foo_l = strlen(foo) + 1; - const char bar[] = "some other string"; - const OSSL_PARAM set[] = { - OSSL_PARAM_utf8_ptr("foo", foo, foo_l), - OSSL_PARAM_utf8_string("bar", bar, sizeof(bar)), - OSSL_PARAM_END - }; - -=head2 Example 2 - -This example is for requesting parameters on some object, and also -demonstrates that the requestor isn't obligated to request all -available parameters: - - const char *foo = NULL; - size_t foo_l; - char bar[1024]; - size_t bar_l; - const OSSL_PARAM request[] = { - OSSL_PARAM_UTF8_PTR("foo", foo, 0, foo_l), - OSSL_PARAM_UTF8_STRING("bar", bar, sizeof(bar), bar_l), - OSSL_PARAM_END - }; - -A I that receives this array (as C in this example) -could fill in the parameters like this: - - /* const OSSL_PARAM *params */ - - const OSSL_PARAM *p; - - if ((p = OSSL_PARAM_locate(params, "foo")) == NULL) - OSSL_PARAM_set_utf8_ptr(p, "foo value"); - if ((p = OSSL_PARAM_locate(params, "bar")) == NULL) - OSSL_PARAM_set_utf8_ptr(p, "bar value"); - if ((p = OSSL_PARAM_locate(params, "cookie")) == NULL) - OSSL_PARAM_set_utf8_ptr(p, "cookie value"); - -=head1 SEE ALSO - -L, L - -=head1 HISTORY - -These APIs were introduced in OpenSSL 3.0.0. - -=head1 COPYRIGHT - -Copyright 2019 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 -in the file LICENSE in the source distribution or at -L. - -=cut diff --git a/doc/man3/OSSL_PARAM_int.pod b/doc/man3/OSSL_PARAM_int.pod new file mode 100644 index 0000000000..f8d8c501e0 --- /dev/null +++ b/doc/man3/OSSL_PARAM_int.pod @@ -0,0 +1,351 @@ +=pod + +=head1 NAME + +OSSL_PARAM_double, OSSL_PARAM_int, OSSL_PARAM_int32, OSSL_PARAM_int64, +OSSL_PARAM_long, OSSL_PARAM_size_t, OSSL_PARAM_uint, OSSL_PARAM_uint32, +OSSL_PARAM_uint64, OSSL_PARAM_ulong, OSSL_PARAM_utf8_string, +OSSL_PARAM_octet_string, OSSL_PARAM_utf8_ptr, OSSL_PARAM_octet_ptr, +OSSL_PARAM_SIZED_double, OSSL_PARAM_SIZED_int, OSSL_PARAM_SIZED_int32, +OSSL_PARAM_SIZED_int64, OSSL_PARAM_SIZED_long, OSSL_PARAM_SIZED_size_t, +OSSL_PARAM_SIZED_uint, OSSL_PARAM_SIZED_uint32, OSSL_PARAM_SIZED_uint64, +OSSL_PARAM_SIZED_ulong, OSSL_PARAM_SIZED_BN, OSSL_PARAM_SIZED_utf8_string, +OSSL_PARAM_SIZED_octet_string, OSSL_PARAM_SIZED_utf8_ptr, +OSSL_PARAM_SIZED_octet_ptr, OSSL_PARAM_END, OSSL_PARAM_construct_double, +OSSL_PARAM_construct_int, OSSL_PARAM_construct_int32, +OSSL_PARAM_construct_int64, OSSL_PARAM_construct_long, +OSSL_PARAM_construct_size_t, OSSL_PARAM_construct_uint, +OSSL_PARAM_construct_uint32, OSSL_PARAM_construct_uint64, +OSSL_PARAM_construct_ulong, OSSL_PARAM_END, OSSL_PARAM_construct_BN, +OSSL_PARAM_construct_utf8_string, OSSL_PARAM_construct_utf8_ptr, +OSSL_PARAM_construct_octet_string, OSSL_PARAM_construct_octet_ptr, +OSSL_PARAM_construct_end, OSSL_PARAM_locate, OSSL_PARAM_get_double, +OSSL_PARAM_get_int, OSSL_PARAM_get_int32, OSSL_PARAM_get_int64, +OSSL_PARAM_get_long, OSSL_PARAM_get_size_t, OSSL_PARAM_get_uint, +OSSL_PARAM_get_uint32, OSSL_PARAM_get_uint64, OSSL_PARAM_get_ulong, +OSSL_PARAM_set_double, OSSL_PARAM_set_int, OSSL_PARAM_set_int32, +OSSL_PARAM_set_int64, OSSL_PARAM_set_long, OSSL_PARAM_set_size_t, +OSSL_PARAM_set_uint, OSSL_PARAM_set_uint32, OSSL_PARAM_set_uint64, +OSSL_PARAM_set_ulong, OSSL_PARAM_get_BN, OSSL_PARAM_set_BN, +OSSL_PARAM_get_utf8_string, OSSL_PARAM_set_utf8_string, +OSSL_PARAM_get_octet_string, OSSL_PARAM_set_octet_string, +OSSL_PARAM_get_utf8_ptr, OSSL_PARAM_set_utf8_ptr, OSSL_PARAM_get_octet_ptr, +OSSL_PARAM_set_octet_ptr +- OSSL_PARAM helpers + +=head1 SYNOPSIS + +=for comment generic + + #include + + #define OSSL_PARAM_TYPE(key, address) + #define OSSL_PARAM_utf8_string(key, address, size) + #define OSSL_PARAM_octet_string(key, address, size) + #define OSSL_PARAM_utf8_ptr(key, address, size) + #define OSSL_PARAM_octet_ptr(key, address, size) + + #define OSSL_PARAM_SIZED_TYPE(key, address, return_size) + #define OSSL_PARAM_SIZED_BN(key, address, size, return_size) + #define OSSL_PARAM_SIZED_utf8_string(key, address, size, return_size) + #define OSSL_PARAM_SIZED_octet_string(key, address, size, return_size) + #define OSSL_PARAM_SIZED_utf8_ptr(key, address, size, return_size) + #define OSSL_PARAM_SIZED_octet_ptr(key, address, size, return_size) + + #define OSSL_PARAM_END + + OSSL_PARAM OSSL_PARAM_construct_TYPE(const char *key, TYPE *buf, size_t *ret); + OSSL_PARAM OSSL_PARAM_construct_BN(const char *key, unsigned char *buf, + size_t bsize, size_t *rsize); + OSSL_PARAM OSSL_PARAM_construct_utf8_string(const char *key, char *buf, + size_t bsize, size_t *rsize); + OSSL_PARAM OSSL_PARAM_construct_octet_string(const char *key, void *buf, + size_t bsize, size_t *rsize); + OSSL_PARAM OSSL_PARAM_construct_utf8_ptr(const char *key, char **buf, + size_t bsize, size_t *rsize); + OSSL_PARAM OSSL_PARAM_construct_octet_ptr(const char *key, void **buf, + size_t bsize, size_t *rsize); + OSSL_PARAM OSSL_PARAM_construct_end(void); + + OSSL_PARAM *OSSL_PARAM_locate(OSSL_PARAM *array, const char *key); + + int OSSL_PARAM_get_TYPE(const OSSL_PARAM *p, const char *key, TYPE *val); + int OSSL_PARAM_set_TYPE(const OSSL_PARAM *p, const char *key, TYPE val); + + int OSSL_PARAM_get_BN(const OSSL_PARAM *p, const char *key, BIGNUM **val); + int OSSL_PARAM_set_BN(const OSSL_PARAM *p, const char *key, const BIGNUM *val); + + int OSSL_PARAM_get_utf8_string(const OSSL_PARAM *p, char **val, + size_t max_len); + int OSSL_PARAM_set_utf8_string(const OSSL_PARAM *p, const char *val); + + int OSSL_PARAM_get_octet_string(const OSSL_PARAM *p, void **val, + size_t max_len, size_t *used_len); + int OSSL_PARAM_set_octet_string(const OSSL_PARAM *p, const void *val, + size_t len); + + int OSSL_PARAM_get_utf8_ptr(const OSSL_PARAM *p, char **val); + int OSSL_PARAM_set_utf8_ptr(const OSSL_PARAM *p, char *val); + + int OSSL_PARAM_get_octet_ptr(const OSSL_PARAM *p, void **val, + size_t *used_len); + int OSSL_PARAM_set_octet_ptr(const OSSL_PARAM *p, void *val, size_t used_len); + +=head1 DESCRIPTION + +A collection of utility functions that simplify and add type safety to the +OSSL_PARAM arrays. The following B names are supported: + +=over 1 + +=item * + +double + +=item * + +int + +=item * + +int32 (int32_t) + +=item * + +int64 (int64_t) + +=item * + +long int (long) + +=item * + +size_t + +=item * + +uint32 (uint32_t) + +=item * + +uint64 (uint64_t) + +=item * + +unsigned int (uint) + +=item * + +unsigned long int (ulong) + +=back + +OSSL_PARAM_TYPE() are a series of macros designed to assist initialising an +array of OSSL_PARAM structures. +Each of these macros defines a parameter of the specified B with the +provided B and parameter variable B

. + +OSSL_PARAM_utf8_string(), OSSL_PARAM_octet_string(), OSSL_PARAM_utf8_ptr(), +OSSL_PARAM_octet_ptr() are macros that provide support for defining UTF8 +strings and OCTET strings. +A parameter with name B is defined. +The storage for this parameter is at B
and is of B bytes. + +OSSL_PARAM_SIZED_TYPE() are a second series of macros designed to assist with +the initialisation of OSSL_PARAM structures. +They are similar to the OSSL_PARAM_TYPE() macros but also include a +B argument which contains the address of a size_t variable which +will be populated with the actual size of the parameter upon return from a +OSSL_PARAM_set_TYPE() call. + +OSSL_PARAM_SIZED_BN(), OSSL_PARAM_SIZED_utf8_string(), +OSSL_PARAM_SIZED_octet_string(), OSSL_PARAM_SIZED_utf8_ptr(), +OSSL_PARAM_SIZED_octet_ptr() are macros that provide support for defining large +integers, UTF8 string and OCTET strings in an OSSL_PARAM array. +A parameter with name B is defined. +The storage for this parameter is at B
and is of B bytes. +The size used by the parameter value, in bytes, is written to B. + +OSSL_PARAM_END provides an end of parameter list marker. +This should terminate all OSSL_PARAM arrays. + +OSSL_PARAM_construct_TYPE() are a series of functions that create OSSL_PARAM +records dynamically. +A parameter with name B is created. +The parameter will use storage pointed to by B and return size of B. + +OSSL_PARAM_construct_BN() is a function that constructs a large integer +OSSL_PARAM structure. +A parameter with name B, storage B, size B and return +size B is created. + +OSSL_PARAM_construct_utf8_string() is a function that constructs a UTF8 +string OSSL_PARAM structure. +A parameter with name B, storage B, size B and return +size B is created. + +OSSL_PARAM_construct_octet_string() is a function that constructs an OCTET +string OSSL_PARAM structure. +A parameter with name B, storage B, size B and return +size B is created. + +OSSL_PARAM_construct_utf8_ptr() is a function that constructes a UTF string +pointer OSSL_PARAM structure. +A parameter with name B, storage pointer B<*buf>, size B and +return size B is created. + +OSSL_PARAM_construct_octet_ptr() is a function that constructes an OCTET string +pointer OSSL_PARAM structure. +A parameter with name B, storage pointer B<*buf>, size B and +return size B is created. + +OSSL_PARAM_construct_end() is a function that constructs the terminating +OSSL_PARAM structure. + +OSSL_PARAM_locate() is a function that searches an B of parameters for +the one matching the B name. + +OSSL_PARAM_get_TYPE() retrieves a value of type B from the parameter B

. +The value is copied to the address B. +Type coercion takes place as discussed in the NOTES section. + +OSSL_PARAM_set_TYPE() stores a value B of type B into the paramter +B

. +Type coercion takes place as discussed in the NOTES section. + +OSSL_PARAM_get_BN() retrieves a BIGNUM from the parameter pointed to by B

. +The BIGNUM referenced by B is updated and is allocated if B<*val> is +B. + +OSSL_PARAM_set_BN() stores the BIGNUM B into the paramater B

. + +OSSL_PARAM_get_utf8_string() retrieves a UTF8 string from the parameter +pointed to by B

. +The string is either stored into B<*val> with a length limit of B or, +in the case when B<*val> is B, memory is allocated for the string and +B is ignored. +If memory is allocated by this function, it must be freed by the caller. + +OSSL_PARAM_set_utf8_string() sets a UTF8 string from the parameter pointed to +by B

to the value referenced by B. + +OSSL_PARAM_get_octet_string() retrieves an OCTET string from the parameter +pointed to by B

. +The OCTETs are either stored into B<*val> with a length limit of B or, +in the case when B<*val> is B, memory is allocated and +B is ignored. +If memory is allocated by this function, it must be freed by the caller. + +OSSL_PARAM_set_octet_string() sets an OCTET string from the parameter +pointed to by B

to the value referenced by B. + +OSSL_PARAM_get_utf8_ptr() retrieves the UTF8 string pointer from the parameter +referenced by B

and stores it in B<*val>. + +OSSL_PARAM_set_utf8_ptr() sets the UTF8 string pointer in the parameter +referenced by B

to the values B. + +OSSL_PARAM_get_octet_ptr() retrieves the OCTET string pointer from the parameter +referenced by B

and stores it in B<*val>. +The length of the OCTET string is stored in B<*used_len>. + +OSSL_PARAM_set_octet_ptr() sets the OCTET string pointer in the parameter +referenced by B

to the values B. +The length of the OCTET string is provided by B. + +=head1 RETURN VALUES + +OSSL_PARAM_construct_TYPE(), OSSL_PARAM_construct_BN(), +OSSL_PARAM_construct_utf8_string(), OSSL_PARAM_construct_octet_string(), +OSSL_PARAM_construct_utf8_ptr() and OSSL_PARAM_construct_octet_ptr() +return a populated OSSL_PARAM structure. + +OSSL_PARAM_locate() returns a pointer to the matching OSSL_PARAM object. +It returns B on error or when no object matching B exists in +the B. + +All other functions return B<1> on success and B<0> on failure. + +=head1 NOTES + +Native types will be converted as required only if the value is exactly +representable by the target type or parameter. +Apart from that, the functions must be used appropriately for the +expected type of the parameter. + +For OSSL_PARAM_get_utf8_ptr() and OSSL_PARAM_get_octet_ptr(), B +is not relevant if the purpose is to send the B array to a +I, i.e. to get parameter data back. +In that case, B can safely be given zero. +See L for further information on the +possible purposes. + +=head1 EXAMPLES + +Reusing the examples from L to just show how +C arrays can be handled using the macros and functions +defined herein. + +=head2 Example 1 + +This example is for setting parameters on some object: + + #include + + const char *foo = "some string"; + size_t foo_l = strlen(foo) + 1; + const char bar[] = "some other string"; + const OSSL_PARAM set[] = { + OSSL_PARAM_utf8_ptr("foo", foo, foo_l), + OSSL_PARAM_utf8_string("bar", bar, sizeof(bar)), + OSSL_PARAM_END + }; + +=head2 Example 2 + +This example is for requesting parameters on some object, and also +demonstrates that the requestor isn't obligated to request all +available parameters: + + const char *foo = NULL; + size_t foo_l; + char bar[1024]; + size_t bar_l; + const OSSL_PARAM request[] = { + OSSL_PARAM_UTF8_PTR("foo", foo, 0, foo_l), + OSSL_PARAM_UTF8_STRING("bar", bar, sizeof(bar), bar_l), + OSSL_PARAM_END + }; + +A I that receives this array (as C in this example) +could fill in the parameters like this: + + /* const OSSL_PARAM *params */ + + const OSSL_PARAM *p; + + if ((p = OSSL_PARAM_locate(params, "foo")) == NULL) + OSSL_PARAM_set_utf8_ptr(p, "foo value"); + if ((p = OSSL_PARAM_locate(params, "bar")) == NULL) + OSSL_PARAM_set_utf8_ptr(p, "bar value"); + if ((p = OSSL_PARAM_locate(params, "cookie")) == NULL) + OSSL_PARAM_set_utf8_ptr(p, "cookie value"); + +=head1 SEE ALSO + +L, L + +=head1 HISTORY + +These APIs were introduced in OpenSSL 3.0.0. + +=head1 COPYRIGHT + +Copyright 2019 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 +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/util/private.num b/util/private.num index 53edf4a7a4..7f4bf907ea 100644 --- a/util/private.num +++ b/util/private.num @@ -328,21 +328,18 @@ OpenSSL_add_all_algorithms define deprecated 1.1.0 OpenSSL_add_all_ciphers define deprecated 1.1.0 OpenSSL_add_all_digests define deprecated 1.1.0 OpenSSL_add_ssl_algorithms define +OSSL_PARAM_TYPE define +OSSL_PARAM_octet_ptr define +OSSL_PARAM_octet_string define OSSL_PARAM_utf8_ptr define +OSSL_PARAM_utf8_string define OSSL_PARAM_SIZED_BN define -OSSL_PARAM_TYPE generic -OSSL_PARAM_construct_TYPE generic -OSSL_PARAM_octet_string define +OSSL_PARAM_SIZED_TYPE define OSSL_PARAM_SIZED_octet_ptr define -OSSL_PARAM_utf8_string define -OSSL_PARAM_octet_ptr define +OSSL_PARAM_SIZED_octet_string define OSSL_PARAM_SIZED_utf8_ptr define OSSL_PARAM_SIZED_utf8_string define -OSSL_PARAM_SIZED_TYPE generic -OSSL_PARAM_get_TYPE generic OSSL_PARAM_END define -OSSL_PARAM_set_TYPE generic -OSSL_PARAM_SIZED_octet_string define PEM_FLAG_EAY_COMPATIBLE define PEM_FLAG_ONLY_B64 define PEM_FLAG_SECURE define