| =pod |
| |
| =head1 NAME |
| |
| OSSL_PARAM_double, OSSL_PARAM_int, OSSL_PARAM_int32, OSSL_PARAM_int64, |
| OSSL_PARAM_long, OSSL_PARAM_size_t, OSSL_PARAM_time_t, OSSL_PARAM_uint, |
| OSSL_PARAM_uint32, OSSL_PARAM_uint64, OSSL_PARAM_ulong, OSSL_PARAM_BN, |
| OSSL_PARAM_utf8_string, OSSL_PARAM_octet_string, OSSL_PARAM_utf8_ptr, |
| OSSL_PARAM_octet_ptr, |
| OSSL_PARAM_END, OSSL_PARAM_DEFN, |
| 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_time_t, OSSL_PARAM_construct_uint, |
| OSSL_PARAM_construct_uint32, OSSL_PARAM_construct_uint64, |
| OSSL_PARAM_construct_ulong, 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_locate_const, |
| 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_time_t, OSSL_PARAM_get_uint, OSSL_PARAM_get_uint32, |
| OSSL_PARAM_get_uint64, OSSL_PARAM_get_ulong, OSSL_PARAM_get_BN, |
| OSSL_PARAM_get_utf8_string, OSSL_PARAM_get_octet_string, |
| OSSL_PARAM_get_utf8_ptr, OSSL_PARAM_get_octet_ptr, |
| OSSL_PARAM_get_utf8_string_ptr, OSSL_PARAM_get_octet_string_ptr, |
| 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_time_t, OSSL_PARAM_set_uint, OSSL_PARAM_set_uint32, |
| OSSL_PARAM_set_uint64, OSSL_PARAM_set_ulong, OSSL_PARAM_set_BN, |
| OSSL_PARAM_set_utf8_string, OSSL_PARAM_set_octet_string, |
| OSSL_PARAM_set_utf8_ptr, OSSL_PARAM_set_octet_ptr, |
| OSSL_PARAM_UNMODIFIED, OSSL_PARAM_modified, OSSL_PARAM_set_all_unmodified |
| - OSSL_PARAM helpers |
| |
| =head1 SYNOPSIS |
| |
| =for openssl generic |
| |
| #include <openssl/params.h> |
| |
| /* |
| * TYPE in function names is one of: |
| * double, int, int32, int64, long, size_t, time_t, uint, uint32, uint64, ulong |
| * Corresponding TYPE in function arguments is one of: |
| * double, int, int32_t, int64_t, long, size_t, time_t, unsigned int, uint32_t, |
| * uint64_t, unsigned long |
| */ |
| |
| #define OSSL_PARAM_TYPE(key, address) |
| #define OSSL_PARAM_BN(key, address, size) |
| #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_END |
| |
| #define OSSL_PARAM_UNMODIFIED |
| |
| #define OSSL_PARAM_DEFN(key, type, addr, sz) \ |
| { (key), (type), (addr), (sz), OSSL_PARAM_UNMODIFIED } |
| |
| OSSL_PARAM OSSL_PARAM_construct_TYPE(const char *key, TYPE *buf); |
| OSSL_PARAM OSSL_PARAM_construct_BN(const char *key, unsigned char *buf, |
| size_t bsize); |
| OSSL_PARAM OSSL_PARAM_construct_utf8_string(const char *key, char *buf, |
| size_t bsize); |
| OSSL_PARAM OSSL_PARAM_construct_octet_string(const char *key, void *buf, |
| size_t bsize); |
| OSSL_PARAM OSSL_PARAM_construct_utf8_ptr(const char *key, char **buf, |
| size_t bsize); |
| OSSL_PARAM OSSL_PARAM_construct_octet_ptr(const char *key, void **buf, |
| size_t bsize); |
| OSSL_PARAM OSSL_PARAM_construct_end(void); |
| |
| OSSL_PARAM *OSSL_PARAM_locate(OSSL_PARAM *array, const char *key); |
| const OSSL_PARAM *OSSL_PARAM_locate_const(const OSSL_PARAM *array, |
| const char *key); |
| |
| int OSSL_PARAM_get_TYPE(const OSSL_PARAM *p, TYPE *val); |
| int OSSL_PARAM_set_TYPE(OSSL_PARAM *p, TYPE val); |
| |
| int OSSL_PARAM_get_BN(const OSSL_PARAM *p, BIGNUM **val); |
| int OSSL_PARAM_set_BN(OSSL_PARAM *p, 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(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(OSSL_PARAM *p, const void *val, size_t len); |
| |
| int OSSL_PARAM_get_utf8_ptr(const OSSL_PARAM *p, const char **val); |
| int OSSL_PARAM_set_utf8_ptr(OSSL_PARAM *p, const char *val); |
| |
| int OSSL_PARAM_get_octet_ptr(const OSSL_PARAM *p, const void **val, |
| size_t *used_len); |
| int OSSL_PARAM_set_octet_ptr(OSSL_PARAM *p, const void *val, |
| size_t used_len); |
| |
| int OSSL_PARAM_get_utf8_string_ptr(const OSSL_PARAM *p, const char **val); |
| int OSSL_PARAM_get_octet_string_ptr(const OSSL_PARAM *p, const void **val, |
| size_t *used_len); |
| |
| int OSSL_PARAM_modified(const OSSL_PARAM *param); |
| void OSSL_PARAM_set_all_unmodified(OSSL_PARAM *params); |
| |
| =head1 DESCRIPTION |
| |
| A collection of utility functions that simplify and add type safety to the |
| B<OSSL_PARAM> arrays. The following B<I<TYPE>> names are supported: |
| |
| =over 1 |
| |
| =item * |
| |
| double |
| |
| =item * |
| |
| int |
| |
| =item * |
| |
| int32 (int32_t) |
| |
| =item * |
| |
| int64 (int64_t) |
| |
| =item * |
| |
| long int (long) |
| |
| =item * |
| |
| time_t |
| |
| =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 B<OSSL_PARAM> structures. |
| Each of these macros defines a parameter of the specified B<I<TYPE>> with the |
| provided I<key> and parameter variable I<address>. |
| |
| OSSL_PARAM_utf8_string(), OSSL_PARAM_octet_string(), OSSL_PARAM_utf8_ptr(), |
| OSSL_PARAM_octet_ptr(), OSSL_PARAM_BN() are macros that provide support |
| for defining UTF8 strings, OCTET strings and big numbers. |
| A parameter with name I<key> is defined. |
| The storage for this parameter is at I<address> and is of I<size> bytes. |
| |
| OSSL_PARAM_END provides an end of parameter list marker. |
| This should terminate all B<OSSL_PARAM> arrays. |
| |
| The OSSL_PARAM_DEFN() macro provides the ability to construct a single |
| B<OSSL_PARAM> (typically used in the construction of B<OSSL_PARAM> arrays). The |
| I<key>, I<type>, I<addr> and I<sz> arguments correspond to the I<key>, |
| I<data_type>, I<data> and I<data_size> fields of the B<OSSL_PARAM> structure as |
| described on the L<OSSL_PARAM(3)> page. |
| |
| OSSL_PARAM_construct_TYPE() are a series of functions that create B<OSSL_PARAM> |
| records dynamically. |
| A parameter with name I<key> is created. |
| The parameter will use storage pointed to by I<buf> and return size of I<ret>. |
| |
| OSSL_PARAM_construct_BN() is a function that constructs a large integer |
| B<OSSL_PARAM> structure. |
| A parameter with name I<key>, storage I<buf>, size I<bsize> and return |
| size I<rsize> is created. |
| |
| OSSL_PARAM_construct_utf8_string() is a function that constructs a UTF8 |
| string B<OSSL_PARAM> structure. |
| A parameter with name I<key>, storage I<buf> and size I<bsize> is created. |
| If I<bsize> is zero, the string length is determined using strlen(3). |
| Generally pass zero for I<bsize> instead of calling strlen(3) yourself. |
| |
| OSSL_PARAM_construct_octet_string() is a function that constructs an OCTET |
| string B<OSSL_PARAM> structure. |
| A parameter with name I<key>, storage I<buf> and size I<bsize> is created. |
| |
| OSSL_PARAM_construct_utf8_ptr() is a function that constructs a UTF8 string |
| pointer B<OSSL_PARAM> structure. |
| A parameter with name I<key>, storage pointer I<*buf> and size I<bsize> |
| is created. |
| |
| OSSL_PARAM_construct_octet_ptr() is a function that constructs an OCTET string |
| pointer B<OSSL_PARAM> structure. |
| A parameter with name I<key>, storage pointer I<*buf> and size I<bsize> |
| is created. |
| |
| OSSL_PARAM_construct_end() is a function that constructs the terminating |
| B<OSSL_PARAM> structure. |
| |
| OSSL_PARAM_locate() is a function that searches an I<array> of parameters for |
| the one matching the I<key> name. |
| |
| OSSL_PARAM_locate_const() behaves exactly like OSSL_PARAM_locate() except for |
| the presence of I<const> for the I<array> argument and its return value. |
| |
| OSSL_PARAM_get_TYPE() retrieves a value of type B<I<TYPE>> from the parameter |
| I<p>. |
| The value is copied to the address I<val>. |
| Type coercion takes place as discussed in the NOTES section. |
| |
| OSSL_PARAM_set_TYPE() stores a value I<val> of type B<I<TYPE>> into the |
| parameter I<p>. |
| If the parameter's I<data> field is NULL, then only its I<return_size> field |
| will be assigned the size the parameter's I<data> buffer should have. |
| Type coercion takes place as discussed in the NOTES section. |
| |
| OSSL_PARAM_get_BN() retrieves a BIGNUM from the parameter pointed to by I<p>. |
| The BIGNUM referenced by I<val> is updated and is allocated if I<*val> is |
| NULL. |
| |
| OSSL_PARAM_set_BN() stores the BIGNUM I<val> into the parameter I<p>. |
| If the parameter's I<data> field is NULL, then only its I<return_size> field |
| will be assigned the size the parameter's I<data> buffer should have. |
| |
| OSSL_PARAM_get_utf8_string() retrieves a UTF8 string from the parameter |
| pointed to by I<p>. |
| The string is stored into I<*val> with a size limit of I<max_len>, |
| which must be large enough to accommodate a terminating NUL byte, |
| otherwise this function will fail. |
| If I<*val> is NULL, memory is allocated for the string (including the |
| terminating NUL byte) and I<max_len> 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 I<p> to the value referenced by I<val>. |
| If the parameter's I<data> field isn't NULL, its I<data_size> must indicate |
| that the buffer is large enough to accommodate the string that I<val> points at, |
| not including the terminating NUL byte, or this function will fail. |
| A terminating NUL byte is added only if the parameter's I<data_size> indicates |
| the buffer is longer than the string length, otherwise the string will not be |
| NUL terminated. |
| If the parameter's I<data> field is NULL, then only its I<return_size> field |
| will be assigned the minimum size the parameter's I<data> buffer should have |
| to accommodate the string, not including a terminating NUL byte. |
| |
| OSSL_PARAM_get_octet_string() retrieves an OCTET string from the parameter |
| pointed to by I<p>. |
| The OCTETs are either stored into I<*val> with a length limit of I<max_len> or, |
| in the case when I<*val> is NULL, memory is allocated and |
| I<max_len> is ignored. I<*used_len> is populated with the number of OCTETs |
| stored. If I<val> is NULL then the OCTETS are not stored, but I<*used_len> is |
| still populated. |
| 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 I<p> to the value referenced by I<val>. |
| If the parameter's I<data> field is NULL, then only its I<return_size> field |
| will be assigned the size the parameter's I<data> buffer should have. |
| |
| OSSL_PARAM_get_utf8_ptr() retrieves the UTF8 string pointer from the parameter |
| referenced by I<p> and stores it in I<*val>. |
| |
| OSSL_PARAM_set_utf8_ptr() sets the UTF8 string pointer in the parameter |
| referenced by I<p> to the values I<val>. |
| |
| OSSL_PARAM_get_octet_ptr() retrieves the OCTET string pointer from the parameter |
| referenced by I<p> and stores it in I<*val>. |
| The length of the OCTET string is stored in I<*used_len>. |
| |
| OSSL_PARAM_set_octet_ptr() sets the OCTET string pointer in the parameter |
| referenced by I<p> to the values I<val>. |
| The length of the OCTET string is provided by I<used_len>. |
| |
| OSSL_PARAM_get_utf8_string_ptr() retrieves the pointer to a UTF8 string from |
| the parameter pointed to by I<p>, and stores that pointer in I<*val>. |
| This is different from OSSL_PARAM_get_utf8_string(), which copies the |
| string. |
| |
| OSSL_PARAM_get_octet_string_ptr() retrieves the pointer to a octet string |
| from the parameter pointed to by I<p>, and stores that pointer in I<*val>, |
| along with the string's length in I<*used_len>. |
| This is different from OSSL_PARAM_get_octet_string(), which copies the |
| string. |
| |
| The OSSL_PARAM_UNMODIFIED macro is used to detect if a parameter was set. On |
| creation, via either the macros or construct calls, the I<return_size> field |
| is set to this. If the parameter is set using the calls defined herein, the |
| I<return_size> field is changed. |
| |
| OSSL_PARAM_modified() queries if the parameter I<param> has been set or not |
| using the calls defined herein. |
| |
| OSSL_PARAM_set_all_unmodified() resets the unused indicator for all parameters |
| in the array I<params>. |
| |
| =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 B<OSSL_PARAM> structure. |
| |
| OSSL_PARAM_locate() and OSSL_PARAM_locate_const() return a pointer to |
| the matching B<OSSL_PARAM> object. They return NULL on error or when |
| no object matching I<key> exists in the I<array>. |
| |
| OSSL_PARAM_modified() returns 1 if the parameter was set and 0 otherwise. |
| |
| All other functions return 1 on success and 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. |
| |
| OSSL_PARAM_get_BN() and OSSL_PARAM_set_BN() only support nonnegative |
| B<BIGNUM>s when the desired data type is B<OSSL_PARAM_UNSIGNED_INTEGER>. |
| OSSL_PARAM_construct_BN() currently constructs an B<OSSL_PARAM> structure |
| with the data type B<OSSL_PARAM_UNSIGNED_INTEGER>. |
| |
| For OSSL_PARAM_construct_utf8_ptr() and OSSL_PARAM_consstruct_octet_ptr(), |
| I<bsize> is not relevant if the purpose is to send the B<OSSL_PARAM> array |
| to a I<responder>, i.e. to get parameter data back. |
| In that case, I<bsize> can safely be given zero. |
| See L<OSSL_PARAM(3)/DESCRIPTION> for further information on the |
| possible purposes. |
| |
| =head1 EXAMPLES |
| |
| Reusing the examples from L<OSSL_PARAM(3)> to just show how |
| B<OSSL_PARAM> arrays can be handled using the macros and functions |
| defined herein. |
| |
| =head2 Example 1 |
| |
| This example is for setting parameters on some object: |
| |
| #include <openssl/core.h> |
| |
| const char *foo = "some string"; |
| size_t foo_l = strlen(foo); |
| 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) - 1), |
| 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; |
| char bar[1024]; |
| OSSL_PARAM request[] = { |
| OSSL_PARAM_utf8_ptr("foo", &foo, 0), |
| OSSL_PARAM_utf8_string("bar", bar, sizeof(bar)), |
| OSSL_PARAM_END |
| }; |
| |
| A I<responder> that receives this array (as C<params> in this example) |
| could fill in the parameters like this: |
| |
| /* OSSL_PARAM *params */ |
| |
| 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_string(p, "bar value"); |
| if ((p = OSSL_PARAM_locate(params, "cookie")) != NULL) |
| OSSL_PARAM_set_utf8_ptr(p, "cookie value"); |
| |
| =head1 SEE ALSO |
| |
| L<openssl-core.h(7)>, L<OSSL_PARAM(3)> |
| |
| =head1 HISTORY |
| |
| These APIs were introduced in OpenSSL 3.0. |
| |
| =head1 COPYRIGHT |
| |
| Copyright 2019-2022 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<https://www.openssl.org/source/license.html>. |
| |
| =cut |