params: add a warning about the PTR types.
authorPauli <paul.dale@oracle.com>
Tue, 7 Apr 2020 05:50:02 +0000 (15:50 +1000)
committerPauli <paul.dale@oracle.com>
Wed, 8 Apr 2020 08:00:36 +0000 (18:00 +1000)
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)

doc/man3/OSSL_PARAM.pod
include/openssl/core.h

index cd7d410..a2392a9 100644 (file)
@@ -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.
index 5959a31..e5a4b92 100644 (file)
@@ -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