-*- mode: troff; coding: utf-8 -*-
Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
Standard preamble:
========================================================================
..
.... \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
. ds C` "" . ds C' "" 'br\} . ds C` . ds C' 'br\}
Escape single quotes in literal strings from groff's Unicode transform.
If the F register is >0, we'll generate index entries on stderr for
titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
entries marked with X<> in POD. Of course, you'll have to process the
output yourself in some meaningful fashion.
Avoid warning from groff about undefined register 'F'.
.. .nr rF 0 . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF ========================================================================
Title "OSSL_PARAM_int 3"
way too many mistakes in technical documents.
\fBOSSL_PARAM_TYPE() are a series of macros designed to assist initialising an array of OSSL_PARAM\|(3) structures. Each of these macros defines a parameter of the specified \f(BITYPE with the provided key and parameter variable address.
\fBOSSL_PARAM_utf8_string(), OSSL_PARAM_octet_string(), OSSL_PARAM_utf8_ptr(), \fBOSSL_PARAM_octet_ptr(), OSSL_PARAM_BN() are macros that provide support for defining UTF8 strings, OCTET strings and big numbers. A parameter with name key is defined. The storage for this parameter is at address and is of size bytes.
OSSL_PARAM_END provides an end of parameter list marker. This should terminate all OSSL_PARAM\|(3) arrays.
The OSSL_PARAM_DEFN() macro provides the ability to construct a single \fBOSSL_PARAM\|(3) (typically used in the construction of OSSL_PARAM arrays). The \fIkey, type, addr and sz arguments correspond to the key, \fIdata_type, data and data_size fields of the OSSL_PARAM\|(3) structure as described on the OSSL_PARAM\|(3) page.
\fBOSSL_PARAM_construct_TYPE() are a series of functions that create OSSL_PARAM\|(3) records dynamically. A parameter with name key is created. The parameter will use storage pointed to by buf and return size of ret.
\fBOSSL_PARAM_construct_BN() is a function that constructs a large integer \fBOSSL_PARAM\|(3) structure. A parameter with name key, storage buf, size bsize and return size rsize is created.
\fBOSSL_PARAM_construct_utf8_string() is a function that constructs a UTF8 string OSSL_PARAM\|(3) structure. A parameter with name key, storage buf and size bsize is created. If bsize is zero, the string length is determined using strlen\|(3). Generally pass zero for bsize instead of calling strlen\|(3) yourself.
\fBOSSL_PARAM_construct_octet_string() is a function that constructs an OCTET string OSSL_PARAM\|(3) structure. A parameter with name key, storage buf and size bsize is created.
\fBOSSL_PARAM_construct_utf8_ptr() is a function that constructs a UTF8 string pointer OSSL_PARAM\|(3) structure. A parameter with name key, storage pointer *buf and size bsize is created.
\fBOSSL_PARAM_construct_octet_ptr() is a function that constructs an OCTET string pointer OSSL_PARAM\|(3) structure. A parameter with name key, storage pointer *buf and size bsize is created.
\fBOSSL_PARAM_construct_end() is a function that constructs the terminating \fBOSSL_PARAM\|(3) structure.
\fBOSSL_PARAM_locate() is a function that searches an array of parameters for the one matching the key name.
\fBOSSL_PARAM_locate_const() behaves exactly like OSSL_PARAM_locate() except for the presence of const for the array argument and its return value.
\fBOSSL_PARAM_get_TYPE() retrieves a value of type \f(BITYPE from the parameter \fIp. The value is copied to the address val. Type coercion takes place as discussed in the NOTES section.
\fBOSSL_PARAM_set_TYPE() stores a value val of type \f(BITYPE into the parameter p. If the parameter's data field is NULL, then only its return_size field will be assigned the size the parameter's data buffer should have. Type coercion takes place as discussed in the NOTES section.
\fBOSSL_PARAM_get_BN() retrieves a BIGNUM from the parameter pointed to by p. The BIGNUM referenced by val is updated and is allocated if *val is NULL.
\fBOSSL_PARAM_set_BN() stores the BIGNUM val into the parameter p. If the parameter's data field is NULL, then only its return_size field will be assigned the size the parameter's data buffer should have.
\fBOSSL_PARAM_get_utf8_string() retrieves a UTF8 string from the parameter pointed to by p. The string is stored into *val with a size limit of max_len, which must be large enough to accommodate a terminating NUL byte, otherwise this function will fail. If *val is NULL, memory is allocated for the string (including the terminating NUL byte) and max_len is ignored. If memory is allocated by this function, it must be freed by the caller.
\fBOSSL_PARAM_set_utf8_string() sets a UTF8 string from the parameter pointed to by p to the value referenced by val. If the parameter's data field isn't NULL, its data_size must indicate that the buffer is large enough to accommodate the string that 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 data_size indicates the buffer is longer than the string length, otherwise the string will not be NUL terminated. If the parameter's data field is NULL, then only its return_size field will be assigned the minimum size the parameter's data buffer should have to accommodate the string, not including a terminating NUL byte.
\fBOSSL_PARAM_get_octet_string() retrieves an OCTET string from the parameter pointed to by p. The OCTETs are either stored into *val with a length limit of max_len or, in the case when *val is NULL, memory is allocated and \fImax_len is ignored. *used_len is populated with the number of OCTETs stored. If val is NULL then the OCTETS are not stored, but *used_len is still populated. If memory is allocated by this function, it must be freed by the caller.
\fBOSSL_PARAM_set_octet_string() sets an OCTET string from the parameter pointed to by p to the value referenced by val. If the parameter's data field is NULL, then only its return_size field will be assigned the size the parameter's data buffer should have.
\fBOSSL_PARAM_get_utf8_ptr() retrieves the UTF8 string pointer from the parameter referenced by p and stores it in *val.
\fBOSSL_PARAM_set_utf8_ptr() sets the UTF8 string pointer in the parameter referenced by p to the values val.
\fBOSSL_PARAM_get_octet_ptr() retrieves the OCTET string pointer from the parameter referenced by p and stores it in *val. The length of the OCTET string is stored in *used_len.
\fBOSSL_PARAM_set_octet_ptr() sets the OCTET string pointer in the parameter referenced by p to the values val. The length of the OCTET string is provided by used_len.
\fBOSSL_PARAM_get_utf8_string_ptr() retrieves the pointer to a UTF8 string from the parameter pointed to by p, and stores that pointer in *val. This is different from OSSL_PARAM_get_utf8_string(), which copies the string.
\fBOSSL_PARAM_get_octet_string_ptr() retrieves the pointer to a octet string from the parameter pointed to by p, and stores that pointer in *val, along with the string's length in *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 return_size field is set to this. If the parameter is set using the calls defined herein, the \fIreturn_size field is changed.
\fBOSSL_PARAM_modified() queries if the parameter param has been set or not using the calls defined herein.
\fBOSSL_PARAM_set_all_unmodified() resets the unused indicator for all parameters in the array params.
\fBOSSL_PARAM_locate() and OSSL_PARAM_locate_const() return a pointer to the matching OSSL_PARAM\|(3) object. They return NULL on error or when no object matching key exists in the array.
\fBOSSL_PARAM_modified() returns 1 if the parameter was set and 0 otherwise.
All other functions return 1 on success and 0 on failure.
\fBOSSL_PARAM_get_BN() and OSSL_PARAM_set_BN() currently only support nonnegative BIGNUMs, and by consequence, only \fBOSSL_PARAM_UNSIGNED_INTEGER. OSSL_PARAM_construct_BN() currently constructs an OSSL_PARAM\|(3) structure with the data type \fBOSSL_PARAM_UNSIGNED_INTEGER.
For OSSL_PARAM_construct_utf8_ptr() and OSSL_PARAM_consstruct_octet_ptr(), \fIbsize is not relevant if the purpose is to send the OSSL_PARAM\|(3) array to a responder, i.e. to get parameter data back. In that case, bsize can safely be given zero. See "DESCRIPTION" in OSSL_PARAM\|(3) for further information on the possible purposes.
.Vb 1 #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 }; .Ve
.Vb 7 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 }; .Ve
A responder that receives this array (as \*(C`params\*(C' in this example) could fill in the parameters like this:
.Vb 1 /* 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"); .Ve
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 <https://www.openssl.org/source/license.html>.