summaryrefslogtreecommitdiffstats
path: root/doc/man3/OSSL_PARAM.pod
AgeCommit message (Collapse)Author
2022-06-21Update copyright yearMatt Caswell
Reviewed-by: Richard Levitte <levitte@openssl.org> Release: yes
2022-06-16Fix for OSSL_PARAM sample code referencing OSSL_PARAM_UTF8_PTRMichael Baentsch
Reviewed-by: Paul Dale <pauli@openssl.org> Reviewed-by: Shane Lontis <shane.lontis@oracle.com> Reviewed-by: Tomas Mraz <tomas@openssl.org> (Merged from https://github.com/openssl/openssl/pull/18490) (cherry picked from commit 809526a06c1305d67a8f231ca15cd27ec800efce)
2021-08-13Correct documentation errors in regards to UTF8 paramsTomas Mraz
This fixes numerous bugs in documentation in regards to UTF8 params and their sizes. The returned size should always be without the terminating NUL byte. On the other hand on the requestor side the size of the buffer should include the NUL byte if it expects it being included in the returned string. Also make this clear in the EVP_PKEY_get_group_name() documentation which uses utf8 string params under the hood. Fixes #16287 Reviewed-by: Viktor Dukhovni <viktor@openssl.org> Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/16296)
2021-05-05DOCS: Mention that libcrypto has helper functions for OSSL_PARAMsRichard Levitte
Fixes #11165 Reviewed-by: Tomas Mraz <tomas@openssl.org> Reviewed-by: Paul Dale <pauli@openssl.org> (Merged from https://github.com/openssl/openssl/pull/15073)
2021-04-12Add OSSL_PARAM_dup() and OSSL_PARAM_merge().Shane Lontis
These functions are prerequisites for implementing EVP_PKEY_todata(). OSSL_PARAM_dup() is required to make a deep copy of the exported params (since the provider export() uses a OSSL_PARAM_BLD which throws away the data after the call), and then use OSSL_PARAM_merge() to add some additional params that can be passed to the EVP_PKEY_todata(). Reviewed-by: Paul Dale <pauli@openssl.org> (Merged from https://github.com/openssl/openssl/pull/14785)
2021-03-11Update copyright yearMatt Caswell
Reviewed-by: Richard Levitte <levitte@openssl.org> (Merged from https://github.com/openssl/openssl/pull/14512)
2021-02-18OSSL_PARAM: Correct the assumptions on the UTF8 string lengthRichard Levitte
When the string "ABCDEFGH" is passed, what's considered its data, this? { 'A', 'B', 'C', 'D', 'E', 'F', 'G', 'H' } or this? { 'A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', '\0' } If it's passed as a pass phrase, should the terminating NUL byte be considered part of the pass phrase, or not? Our treatment of OSSL_PARAMs with the data type OSSL_PARAM_UTF8_STRING set the length of the string to include the terminating NUL byte, which is quite confusing. What should the recipient of such a string believe? Instead of perpetuating this confusion, we change the assumption to set the OSSL_PARAM to the length of the string, not including the terminating NUL byte, thereby giving it the same value as a strlen() call would give. Reviewed-by: Tomas Mraz <tomas@openssl.org> (Merged from https://github.com/openssl/openssl/pull/14168)
2020-11-26DOC: Add note on how to terminate an OSSL_PARAM arrayRichard Levitte
The examples are also updated to have correct terminators. doc/man3/OSSL_PARAM.pod is deliberately written with no help from the constructor macros described in OSSL_PARAM_int.pod. Therefore, use of OSSL_PARAM_END isn't shown directly here, only leaving a link to its man-page to indicate that there is that option. Fixes #11280 Reviewed-by: Paul Dale <paul.dale@oracle.com> (Merged from https://github.com/openssl/openssl/pull/13478)
2020-04-23Update copyright yearMatt Caswell
Reviewed-by: Richard Levitte <levitte@openssl.org> (Merged from https://github.com/openssl/openssl/pull/11616)
2020-04-08params: add a warning about the PTR types.Pauli
The warning is deter the unsure -- if in doubt the PTR type is almost certainly NOT what you should be using. Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org> (Merged from https://github.com/openssl/openssl/pull/11480)
2019-11-03doc/man3/OSSL_PARAM.pod: Clarify return_size with integer typesRichard Levitte
Reviewed-by: Patrick Steuer <patrick.steuer@de.ibm.com> (Merged from https://github.com/openssl/openssl/pull/10326)
2019-09-27OSSL_PARAM.pod: document the mechanism to figure out buffer sizesRichard Levitte
When requesting parameters, it's acceptable to make a first pass with the |data| field of some parameters being NULL. That can be used to help the requestor to figure out dynamically what buffer size is needed. For variable size parameters, there's no other way to find out. Reviewed-by: Paul Dale <paul.dale@oracle.com> (Merged from https://github.com/openssl/openssl/pull/10025)
2019-09-12doc/man3/OSSL_PARAM.pod: add details about multiple elements with same keyRichard Levitte
Usually, each element in an OSSL_PARAM array will have a unique key. However, there may be some rare cases when a responder will handle multiple elements with the same key. This adds a short passage explaining this case. Reviewed-by: Paul Dale <paul.dale@oracle.com> (Merged from https://github.com/openssl/openssl/pull/9741)
2019-09-12doc/man3/OSSL_PARAM.pod: remove a comment that isn't true any moreRichard Levitte
Reviewed-by: Paul Dale <paul.dale@oracle.com> (Merged from https://github.com/openssl/openssl/pull/9741)
2019-09-12doc/man3/OSSL_PARAM.pod: conform to man-page standardsRichard Levitte
Reviewed-by: Paul Dale <paul.dale@oracle.com> (Merged from https://github.com/openssl/openssl/pull/9741)
2019-07-23Describe OSSL_PARAM as a parameter descriptorRichard Levitte
This affects doc/man3/OSSL_PARAM.pod and doc/man7/openssl-core.h.pod Reviewed-by: Paul Dale <paul.dale@oracle.com> (Merged from https://github.com/openssl/openssl/pull/9346)
2019-07-19doc: fix some linksRichard Levitte
Some links are aged and need an adjustment. Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/9407)
2019-06-24Change OSSL_PARAM return size to not be a pointer.Pauli
Instead of referencing the return size from the OSSL_PARAM structure, make the size a field within the structure. Reviewed-by: Richard Levitte <levitte@openssl.org> (Merged from https://github.com/openssl/openssl/pull/9135)
2019-06-12OSSL_PARAM example code bug fix.Pauli
Technically not a bug since the code worked but the array index shouldn't have been constant after searching for the field. Reviewed-by: Richard Levitte <levitte@openssl.org> (Merged from https://github.com/openssl/openssl/pull/9136)
2019-03-12OSSL_PARAM helper functions.Pauli
Provide a number of functions to allow parameters to be set and retrieved in a type safe manner. Functions are provided for many integral types plus double, BIGNUM, UTF8 strings and OCTET strings. All of the integer functions will widen the parameter data as required. This permits a degree of malleability in the parameter definition. For example a type can be changed from a thirty two bit integer to a sixty four bit one without changing application code. Only four and eight byte integral sizes are supported here. A pair of real functions are available for doubles. A pair of functions is available for BIGNUMs. These accept any sized unsigned integer input and convert to/from a BIGNUM. For each OCTET and UTF8 strings, four functions are defined. This provide get and set functionality for string and for pointers to strings. The latter avoiding copies but have other inherent risks. Finally, some utility macros and functions are defined to allow OSSL_PARAM definition arrays to be specified in a simple manner. There are two macro and one function for most types. The exception being BIGNUM, for which there is one macro and one function. Reviewed-by: Matt Caswell <matt@openssl.org> Reviewed-by: Richard Levitte <levitte@openssl.org> (Merged from https://github.com/openssl/openssl/pull/8451)
2019-03-12Rename 'buffer' to 'data' in OSSL_PARAMRichard Levitte
The OSSL_PARAM attribute names |buffer| and |buffer_size| may lead to confusion, as they may make some think that the memory pointed at is an intermediate memory are. This is not generally the case, so we rename |buffer| and |buffer_size| to |data| and |data_size| Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/8451)
2019-02-27Replumbing: Add include/openssl/core.h, initially with core typesRichard Levitte
Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/8286)