From: Pauli Date: Tue, 7 Apr 2020 05:50:02 +0000 (+1000) Subject: params: add a warning about the PTR types. X-Git-Tag: openssl-3.0.0-alpha1~143 X-Git-Url: https://git.openssl.org/gitweb/?p=openssl.git;a=commitdiff_plain;h=82e1fc1bc06a87278b2dada07e40a4296e6898c7 params: add a warning about the PTR types. 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 (Merged from https://github.com/openssl/openssl/pull/11480) --- diff --git a/doc/man3/OSSL_PARAM.pod b/doc/man3/OSSL_PARAM.pod index cd7d41006b..a2392a9609 100644 --- a/doc/man3/OSSL_PARAM.pod +++ b/doc/man3/OSSL_PARAM.pod @@ -159,6 +159,9 @@ The parameter data is a pointer to a printable string. The difference between this and B is that I doesn't point directly at the data, but to a pointer that points to the data. +If there is any uncertainty about which to use, B is +almost certainly the correct choice. + This is used to indicate that constant data is or will be passed, and there is therefore no need to copy the data that is passed, just the pointer to it. @@ -182,6 +185,9 @@ The difference between this and B is that I doesn't point directly at the data, but to a pointer that points to the data. +If there is any uncertainty about which to use, B is +almost certainly the correct choice. + This is used to indicate that constant data is or will be passed, and there is therefore no need to copy the data that is passed, just the pointer to it. diff --git a/include/openssl/core.h b/include/openssl/core.h index 5959a31880..e5a4b9266a 100644 --- a/include/openssl/core.h +++ b/include/openssl/core.h @@ -124,6 +124,9 @@ struct ossl_param_st { * * WARNING! Using these is FRAGILE, as it assumes that the actual * data and its location are constant. + * + * EXTRA WARNING! If you are not completely sure you most likely want + * to use the OSSL_PARAM_UTF8_STRING type. */ # define OSSL_PARAM_UTF8_PTR 6 /*- @@ -140,6 +143,9 @@ struct ossl_param_st { * * WARNING! Using these is FRAGILE, as it assumes that the actual * data and its location are constant. + * + * EXTRA WARNING! If you are not completely sure you most likely want + * to use the OSSL_PARAM_OCTET_STRING type. */ # define OSSL_PARAM_OCTET_PTR 7