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 <tmraz@fedoraproject.org>
(Merged from https://github.com/openssl/openssl/pull/11480)

diff --git a/doc/man3/OSSL_PARAM.pod b/doc/man3/OSSL_PARAM.pod
index cd7d41006bffe20511a19185b4f6078f97f6816c..a2392a9609c647235439c1d2d9c38b7f2070d292 100644 (file)
--- 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<OSSL_PARAM_UTF8_STRING> is that I<data>
 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<OSSL_PARAM_UTF8_STRING> 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<OSSL_PARAM_OCTET_STRING> is that
 I<data> 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<OSSL_PARAM_OCTET_STRING> 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 5959a3188064690c09c5b6c961675d6ba9b57df4..e5a4b9266a2313b46991c55fee060b259d4d519a 100644 (file)
--- 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