STORE: Deprecate legacy / ENGINE functions

Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/12587)

3 files changed, 23 insertions, 21 deletions

diff --git a/doc/man3/OSSL_STORE_LOADER.pod b/doc/man3/OSSL_STORE_LOADER.pod
index 4e25f79f9e..12e3748c47 100644
--- a/doc/man3/OSSL_STORE_LOADER.pod
+++ b/doc/man3/OSSL_STORE_LOADER.pod
@@ -52,8 +52,9 @@ unregister STORE loaders for different URI schemes
                                      void (*fn)(const char *name, void *data),
                                      void *data);
 
-Legacy functions, still present to support B<OSSL_STORE_LOADER>s provided
-by B<ENGINE>:
+Deprecated since OpenSSL 3.0, can be hidden entirely by defining
+B<OPENSSL_API_COMPAT> with a suitable version value, see
+L<openssl_user_macros(7)>:
 
  OSSL_STORE_LOADER *OSSL_STORE_LOADER_new(ENGINE *e, const char *scheme);
  const ENGINE *OSSL_STORE_LOADER_get0_engine(const OSSL_STORE_LOADER
@@ -146,11 +147,11 @@ I<data> as arguments.
 OSSL_STORE_LOADER_names_do_all() traverses all names for the given
 I<loader>, and calls I<fn> with each name and I<data>.
 
-=head2 Legacy Types and Functions
+=head2 Legacy Types and Functions (deprecated)
 
 These functions help applications and engines to create loaders for
-schemes they support.  These are all discouraged in favour of provider
-implementations, see L<provider-storemgmt(7)>.
+schemes they support.  These are all deprecated and discouraged in favour of
+provider implementations, see L<provider-storemgmt(7)>.
 
 B<OSSL_STORE_LOADER_CTX> is a type template, to be defined by each loader
 using C<struct ossl_store_loader_ctx_st { ... }>.
@@ -366,7 +367,7 @@ OSSL_STORE_LOADER_set_eof(), OSSL_STORE_LOADER_set_close(),
 OSSL_STORE_LOADER_free(), OSSL_STORE_register_loader(),
 OSSL_STORE_unregister_loader(), OSSL_STORE_open_fn(), OSSL_STORE_ctrl_fn(),
 OSSL_STORE_load_fn(), OSSL_STORE_eof_fn() and OSSL_STORE_close_fn()
-were added in OpenSSL 1.1.1.
+were added in OpenSSL 1.1.1, and became deprecated in OpenSSL 3.0.
 
 =head1 COPYRIGHT
 
diff --git a/doc/man3/OSSL_STORE_SEARCH.pod b/doc/man3/OSSL_STORE_SEARCH.pod
index 7dc84227f9..82ff05f9ef 100644
--- a/doc/man3/OSSL_STORE_SEARCH.pod
+++ b/doc/man3/OSSL_STORE_SEARCH.pod
@@ -139,27 +139,27 @@ OSSL_STORE_SEARCH_by_name(),
 OSSL_STORE_SEARCH_by_issuer_serial(),
 OSSL_STORE_SEARCH_by_key_fingerprint(),
 and OSSL_STORE_SEARCH_by_alias()
-return a B<OSSL_STORE_SEARCH> pointer on success, or B<NULL> on failure.
+return a B<OSSL_STORE_SEARCH> pointer on success, or NULL on failure.
 
 OSSL_STORE_SEARCH_get_type() returns the criterion type of the given
 B<OSSL_STORE_SEARCH>.
 There is no error value.
 
 OSSL_STORE_SEARCH_get0_name() returns a B<X509_NAME> pointer on success,
-or B<NULL> when the given B<OSSL_STORE_SEARCH> was of a different type.
+or NULL when the given B<OSSL_STORE_SEARCH> was of a different type.
 
 OSSL_STORE_SEARCH_get0_serial() returns a B<ASN1_INTEGER> pointer on success,
-or B<NULL> when the given B<OSSL_STORE_SEARCH> was of a different type.
+or NULL when the given B<OSSL_STORE_SEARCH> was of a different type.
 
 OSSL_STORE_SEARCH_get0_bytes() returns a B<const unsigned char> pointer and
-sets B<*length> to the strings length on success, or B<NULL> when the given
+sets I<*length> to the strings length on success, or NULL when the given
 B<OSSL_STORE_SEARCH> was of a different type.
 
 OSSL_STORE_SEARCH_get0_string() returns a B<const char> pointer on success,
-or B<NULL> when the given B<OSSL_STORE_SEARCH> was of a different type.
+or NULL when the given B<OSSL_STORE_SEARCH> was of a different type.
 
 OSSL_STORE_SEARCH_get0_digest() returns a B<const EVP_MD> pointer.
-B<NULL> is a valid value and means that the store loader default will
+NULL is a valid value and means that the store loader default will
 be used when applicable.
 
 =head1 SEE ALSO
diff --git a/doc/man3/OSSL_STORE_open.pod b/doc/man3/OSSL_STORE_open.pod
index 0f7bf9c0d3..4269dea20a 100644
--- a/doc/man3/OSSL_STORE_open.pod
+++ b/doc/man3/OSSL_STORE_open.pod
@@ -27,18 +27,23 @@ OSSL_STORE_error, OSSL_STORE_close
                              const UI_METHOD *ui_method, void *ui_data,
                              OSSL_STORE_post_process_info_fn post_process,
                              void *post_process_data);
- int OSSL_STORE_ctrl(OSSL_STORE_CTX *ctx, int cmd, ... /* args */);
+
  OSSL_STORE_INFO *OSSL_STORE_load(OSSL_STORE_CTX *ctx);
  int OSSL_STORE_eof(OSSL_STORE_CTX *ctx);
  int OSSL_STORE_error(OSSL_STORE_CTX *ctx);
  int OSSL_STORE_close(OSSL_STORE_CTX *ctx);
 
+Deprecated since OpenSSL 3.0, can be hidden entirely by defining
+B<OPENSSL_API_COMPAT> with a suitable version value, see
+L<openssl_user_macros(7)>:
+
+ int OSSL_STORE_ctrl(OSSL_STORE_CTX *ctx, int cmd, ... /* args */);
+
 =head1 DESCRIPTION
 
 These functions help the application to fetch supported objects (see
 L<OSSL_STORE_INFO(3)/SUPPORTED OBJECTS> for information on which those are)
-from a given URI (see L</SUPPORTED SCHEMES> for more information on
-the supported URI schemes).
+from a given URI.
 The general method to do so is to "open" the URI using OSSL_STORE_open(),
 read each available and supported object using OSSL_STORE_load() as long as
 OSSL_STORE_eof() hasn't been reached, and finish it off with OSSL_STORE_close().
@@ -110,12 +115,6 @@ by OSSL_STORE_open() and frees all other information that was stored in the
 B<OSSL_STORE_CTX>, as well as the B<OSSL_STORE_CTX> itself.
 If I<ctx> is NULL it does nothing.
 
-=head1 SUPPORTED SCHEMES
-
-The basic supported scheme is B<file:>.
-Any other scheme can be added dynamically, using
-OSSL_STORE_register_loader().
-
 =head1 NOTES
 
 A string without a scheme prefix (that is, a non-URI string) is
@@ -171,6 +170,8 @@ was introduced in OpenSSL 1.1.1h.
 
 OSSL_STORE_open_with_libctx() was added in OpenSSL 3.0.
 
+OSSL_STORE_ctrl() and OSSL_STORE_vctrl() were deprecated in OpenSSL 3.0.
+
 =head1 COPYRIGHT
 
 Copyright 2016-2020 The OpenSSL Project Authors. All Rights Reserved.