Remove the engine parameter from the provider MAC documentations

[openssl.git] / doc / man7 / provider-mac.pod

diff --git a/doc/man7/provider-mac.pod b/doc/man7/provider-mac.pod
index 65aa0124e504941474fc09b98e39ab582451fa5f..77feab6b9b2fc0bbf950fe713915e9a126cffe45 100644 (file)
--- a/doc/man7/provider-mac.pod
+++ b/doc/man7/provider-mac.pod
@@ -29,13 +29,13 @@ provider-mac - The mac library E<lt>-E<gt> provider functions
 
  /* MAC parameter descriptors */
  const OSSL_PARAM *OP_mac_get_params(void);
- const OSSL_PARAM *OP_mac_ctx_get_params(void);
- const OSSL_PARAM *OP_mac_ctx_set_params(void);
+ const OSSL_PARAM *OP_mac_get_ctx_params(void);
+ const OSSL_PARAM *OP_mac_set_ctx_params(void);
 
  /* MAC parameters */
  int OP_mac_get_params(OSSL_PARAM params[]);
- int OP_mac_ctx_get_params(void *mctx, OSSL_PARAM params[]);
- int OP_mac_ctx_set_params(void *mctx, const OSSL_PARAM params[]);
+ int OP_mac_get_ctx_params(void *mctx, OSSL_PARAM params[]);
+ int OP_mac_set_ctx_params(void *mctx, const OSSL_PARAM params[]);
 
 =head1 DESCRIPTION
 
@@ -74,8 +74,8 @@ macros in L<openssl-core_numbers.h(7)>, as follows:
  OP_mac_final                OSSL_FUNC_MAC_FINAL
 
  OP_mac_get_params           OSSL_FUNC_MAC_GET_PARAMS
- OP_mac_ctx_get_params       OSSL_FUNC_MAC_CTX_GET_PARAMS
- OP_mac_ctx_set_params       OSSL_FUNC_MAC_CTX_SET_PARAMS
+ OP_mac_get_ctx_params       OSSL_FUNC_MAC_GET_CTX_PARAMS
+ OP_mac_set_ctx_params       OSSL_FUNC_MAC_SET_CTX_PARAMS
 
  OP_mac_gettable_params      OSSL_FUNC_MAC_GETTABLE_PARAMS
  OP_mac_gettable_ctx_params  OSSL_FUNC_MAC_GETTABLE_CTX_PARAMS
@@ -132,18 +132,18 @@ these functions.
 OP_mac_get_params() gets details of parameter values associated with the
 provider algorithm and stores them in I<params>.
 
-OP_mac_ctx_set_params() sets mac parameters associated with the given
+OP_mac_set_ctx_params() sets mac parameters associated with the given
 provider side mac context I<mctx> to I<params>.
 Any parameter settings are additional to any that were previously set.
 
-OP_mac_ctx_get_params() gets details of currently set parameter values
+OP_mac_get_ctx_params() gets details of currently set parameter values
 associated with the given provider side mac context I<mctx> and stores them
 in I<params>.
 
 OP_mac_gettable_params(), OP_mac_gettable_ctx_params(), and
 OP_mac_settable_ctx_params() all return constant B<OSSL_PARAM> arrays
 as descriptors of the parameters that OP_mac_get_params(),
-OP_mac_ctx_get_params(), and OP_mac_ctx_set_params() can handle,
+OP_mac_get_ctx_params(), and OP_mac_set_ctx_params() can handle,
 respectively.
 
 Parameters currently recognised by built-in macs are as follows. Not all
@@ -178,27 +178,12 @@ Gets flags associated with the MAC.
 
 =for comment We need to investigate if this is the right approach
 
-=item B<OSSL_MAC_PARAM_ALGORITHM> (utf8 string)
-
-Sets the name of the underlying algorithm to be used.
-It must name a suitable algorithm for the MAC that's being used.
-
-=item B<OSSL_MAC_PARAM_MD> (utf8 string)
-
-=item B<OSSL_MAC_PARAM_DIGEST> (utf8 string)
-
 =item B<OSSL_MAC_PARAM_CIPHER> (utf8 string)
 
-These have the same meaning as B<OSSL_MAC_PARAM_ALGORITHM>, but specify
-the expected operation for the underlying algorithm.
-These are regarded as antiquated, but are kept for easier transition from
-legacy MAC implementations.
-
-=item B<OSSL_MAC_PARAM_ENGINE> (utf8 string)
+=item B<OSSL_MAC_PARAM_DIGEST> (utf8 string)
 
-Sets the name of an engine that implements the underlying algorithm.
-This must be given together with the algorithm naming parameter to be
-considered valid.
+Sets the name of the underlying cipher or digest to be used.
+It must name a suitable algorithm for the MAC that's being used.
 
 =item B<OSSL_MAC_PARAM_PROPERTIES> (utf8 string)
 
@@ -206,19 +191,13 @@ Sets the properties to be queried when trying to fetch the underlying algorithm.
 This must be given together with the algorithm naming parameter to be
 considered valid.
 
-Note that both this and B<OSSL_MAC_PARAM_ENGINE> can be given at the same time.
-If the underlying algorithm ends up being fetched from a provider, offered by
-and engine, or a built in legacy function depends on what is available.
-
 =item B<OSSL_MAC_PARAM_SIZE> (int)
 
-=item B<OSSL_MAC_PARAM_DIGESTSIZE> (int)
-
-=item B<OSSL_MAC_PARAM_OUTLEN> (int)
+Can be used to get the resulting MAC size.
 
-All three names are considered the same.
-B<OSSL_MAC_PARAM_SIZE> and B<OSSL_MAC_PARAM_DIGESTSIZE> are considered
-antiquated, but are kept for easier transition from legacy MAC implementations.
+With some MAC algorithms, it can also be used to set the size that the
+resulting MAC should have.
+Allowable sizes are decided within each implementation.
 
 =back
 
@@ -228,7 +207,7 @@ OP_mac_newctx() and OP_mac_dupctx() should return the newly created
 provider side mac context, or NULL on failure.
 
 OP_mac_init(), OP_mac_update(), OP_mac_final(), OP_mac_get_params(),
-OP_mac_ctx_get_params() and OP_mac_ctx_set_params() should return 1 for
+OP_mac_get_ctx_params() and OP_mac_set_ctx_params() should return 1 for
 success or 0 on error.
 
 OP_mac_gettable_params(), OP_mac_gettable_ctx_params() and