Store: API for deletion - documentation

Reviewed-by: Richard Levitte <levitte@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/21901)

doc/man3/OSSL_STORE_open.pod

@@ -4,7 +4,7 @@
 
 OSSL_STORE_CTX, OSSL_STORE_post_process_info_fn,
 OSSL_STORE_open, OSSL_STORE_open_ex,
-OSSL_STORE_ctrl, OSSL_STORE_load, OSSL_STORE_eof,
+OSSL_STORE_ctrl, OSSL_STORE_load, OSSL_STORE_eof, OSSL_STORE_delete,
 OSSL_STORE_error, OSSL_STORE_close
 - Types and functions to read objects from a URI
 
@@ -30,6 +30,9 @@ OSSL_STORE_error, OSSL_STORE_close
 
  OSSL_STORE_INFO *OSSL_STORE_load(OSSL_STORE_CTX *ctx);
  int OSSL_STORE_eof(OSSL_STORE_CTX *ctx);
+ int OSSL_STORE_delete(const char *uri, OSSL_LIB_CTX *libctx, const char *propq,
+                       const UI_METHOD *ui_method, void *ui_data,
+                       const OSSL_PARAM params[]);
  int OSSL_STORE_error(OSSL_STORE_CTX *ctx);
  int OSSL_STORE_close(OSSL_STORE_CTX *ctx);
 
@@ -104,6 +107,8 @@ Any other value is an error.
 OSSL_STORE_load() takes a B<OSSL_STORE_CTX> and tries to load the next
 available object and return it wrapped with B<OSSL_STORE_INFO>.
 
+OSSL_STORE_delete() deletes the object identified by I<uri>.
+
 OSSL_STORE_eof() takes a B<OSSL_STORE_CTX> and checks if we've reached the end
 of data.
 
@@ -152,7 +157,8 @@ or an error occurred, 0 otherwise.
 OSSL_STORE_error() returns 1 if an error occurred in an OSSL_STORE_load() call,
 otherwise 0.
 
-OSSL_STORE_ctrl() and OSSL_STORE_close() returns 1 on success, or 0 on failure.
+OSSL_STORE_delete(), OSSL_STORE_ctrl() and OSSL_STORE_close() return 1 on
+success, or 0 on failure.
 
 =head1 SEE ALSO
 
@@ -161,6 +167,8 @@ L<passphrase-encoding(7)>
 
 =head1 HISTORY
 
+OSSL_STORE_delete() was added in OpenSSL 3.2.
+
 OSSL_STORE_open_ex() was added in OpenSSL 3.0.
 
 B<OSSL_STORE_CTX>, OSSL_STORE_post_process_info_fn(), OSSL_STORE_open(),
@@ -170,8 +178,6 @@ were added in OpenSSL 1.1.1.
 Handling of NULL I<ctx> argument for OSSL_STORE_close()
 was introduced in OpenSSL 1.1.1h.
 
-OSSL_STORE_open_ex() was added in OpenSSL 3.0.
-
 OSSL_STORE_ctrl() and OSSL_STORE_vctrl() were deprecated in OpenSSL 3.0.
 
 =head1 COPYRIGHT

doc/man7/provider-storemgmt.pod

@@ -28,6 +28,10 @@ provider-storemgmt - The OSSL_STORE library E<lt>-E<gt> provider functions
      (void *loaderctx, const void *objref, size_t objref_sz,
       OSSL_CALLBACK *export_cb, void *export_cbarg);
 
+ int OSSL_FUNC_store_delete(void *provctx, const char *uri,
+                    const OSSL_PARAM params[],
+                    OSSL_PASSPHRASE_CALLBACK *pw_cb, void *pw_cbarg);
+
 =head1 DESCRIPTION
 
 The STORE operation is the provider side of the L<ossl_store(7)> API.
@@ -70,6 +74,7 @@ in L<openssl-core_dispatch.h(7)>, as follows:
  OSSL_FUNC_store_eof                  OSSL_FUNC_STORE_EOF
  OSSL_FUNC_store_close                OSSL_FUNC_STORE_CLOSE
  OSSL_FUNC_store_export_object        OSSL_FUNC_STORE_EXPORT_OBJECT
+ OSSL_FUNC_store_delete               OSSL_FUNC_STORE_DELETE
 
 =head2 Functions
 
@@ -114,6 +119,11 @@ OSSL_FUNC_store_export_object() should export the object of size I<objref_sz>
 referenced by I<objref> as an L<OSSL_PARAM(3)> array and pass that to the
 I<export_cb> as well as the given I<export_cbarg>.
 
+OSSL_FUNC_store_delete() deletes the object identified by the I<uri>. The
+implementation is entirely responsible for the interpretation of the URI.  In
+case a passphrase needs to be prompted to remove an object, I<pw_cb> should be
+called.
+
 =head2 Load Parameters
 
 =over 4
@@ -186,6 +196,8 @@ L<provider(7)>
 
 The STORE interface was introduced in OpenSSL 3.0.
 
+OSSL_FUNC_store_delete() callback was added in OpenSSL 3.2
+
 =head1 COPYRIGHT
 
 Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved.