From f49a65d09c09b3309b711518664b8ee973ec4b96 Mon Sep 17 00:00:00 2001
From: Pauli <paul.dale@oracle.com>
Date: Wed, 25 Sep 2019 20:27:36 +1000
Subject: [PATCH] Use OSSL_PARAM types for MAC documentation

Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/10011)
---
 doc/man7/EVP_MAC-BLAKE2.pod   | 3 ++-
 doc/man7/EVP_MAC-CMAC.pod     | 7 ++++---
 doc/man7/EVP_MAC-GMAC.pod     | 7 ++++---
 doc/man7/EVP_MAC-HMAC.pod     | 9 +++++----
 doc/man7/EVP_MAC-KMAC.pod     | 3 ++-
 doc/man7/EVP_MAC-Poly1305.pod | 3 ++-
 doc/man7/EVP_MAC-Siphash.pod  | 3 ++-
 7 files changed, 21 insertions(+), 14 deletions(-)

diff --git a/doc/man7/EVP_MAC-BLAKE2.pod b/doc/man7/EVP_MAC-BLAKE2.pod
index 21be5223c9..15df9ce0cf 100644
--- a/doc/man7/EVP_MAC-BLAKE2.pod
+++ b/doc/man7/EVP_MAC-BLAKE2.pod
@@ -30,6 +30,7 @@ L<EVP_MAC(3)/PARAMETERS>.
 All these parameters can be set with EVP_MAC_CTX_set_params().
 Furthermore, the "size" parameter can be retrieved with
 EVP_MAC_CTX_get_params(), or with EVP_MAC_size().
+The length of the "size" parameter should not exceed that of a B<size_t>.
 
 =over 4
 
@@ -50,7 +51,7 @@ This is an optional value of at most 16 bytes for BLAKE2BMAC or 8 for
 BLAKE2SMAC.
 It is empty by default.
 
-=item B<OSSL_MAC_PARAM_SIZE> ("size") <size_t>
+=item B<OSSL_MAC_PARAM_SIZE> ("size") <unsigned integer>
 
 When set, this can be any number between between 1 and 32 for
 EVP_MAC_BLAKE2S or 64 for EVP_MAC_BLAKE2B.
diff --git a/doc/man7/EVP_MAC-CMAC.pod b/doc/man7/EVP_MAC-CMAC.pod
index 0b30c93735..75950617db 100644
--- a/doc/man7/EVP_MAC-CMAC.pod
+++ b/doc/man7/EVP_MAC-CMAC.pod
@@ -30,9 +30,9 @@ The following parameter can be set with EVP_MAC_CTX_set_params():
 
 =item B<OSSL_MAC_PARAM_KEY> ("key") <octet string>
 
-=item B<OSSL_MAC_PARAM_CIPHER> ("cipher") <utf8 string>
+=item B<OSSL_MAC_PARAM_CIPHER> ("cipher") <UTF8 string>
 
-=item B<OSSL_MAC_PARAM_PROPERTIES> ("properties") <utf8 string>
+=item B<OSSL_MAC_PARAM_PROPERTIES> ("properties") <UTF8 string>
 
 =back
 
@@ -41,11 +41,12 @@ EVP_MAC_CTX_get_params():
 
 =over 4
 
-=item B<OSSL_MAC_PARAM_SIZE> ("size") <unsigned int>
+=item B<OSSL_MAC_PARAM_SIZE> ("size") <unsigned integer>
 
 =back
 
 The "size" parameter can also be retrieved with with EVP_MAC_size().
+The length of the "size" parameter is equal to that of an B<unsigned int>.
 
 =head1 SEE ALSO
 
diff --git a/doc/man7/EVP_MAC-GMAC.pod b/doc/man7/EVP_MAC-GMAC.pod
index 79aaaa5b24..114322b97c 100644
--- a/doc/man7/EVP_MAC-GMAC.pod
+++ b/doc/man7/EVP_MAC-GMAC.pod
@@ -32,9 +32,9 @@ The following parameter can be set with EVP_MAC_CTX_set_params():
 
 =item B<OSSL_MAC_PARAM_IV> ("iv") <octet string>
 
-=item B<OSSL_MAC_PARAM_CIPHER> ("cipher") <utf8 string>
+=item B<OSSL_MAC_PARAM_CIPHER> ("cipher") <UTF8 string>
 
-=item B<OSSL_MAC_PARAM_PROPERTIES> ("properties") <utf8 string>
+=item B<OSSL_MAC_PARAM_PROPERTIES> ("properties") <UTF8 string>
 
 =back
 
@@ -43,11 +43,12 @@ EVP_MAC_CTX_get_params():
 
 =over 4
 
-=item B<OSSL_MAC_PARAM_SIZE> ("size") <unsigned int>
+=item B<OSSL_MAC_PARAM_SIZE> ("size") <unsigned integer>
 
 =back
 
 The "size" parameter can also be retrieved with EVP_MAC_size().
+The length of the "size" parameter is equal to that of an B<unsigned int>.
 
 =head1 SEE ALSO
 
diff --git a/doc/man7/EVP_MAC-HMAC.pod b/doc/man7/EVP_MAC-HMAC.pod
index 3ca2909d03..1b983b2339 100644
--- a/doc/man7/EVP_MAC-HMAC.pod
+++ b/doc/man7/EVP_MAC-HMAC.pod
@@ -32,24 +32,25 @@ The following parameter can be set with EVP_MAC_CTX_set_params():
 
 =item B<OSSL_MAC_PARAM_FLAGS> ("flags") <octet string>
 
-=item B<OSSL_MAC_PARAM_DIGEST> ("digest") <utf8 string>
+=item B<OSSL_MAC_PARAM_DIGEST> ("digest") <UTF8 string>
 
-=item B<OSSL_MAC_PARAM_PROPERTIES> ("properties") <utf8 string>
+=item B<OSSL_MAC_PARAM_PROPERTIES> ("properties") <UTF8 string>
 
 =back
 
 The "flags" parameter is passed directly to HMAC_CTX_set_flags().
 
-The following parameters can be retrieved with
+The following parameter can be retrieved with
 EVP_MAC_CTX_get_params():
 
 =over 4
 
-=item B<OSSL_MAC_PARAM_SIZE> ("size") <unsigned int>
+=item B<OSSL_MAC_PARAM_SIZE> ("size") <unsigned integer>
 
 =back
 
 The "size" parameter can also be retrieved with EVP_MAC_size().
+The length of the "size" parameter is equal to that of an B<unsigned int>.
 
 =head1 SEE ALSO
 
diff --git a/doc/man7/EVP_MAC-KMAC.pod b/doc/man7/EVP_MAC-KMAC.pod
index d241414428..0aec63100b 100644
--- a/doc/man7/EVP_MAC-KMAC.pod
+++ b/doc/man7/EVP_MAC-KMAC.pod
@@ -30,6 +30,7 @@ L<EVP_MAC(3)/PARAMETERS>.
 All these parameters can be set with EVP_MAC_CTX_set_params().
 Furthermore, the "size" parameter can be retrieved with
 EVP_MAC_CTX_get_params(), or with EVP_MAC_size().
+The length of the "size" parameter should not exceed that of a B<size_t>.
 
 =over 4
 
@@ -37,7 +38,7 @@ EVP_MAC_CTX_get_params(), or with EVP_MAC_size().
 
 =item B<OSSL_MAC_PARAM_CUSTOM> ("custom") <octet string>
 
-=item B<OSSL_MAC_PARAM_SIZE> ("size") <size_t>
+=item B<OSSL_MAC_PARAM_SIZE> ("size") <unsigned integer>
 
 =item B<OSSL_MAC_PARAM_XOF>
 
diff --git a/doc/man7/EVP_MAC-Poly1305.pod b/doc/man7/EVP_MAC-Poly1305.pod
index 5f606d66b2..6e3bf02b3c 100644
--- a/doc/man7/EVP_MAC-Poly1305.pod
+++ b/doc/man7/EVP_MAC-Poly1305.pod
@@ -37,11 +37,12 @@ EVP_MAC_CTX_get_params():
 
 =over 4
 
-=item B<OSSL_MAC_PARAM_SIZE> ("size") <unsigned int>
+=item B<OSSL_MAC_PARAM_SIZE> ("size") <unsigned integer>
 
 =back
 
 The "size" parameter can also be retrieved with with EVP_MAC_size().
+The length of the "size" parameter should not exceed that of an B<unsigned int>.
 
 =head1 SEE ALSO
 
diff --git a/doc/man7/EVP_MAC-Siphash.pod b/doc/man7/EVP_MAC-Siphash.pod
index f82a668851..7738cc0017 100644
--- a/doc/man7/EVP_MAC-Siphash.pod
+++ b/doc/man7/EVP_MAC-Siphash.pod
@@ -28,12 +28,13 @@ L<EVP_MAC(3)/PARAMETERS>.
 All these parameters can be set with EVP_MAC_CTX_set_params().
 Furthermore, the "size" parameter can be retrieved with
 EVP_MAC_CTX_get_params(), or with EVP_MAC_size().
+The length of the "size" parameter should not exceed that of a B<size_t>.
 
 =over 4
 
 =item B<OSSL_MAC_PARAM_KEY> ("key") <octet string>
 
-=item B<OSSL_MAC_PARAM_SIZE> ("size") <size_t>
+=item B<OSSL_MAC_PARAM_SIZE> ("size") <unsigned integer>
 
 =back
 
-- 
2.25.1