From b5b91a79633dbecb6f4d74d469ea28748ba606d7 Mon Sep 17 00:00:00 2001
From: Richard Levitte <levitte@openssl.org>
Date: Sat, 7 Mar 2020 07:51:27 +0100
Subject: [PATCH] DOCS: Add translation information for EVP_MD_CTX_ctrl()

EVP_MD_CTX_ctrl() translates some known control commands when faced
with a fetched EVP_MD, so we need to document it.

This also ensures that we don't drop the information on the "micalg"
parameter entirely.

Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/11270)
---
 doc/man3/EVP_DigestInit.pod | 20 +++++++++++++++++---
 1 file changed, 17 insertions(+), 3 deletions(-)

diff --git a/doc/man3/EVP_DigestInit.pod b/doc/man3/EVP_DigestInit.pod
index ef40ae49f8..94f751a659 100644
--- a/doc/man3/EVP_DigestInit.pod
+++ b/doc/man3/EVP_DigestInit.pod
@@ -142,14 +142,22 @@ Cleans up digest context B<ctx> and frees up the space allocated to it.
 
 =item EVP_MD_CTX_ctrl()
 
-This is a legacy method. EVP_MD_CTX_set_params() and EVP_MD_CTX_get_params()
+I<This is a legacy method. EVP_MD_CTX_set_params() and EVP_MD_CTX_get_params()
 is the mechanism that should be used to set and get parameters that are used by
-providers.
+providers.>
+
 Performs digest-specific control actions on context B<ctx>. The control command
 is indicated in B<cmd> and any additional arguments in B<p1> and B<p2>.
 EVP_MD_CTX_ctrl() must be called after EVP_DigestInit_ex(). Other restrictions
 may apply depending on the control type and digest implementation.
-See L</CONTROLS> below for more information.
+
+If this function happens to be used with a fetched B<EVP_MD>, it will
+translate the controls that are known to OpenSSL into L<OSSL_PARAM(3)>
+parameters with keys defined by OpenSSL and call EVP_MD_CTX_get_params() or
+EVP_MD_CTX_set_params() as is appropriate for each control command.
+
+See L</CONTROLS> below for more information, including what translations are
+being done.
 
 =item EVP_MD_get_params()
 
@@ -411,6 +419,9 @@ Gets the digest Message Integrity Check algorithm string. This is used when
 creating S/MIME multipart/signed messages, as specified in RFC 3851.
 The string value is written to B<p2>.
 
+When used with a fetched B<EVP_MD>, EVP_MD_CTX_get_params() gets called with
+an L<OSSL_PARAM(3)> item with the key "micalg" (B<OSSL_DIGEST_PARAM_MICALG>).
+
 =item EVP_MD_CTRL_XOF_LEN
 
 This control sets the digest length for extendable output functions to B<p1>.
@@ -418,6 +429,9 @@ Sending this control directly should not be necessary, the use of
 C<EVP_DigestFinalXOF()> is preferred.
 Currently used by SHAKE.
 
+When used with a fetched B<EVP_MD>, EVP_MD_CTX_get_params() gets called with
+an L<OSSL_PARAM(3)> item with the key "xoflen" (B<OSSL_DIGEST_PARAM_XOFLEN>).
+
 =back
 
 =head1 FLAGS
-- 
2.25.1