diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/man3/OSSL_PARAM.pod | 7 | ||||
| -rw-r--r-- | doc/man3/OSSL_PARAM_int.pod | 20 | ||||
| -rw-r--r-- | doc/man7/EVP_KDF-SSHKDF.pod | 2 |
3 files changed, 19 insertions, 10 deletions
diff --git a/doc/man3/OSSL_PARAM.pod b/doc/man3/OSSL_PARAM.pod index fdf376a206..99f4e2ce62 100644 --- a/doc/man3/OSSL_PARAM.pod +++ b/doc/man3/OSSL_PARAM.pod @@ -97,6 +97,13 @@ setting parameters) or shall (when requesting parameters) be stored, and I<data_size> is its size in bytes. The organization of the data depends on the parameter type and flag. +The I<data_size> needs special attention with the parameter type +B<OSSL_PARAM_UTF8_STRING> in relation to C strings. When setting +parameters, the size should be set to the length of the string, not +counting the terminating NUL byte. When requesting parameters, the +size should be set to the size of the buffer to be populated, which +should accomodate enough space for a terminating NUL byte. + When I<requesting parameters>, it's acceptable for I<data> to be NULL. This can be used by the I<requestor> to figure out dynamically exactly how much buffer space is needed to store the parameter data. diff --git a/doc/man3/OSSL_PARAM_int.pod b/doc/man3/OSSL_PARAM_int.pod index d637d94f8a..25b87014b7 100644 --- a/doc/man3/OSSL_PARAM_int.pod +++ b/doc/man3/OSSL_PARAM_int.pod @@ -184,8 +184,7 @@ size I<rsize> is created. OSSL_PARAM_construct_utf8_string() is a function that constructs a UTF8 string 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) + 1 for the -null termination byte. +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 @@ -232,15 +231,18 @@ 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 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 for the string and -I<max_len> is ignored. +The string is stored into I<*val> with a size limit of I<max_len>, +which must be large enough to accomodate a terminating NUL byte, +otherwise this function will fail. +If I<*val> is NULL, memory is allocated for the string 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 is NULL, then only its I<return_size> field -will be assigned the size the parameter's I<data> buffer should have. +will be assigned the minimum size the parameter's I<data> buffer should have +to accomodate the string, including a terminating NUL byte. OSSL_PARAM_get_octet_string() retrieves an OCTET string from the parameter pointed to by I<p>. @@ -334,11 +336,11 @@ This example is for setting parameters on some object: #include <openssl/core.h> const char *foo = "some string"; - size_t foo_l = strlen(foo) + 1; + 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)), + OSSL_PARAM_utf8_string("bar", bar, sizeof(bar) - 1), OSSL_PARAM_END }; @@ -366,7 +368,7 @@ could fill in the parameters like this: 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"); + OSSL_PARAM_set_utf8_string(p, "bar value"); if ((p = OSSL_PARAM_locate(params, "cookie")) != NULL) OSSL_PARAM_set_utf8_ptr(p, "cookie value"); diff --git a/doc/man7/EVP_KDF-SSHKDF.pod b/doc/man7/EVP_KDF-SSHKDF.pod index f0e113c6c8..a2ff902cce 100644 --- a/doc/man7/EVP_KDF-SSHKDF.pod +++ b/doc/man7/EVP_KDF-SSHKDF.pod @@ -124,7 +124,7 @@ This example derives an 8 byte IV using SHA-256 with a 1K "key" and appropriate *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT, session_id, (size_t)32); *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_SSHKDF_TYPE, - type, sizeof(type)); + type, sizeof(type) - 1); *p = OSSL_PARAM_construct_end(); if (EVP_KDF_CTX_set_params(kctx, params) <= 0) /* Error */ |