Add X509_NAME_hash_ex() to be able to check if it failed due to unsupported SHA1

[openssl.git] / doc / man3 / OSSL_STORE_INFO.pod

diff --git a/doc/man3/OSSL_STORE_INFO.pod b/doc/man3/OSSL_STORE_INFO.pod
index bc965a77bdeb483aacefc2881501785b89fcd91b..8c811ec1f31d20d6ae3f7c7a69f2e1f9aa46bf90 100644 (file)
--- a/doc/man3/OSSL_STORE_INFO.pod
+++ b/doc/man3/OSSL_STORE_INFO.pod
@@ -12,7 +12,8 @@ OSSL_STORE_INFO_get1_PKEY, OSSL_STORE_INFO_get1_CERT, OSSL_STORE_INFO_get1_CRL,
 OSSL_STORE_INFO_type_string, OSSL_STORE_INFO_free,
 OSSL_STORE_INFO_new_NAME, OSSL_STORE_INFO_set0_NAME_description,
 OSSL_STORE_INFO_new_PARAMS, OSSL_STORE_INFO_new_PUBKEY,
-OSSL_STORE_INFO_new_PKEY, OSSL_STORE_INFO_new_CERT, OSSL_STORE_INFO_new_CRL
+OSSL_STORE_INFO_new_PKEY, OSSL_STORE_INFO_new_CERT, OSSL_STORE_INFO_new_CRL,
+OSSL_STORE_INFO_new, OSSL_STORE_INFO_get0_data
 - Functions to manipulate OSSL_STORE_INFO objects
 
 =head1 SYNOPSIS
@@ -50,6 +51,9 @@ OSSL_STORE_INFO_new_PKEY, OSSL_STORE_INFO_new_CERT, OSSL_STORE_INFO_new_CRL
  OSSL_STORE_INFO *OSSL_STORE_INFO_new_CERT(X509 *x509);
  OSSL_STORE_INFO *OSSL_STORE_INFO_new_CRL(X509_CRL *crl);
 
+ OSSL_STORE_INFO *OSSL_STORE_INFO_new(int type, void *data);
+ void *OSSL_STORE_INFO_get0_data(int type, const OSSL_STORE_INFO *info);
+
 =head1 DESCRIPTION
 
 These functions are primarily useful for applications to retrieve
@@ -110,6 +114,19 @@ description.
 This description is meant to be human readable and should be used for
 information printout.
 
+OSSL_STORE_INFO_new() creates a B<OSSL_STORE_INFO> with an arbitrary I<type>
+number and I<data> structure.  It's the responsibility of the caller to
+define type numbers other than the ones defined by F<< <openssl/store.h> >>,
+and to handle freeing the associated data structure on their own.
+I<Using type numbers that are defined by F<< <openssl/store.h> >> may cause
+undefined behaviours, including crashes>.
+
+OSSL_STORE_INFO_get0_data() returns the data pointer that was passed to
+OSSL_STORE_INFO_new() if I<type> matches the type number in I<info>.
+
+OSSL_STORE_INFO_new() and OSSL_STORE_INFO_get0_data() may be useful for
+applications that define their own STORE data, but must be used with care.
+
 =head1 SUPPORTED OBJECTS
 
 Currently supported object types are:
@@ -177,13 +194,13 @@ OSSL_STORE_INFO_get1_PARAMS(), OSSL_STORE_INFO_get1_PKEY(),
 OSSL_STORE_INFO_get1_CERT() and OSSL_STORE_INFO_get1_CRL() all return
 a pointer to a duplicate of the OpenSSL object on success, NULL otherwise.
 
-OSSL_STORE_INFO_type_string() returns a string on success, or B<NULL> on
+OSSL_STORE_INFO_type_string() returns a string on success, or NULL on
 failure.
 
 OSSL_STORE_INFO_new_NAME(), OSSL_STORE_INFO_new_PARAMS(),
 OSSL_STORE_INFO_new_PKEY(), OSSL_STORE_INFO_new_CERT() and
 OSSL_STORE_INFO_new_CRL() return a B<OSSL_STORE_INFO>
-pointer on success, or B<NULL> on failure.
+pointer on success, or NULL on failure.
 
 OSSL_STORE_INFO_set0_NAME_description() returns 1 on success, or 0 on
 failure.