[openssl] master update

[Dr. Paul Dale]

The branch master has been updated
       via  82e1fc1bc06a87278b2dada07e40a4296e6898c7 (commit)
      from  069165d10646a22000c596095cc04d43bbf1f807 (commit)


- Log -----------------------------------------------------------------
commit 82e1fc1bc06a87278b2dada07e40a4296e6898c7
Author: Pauli <paul.dale at oracle.com>
Date:   Tue Apr 7 15:50:02 2020 +1000

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

-----------------------------------------------------------------------

Summary of changes:
 doc/man3/OSSL_PARAM.pod | 6 ++++++
 include/openssl/core.h  | 6 ++++++
 2 files changed, 12 insertions(+)

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<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 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