Rework the documentation of our individual MAC implementations
authorRichard Levitte <levitte@openssl.org>
Wed, 28 Aug 2019 07:13:21 +0000 (09:13 +0200)
committerRichard Levitte <levitte@openssl.org>
Mon, 2 Sep 2019 05:21:58 +0000 (07:21 +0200)
We now describe parameters instead of controls.

Also, since macros like EVP_MAC_CMAC do not exist any more, we rename
the pod files from EVP_MAC_{algo}.pod to EVP_MAC-{algo}.pod.  This
allows getting the documentation like this:

    man EVP_MAC CMAC

[skip ci]
Fixes #9709

Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/9713)

15 files changed:
doc/man3/EVP_MAC.pod
doc/man7/EVP_MAC-BLAKE2.pod [new file with mode: 0644]
doc/man7/EVP_MAC-CMAC.pod [new file with mode: 0644]
doc/man7/EVP_MAC-GMAC.pod [new file with mode: 0644]
doc/man7/EVP_MAC-HMAC.pod [new file with mode: 0644]
doc/man7/EVP_MAC-KMAC.pod [new file with mode: 0644]
doc/man7/EVP_MAC-Poly1305.pod [new file with mode: 0644]
doc/man7/EVP_MAC-Siphash.pod [new file with mode: 0644]
doc/man7/EVP_MAC_BLAKE2.pod [deleted file]
doc/man7/EVP_MAC_CMAC.pod [deleted file]
doc/man7/EVP_MAC_GMAC.pod [deleted file]
doc/man7/EVP_MAC_HMAC.pod [deleted file]
doc/man7/EVP_MAC_KMAC.pod [deleted file]
doc/man7/EVP_MAC_POLY1305.pod [deleted file]
doc/man7/EVP_MAC_SIPHASH.pod [deleted file]

index 5fa498a..6daa82d 100644 (file)
@@ -167,49 +167,56 @@ and the given I<arg> as argument.
 
 =head1 PARAMETER NAMES
 
+Parameters are identified by name as strings, and have an expected
+data type and maximum size.
+OpenSSL has a set of macros for parameter names it expects to see in
+its own MAC implementations.
+Here, we show all three, the OpenSSL macro for the parameter name, the
+name in string form, and a type description.
+
 The standard parameter names are:
 
 =over 4
 
-=item OSSL_MAC_PARAM_KEY ("key") <octet string>
+=item B<OSSL_MAC_PARAM_KEY> ("key") <octet string>
 
 Its value is the MAC key as an array of bytes.
 
 For MACs that use an underlying computation algorithm, the algorithm
 must be set first, see parameter names "algorithm" below.
 
-=item OSSL_MAC_PARAM_IV ("iv") <octet string>
+=item B<OSSL_MAC_PARAM_IV> ("iv") <octet string>
 
 Some MAC implementations require an IV, this parameter sets the IV.
 
-=item OSSL_MAC_PARAM_CUSTOM ("custom") <octet string>
+=item B<OSSL_MAC_PARAM_CUSTOM> ("custom") <octet string>
 
 Some MAC implementations (KMAC, BLAKE2) accept a Customization String,
 this parameter sets the Customization String. The default value is the
 empty string.
 
-=item OSSL_MAC_PARAM_SALT ("salt") <octet string>
+=item B<OSSL_MAC_PARAM_SALT> ("salt") <octet string>
 
 This option is used by BLAKE2 MAC.
 
-=item OSSL_MAC_PARAM_XOF ("xof") <int>
+=item B<OSSL_MAC_PARAM_XOF> ("xof") <int>
 
 It's a simple flag, the value 0 or 1 are expected.
 
 This option is used by KMAC.
 
-=item OSSL_MAC_PARAM_FLAGS ("flags") <int>
+=item B<OSSL_MAC_PARAM_FLAGS> ("flags") <int>
 
 These will set the MAC flags to the given numbers.
 Some MACs do not support this option.
 
-=item OSSL_MAC_PARAM_ENGINE ("engine") <utf8string>
+=item B<OSSL_MAC_PARAM_ENGINE> ("engine") <utf8string>
 
-=item OSSL_MAC_PARAM_PROPERTIES ("properties") <utf8string>
+=item B<OSSL_MAC_PARAM_PROPERTIES> ("properties") <utf8string>
 
-=item OSSL_MAC_PARAM_DIGEST ("digest") <utf8string>
+=item B<OSSL_MAC_PARAM_DIGEST> ("digest") <utf8string>
 
-=item OSSL_MAC_PARAM_CIPHER ("cipher") <utf8string>
+=item B<OSSL_MAC_PARAM_CIPHER> ("cipher") <utf8string>
 
 For MAC implementations that use an underlying computation cipher or
 digest, these parameters set what the algorithm should be, and the
@@ -223,7 +230,7 @@ Note that not all algorithms may support all digests.
 HMAC does not support variable output length digests such as SHAKE128
 or SHAKE256.
 
-=item OSSL_MAC_PARAM_SIZE <unsigned int>
+=item B<OSSL_MAC_PARAM_SIZE> ("size") <unsigned int>
 
 For MAC implementations that support it, set the output size that
 EVP_MAC_final() should produce.
diff --git a/doc/man7/EVP_MAC-BLAKE2.pod b/doc/man7/EVP_MAC-BLAKE2.pod
new file mode 100644 (file)
index 0000000..6ceb65d
--- /dev/null
@@ -0,0 +1,79 @@
+=pod
+
+=head1 NAME
+
+EVP_MAC-BLAKE2, EVP_MAC-BLAKE2BMAC, EVP_MAC-BLAKE2SMAC
+- The BLAKE2 EVP_MAC implementations
+
+=head1 DESCRIPTION
+
+Support for computing BLAKE2 MACs through the B<EVP_MAC> API.
+
+=head2 Identity
+
+These implementations are identified with one of these names and
+properties, to be used with EVP_MAC_fetch():
+
+=over 4
+
+=item "BLAKE2BMAC", "default=yes"
+
+=item "BLAKE2SMAC", "default=yes"
+
+=back
+
+=head2 Supported parameters
+
+The general description of these parameters can be found in
+L<EVP_MAC(3)/PARAMETER NAMES>.
+
+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().
+
+=over 4
+
+=item B<OSSL_MAC_PARAM_KEY> ("key") <octet string>
+
+This may be at most 64 bytes for BLAKE2BMAC or 32 for BLAKE2SMAC and
+at least 1 byte in both cases.
+
+=item B<OSSL_MAC_PARAM_CUSTOM> ("custom") <octet string>
+
+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_SALT> ("salt") <octet string>
+
+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>
+
+When set, this can be any number between between 1 and 32 for
+EVP_MAC_BLAKE2S or 64 for EVP_MAC_BLAKE2B.
+It is 32 and 64 respectively by default.
+
+=back
+
+=head1 SEE ALSO
+
+L<EVP_MAC_CTX_get_params(3)>, L<EVP_MAC_CTX_set_params(3)>,
+L<EVP_MAC(3)/PARAMETER NAMES>, L<OSSL_PARAM(3)>
+
+=head1 HISTORY
+
+The macros and functions described here were added to OpenSSL 3.0.
+
+=head1 COPYRIGHT
+
+Copyright 2018-2019 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
diff --git a/doc/man7/EVP_MAC-CMAC.pod b/doc/man7/EVP_MAC-CMAC.pod
new file mode 100644 (file)
index 0000000..e7675e2
--- /dev/null
@@ -0,0 +1,66 @@
+=pod
+
+=head1 NAME
+
+EVP_MAC-CMAC - The CMAC EVP_MAC implementation
+
+=head1 DESCRIPTION
+
+Support for computing CMAC MACs through the B<EVP_MAC> API.
+
+=head2 Identity
+
+This implementation is identified with this name and properties, to be
+used with EVP_MAC_fetch():
+
+=over 4
+
+=item "CMAC", "default=yes"
+
+=back
+
+=head2 Supported parameters
+
+The general description of these parameters can be found in
+L<EVP_MAC(3)/PARAMETER NAMES>.
+
+The following parameter can be set with EVP_MAC_CTX_set_params():
+
+=over 4
+
+=item B<OSSL_MAC_PARAM_KEY> ("key") <octet string>
+
+=item B<OSSL_MAC_PARAM_ENGINE> ("engine") <utf8 string>
+
+=item B<OSSL_MAC_PARAM_CIPHER> ("cipher") <utf8 string>
+
+=item B<OSSL_MAC_PARAM_PROPERTIES> ("properties") <utf8 string>
+
+=back
+
+The following parameters can be retrieved with
+EVP_MAC_CTX_get_params():
+
+=over 4
+
+=item B<OSSL_MAC_PARAM_SIZE> ("size") <unsigned int>
+
+=back
+
+The "size" parameter can also be retrieved with with EVP_MAC_size().
+
+=head1 SEE ALSO
+
+L<EVP_MAC_CTX_get_params(3)>, L<EVP_MAC_CTX_set_params(3)>,
+L<EVP_MAC(3)/PARAMETER NAMES>, L<OSSL_PARAM(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2018-2019 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
diff --git a/doc/man7/EVP_MAC-GMAC.pod b/doc/man7/EVP_MAC-GMAC.pod
new file mode 100644 (file)
index 0000000..fcd9c96
--- /dev/null
@@ -0,0 +1,68 @@
+=pod
+
+=head1 NAME
+
+EVP_MAC-GMAC - The GMAC EVP_MAC implementation
+
+=head1 DESCRIPTION
+
+Support for computing GMAC MACs through the B<EVP_MAC> API.
+
+=head2 Identity
+
+This implementation is identified with this name and properties, to be
+used with EVP_MAC_fetch():
+
+=over 4
+
+=item "GMAC", "default=yes"
+
+=back
+
+=head2 Supported parameters
+
+The general description of these parameters can be found in
+L<EVP_MAC(3)/PARAMETER NAMES>.
+
+The following parameter can be set with EVP_MAC_CTX_set_params():
+
+=over 4
+
+=item B<OSSL_MAC_PARAM_KEY> ("key") <octet string>
+
+=item B<OSSL_MAC_PARAM_IV> ("iv") <octet string>
+
+=item B<OSSL_MAC_PARAM_ENGINE> ("engine") <utf8 string>
+
+=item B<OSSL_MAC_PARAM_CIPHER> ("cipher") <utf8 string>
+
+=item B<OSSL_MAC_PARAM_PROPERTIES> ("properties") <utf8 string>
+
+=back
+
+The following parameters can be retrieved with
+EVP_MAC_CTX_get_params():
+
+=over 4
+
+=item B<OSSL_MAC_PARAM_SIZE> ("size") <unsigned int>
+
+=back
+
+The "size" parameter can also be retrieved with EVP_MAC_size().
+
+=head1 SEE ALSO
+
+L<EVP_MAC_CTX_get_params(3)>, L<EVP_MAC_CTX_set_params(3)>,
+L<EVP_MAC(3)/PARAMETER NAMES>, L<OSSL_PARAM(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2018-2019 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
diff --git a/doc/man7/EVP_MAC-HMAC.pod b/doc/man7/EVP_MAC-HMAC.pod
new file mode 100644 (file)
index 0000000..0fb92d3
--- /dev/null
@@ -0,0 +1,70 @@
+=pod
+
+=head1 NAME
+
+EVP_MAC-HMAC - The HMAC EVP_MAC implementation
+
+=head1 DESCRIPTION
+
+Support for computing HMAC MACs through the B<EVP_MAC> API.
+
+=head2 Identity
+
+This implementation is identified with this name and properties, to be
+used with EVP_MAC_fetch():
+
+=over 4
+
+=item "HMAC", "default=yes"
+
+=back
+
+=head2 Supported parameters
+
+The general description of these parameters can be found in
+L<EVP_MAC(3)/PARAMETER NAMES>.
+
+The following parameter can be set with EVP_MAC_CTX_set_params():
+
+=over 4
+
+=item B<OSSL_MAC_PARAM_KEY> ("key") <octet string>
+
+=item B<OSSL_MAC_PARAM_FLAGS> ("flags") <octet string>
+
+=item B<OSSL_MAC_PARAM_ENGINE> ("engine") <utf8 string>
+
+=item B<OSSL_MAC_PARAM_DIGEST> ("digest") <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
+EVP_MAC_CTX_get_params():
+
+=over 4
+
+=item B<OSSL_MAC_PARAM_SIZE> ("size") <unsigned int>
+
+=back
+
+The "size" parameter can also be retrieved with EVP_MAC_size().
+
+=head1 SEE ALSO
+
+L<EVP_MAC_CTX_get_params(3)>, L<EVP_MAC_CTX_set_params(3)>,
+L<EVP_MAC(3)/PARAMETER NAMES>, L<OSSL_PARAM(3)>, L<HMAC(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2018-2019 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
diff --git a/doc/man7/EVP_MAC-KMAC.pod b/doc/man7/EVP_MAC-KMAC.pod
new file mode 100644 (file)
index 0000000..71a3bf2
--- /dev/null
@@ -0,0 +1,64 @@
+=pod
+
+=head1 NAME
+
+EVP_MAC-KMAC, EVP_MAC-KMAC256, EVP_MAC-KMAC256
+- The KMAC EVP_MAC implementations
+
+=head1 DESCRIPTION
+
+Support for computing KMAC MACs through the B<EVP_MAC> API.
+
+=head2 Identity
+
+These implementations are identified with one of these names and
+properties, to be used with EVP_MAC_fetch():
+
+=over 4
+
+=item "KMAC128", "default=yes"
+
+=item "KMAC256", "default=yes"
+
+=back
+
+=head2 Supported parameters
+
+The general description of these parameters can be found in
+L<EVP_MAC(3)/PARAMETER NAMES>.
+
+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().
+
+=over 4
+
+=item B<OSSL_MAC_PARAM_KEY> ("key") <octet string>
+
+=item B<OSSL_MAC_PARAM_CUSTOM> ("custom") <octet string>
+
+=item B<OSSL_MAC_PARAM_SIZE> ("size") <size_t>
+
+=item B<OSSL_MAC_PARAM_XOF>
+
+=back
+
+The "xof" parameter value is exptect to be 1 or 0. Use 1 to enable XOF
+mode. If XOF is enabled then the output len that is encoded as part of
+the input stream is set to zero.
+
+=head1 SEE ALSO
+
+L<EVP_MAC_CTX_get_params(3)>, L<EVP_MAC_CTX_set_params(3)>,
+L<EVP_MAC(3)/PARAMETER NAMES>, L<OSSL_PARAM(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2018-2019 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
diff --git a/doc/man7/EVP_MAC-Poly1305.pod b/doc/man7/EVP_MAC-Poly1305.pod
new file mode 100644 (file)
index 0000000..02cbe0e
--- /dev/null
@@ -0,0 +1,60 @@
+=pod
+
+=head1 NAME
+
+EVP_MAC-Poly1305 - The Poly1305 EVP_MAC implementation
+
+=head1 DESCRIPTION
+
+Support for computing Poly1305 MACs through the B<EVP_MAC> API.
+
+=head2 Identity
+
+This implementation is identified with this name and properties, to be
+used with EVP_MAC_fetch():
+
+=over 4
+
+=item "Poly1305", "default=yes"
+
+=back
+
+=head2 Supported parameters
+
+The general description of these parameters can be found in
+L<EVP_MAC(3)/PARAMETER NAMES>.
+
+The following parameter can be set with EVP_MAC_CTX_set_params():
+
+=over 4
+
+=item B<OSSL_MAC_PARAM_KEY> ("key") <octet string>
+
+=back
+
+The following parameters can be retrieved with
+EVP_MAC_CTX_get_params():
+
+=over 4
+
+=item B<OSSL_MAC_PARAM_SIZE> ("size") <unsigned int>
+
+=back
+
+The "size" parameter can also be retrieved with with EVP_MAC_size().
+
+=head1 SEE ALSO
+
+L<EVP_MAC_CTX_get_params(3)>, L<EVP_MAC_CTX_set_params(3)>,
+L<EVP_MAC(3)/PARAMETER NAMES>, L<OSSL_PARAM(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2018-2019 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
diff --git a/doc/man7/EVP_MAC-Siphash.pod b/doc/man7/EVP_MAC-Siphash.pod
new file mode 100644 (file)
index 0000000..25e0a8f
--- /dev/null
@@ -0,0 +1,54 @@
+=pod
+
+=head1 NAME
+
+EVP_MAC-Siphash - The SipHash EVP_MAC implementation
+
+=head1 DESCRIPTION
+
+Support for computing SipHash MACs through the B<EVP_MAC> API.
+
+=head2 Identity
+
+This implementation is identified with this name and properties, to be
+used with EVP_MAC_fetch():
+
+=over 4
+
+=item "Siphash", "default=yes"
+
+=back
+
+
+=head2 Supported parameters
+
+The general description of these parameters can be found in
+L<EVP_MAC(3)/PARAMETER NAMES>.
+
+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().
+
+=over 4
+
+=item B<OSSL_MAC_PARAM_KEY> ("key") <octet string>
+
+=item B<OSSL_MAC_PARAM_SIZE> ("size") <size_t>
+
+=back
+
+=head1 SEE ALSO
+
+L<EVP_MAC_CTX_get_params(3)>, L<EVP_MAC_CTX_set_params(3)>,
+L<EVP_MAC(3)/PARAMETER NAMES>, L<OSSL_PARAM(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2018-2019 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
diff --git a/doc/man7/EVP_MAC_BLAKE2.pod b/doc/man7/EVP_MAC_BLAKE2.pod
deleted file mode 100644 (file)
index 2fc8051..0000000
+++ /dev/null
@@ -1,114 +0,0 @@
-=pod
-
-=head1 NAME
-
-EVP_MAC_BLAKE2 - The BLAKE2 EVP_MAC implementation
-
-=head1 DESCRIPTION
-
-Support for computing BLAKE2 MACs through the B<EVP_MAC> API.
-
-=head2 Numeric identity
-
-B<EVP_MAC_BLAKE2B> and B<EVP_MAC_BLAKE2S> are the numeric identities for this
-implementation, and can be used in functions like EVP_MAC_CTX_new_id() and
-EVP_get_macbynid().
-
-=head2 Supported controls
-
-The supported controls are:
-
-=over 4
-
-=item B<EVP_MAC_CTRL_SET_KEY>
-
-This is a string value of at most 64 bytes for EVP_MAC_BLAKE2B
-or 32 for EVP_MAC_BLAKE2S and at least 1 byte in both cases.
-This must be set before calling EVP_MAC_init().
-
-EVP_MAC_ctrl_str() takes two type strings for this control:
-
-=over 4
-
-=item "key"
-
-The value string is used as is.
-
-=item "hexkey"
-
-The value string is expected to be a hexadecimal number, which will be
-decoded before passing on as control value.
-
-=back
-
-=item B<EVP_MAC_CTRL_SET_CUSTOM>
-
-This is an optional string value of at most 16 bytes for EVP_MAC_BLAKE2B
-or 8 for EVP_MAC_BLAKE2S, set to all-NULL by default.
-If used this must be set before calling EVP_MAC_init().
-
-EVP_MAC_ctrl_str() takes two type strings for this control:
-
-=over 4
-
-=item "custom"
-
-The value string is used as is.
-
-=item "hexcustom"
-
-The value string is expected to be a hexadecimal number, which will be
-decoded before passing on as control value.
-
-=back
-
-=item B<EVP_MAC_CTRL_SET_SALT>
-
-This is an optional string value of at most 16 bytes for EVP_MAC_BLAKE2B
-or 8 for EVP_MAC_BLAKE2S, set to all-NULL by default.
-If used this must be set before calling EVP_MAC_init().
-
-EVP_MAC_ctrl_str() takes two type strings for this control:
-
-=over 4
-
-=item "salt"
-
-The value string is used as is.
-
-=item "hexsalt"
-
-The value string is expected to be a hexadecimal number, which will be
-decoded before passing on as control value.
-
-=back
-
-=item B<EVP_MAC_CTRL_SET_SIZE>
-
-EVP_MAC_ctrl_str() type string: "outlen"
-
-This is an optional value string containing a decimal number between 1 and
-32 for EVP_MAC_BLAKE2S or 64 for EVP_MAC_BLAKE2B.
-If it is not set it uses the default digest size of 32 and 64 respectively.
-If used this must be set before calling EVP_MAC_init().
-
-=back
-
-=head1 SEE ALSO
-
-L<EVP_MAC_ctrl(3)>, L<EVP_MAC(3)/CONTROLS>
-
-=head1 HISTORY
-
-The macros and functions described here were added to OpenSSL 3.0.
-
-=head1 COPYRIGHT
-
-Copyright 2018 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the Apache License 2.0 (the "License").  You may not use
-this file except in compliance with the License.  You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
diff --git a/doc/man7/EVP_MAC_CMAC.pod b/doc/man7/EVP_MAC_CMAC.pod
deleted file mode 100644 (file)
index cda3f3f..0000000
+++ /dev/null
@@ -1,65 +0,0 @@
-=pod
-
-=head1 NAME
-
-EVP_MAC_CMAC - The CMAC EVP_MAC implementation
-
-=head1 DESCRIPTION
-
-Support for computing CMAC MACs through the B<EVP_MAC> API.
-
-=head2 Numeric identity
-
-B<EVP_MAC_CMAC> is the numeric identity for this implementation, and
-can be used in functions like EVP_MAC_CTX_new_id() and
-EVP_get_macbynid().
-
-=head2 Supported controls
-
-The supported controls are:
-
-=over 4
-
-=item B<EVP_MAC_CTRL_SET_KEY>
-
-EVP_MAC_ctrl_str() takes two type strings for this control:
-
-=over 4
-
-=item "key"
-
-The value string is used as is.
-
-=item "hexkey"
-
-The value string is expected to be a hexadecimal number, which will be
-decoded before passing on as control value.
-
-=back
-
-=item B<EVP_MAC_CTRL_SET_ENGINE>
-
-=item B<EVP_MAC_CTRL_SET_CIPHER>
-
-These work as described in L<EVP_MAC(3)/CONTROLS>.
-
-EVP_MAC_ctrl_str() type string for B<EVP_MAC_CTRL_SET_CIPHER>: "cipher"
-
-The value is expected to be the name of a cipher.
-
-=back
-
-=head1 SEE ALSO
-
-L<EVP_MAC_ctrl(3)>, L<EVP_MAC(3)/CONTROLS>
-
-=head1 COPYRIGHT
-
-Copyright 2018 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the Apache License 2.0 (the "License").  You may not use
-this file except in compliance with the License.  You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
diff --git a/doc/man7/EVP_MAC_GMAC.pod b/doc/man7/EVP_MAC_GMAC.pod
deleted file mode 100644 (file)
index 6e4ba1a..0000000
+++ /dev/null
@@ -1,83 +0,0 @@
-=pod
-
-=head1 NAME
-
-EVP_MAC_GMAC - The GMAC EVP_MAC implementation
-
-=head1 DESCRIPTION
-
-Support for computing GMAC MACs through the B<EVP_MAC> API.
-
-=head2 Numeric identity
-
-B<EVP_MAC_GMAC> is the numeric identity for this implementation, and
-can be used in functions like EVP_MAC_CTX_new_id() and
-EVP_get_macbynid().
-
-=head2 Supported controls
-
-The supported controls are:
-
-=over 4
-
-=item B<EVP_MAC_CTRL_SET_KEY>
-
-EVP_MAC_ctrl_str() takes two type strings for this control:
-
-=over 4
-
-=item "key"
-
-The value string is used as is.
-
-=item "hexkey"
-
-The value string is expected to be a hexadecimal number, which will be
-decoded before passing on as control value.
-
-=back
-
-=item B<EVP_MAC_CTRL_SET_IV>
-
-EVP_MAC_ctrl_str() takes two type strings for this control:
-
-=over 4
-
-=item "iv"
-
-The value string is used as is.
-
-=item "hexiv"
-
-The value string is expected to be a hexadecimal number, which will be
-decoded before passing on as control value.
-
-=back
-
-=item B<EVP_MAC_CTRL_SET_ENGINE>
-
-=item B<EVP_MAC_CTRL_SET_CIPHER>
-
-These work as described in L<EVP_MAC(3)/CONTROLS> with the restriction that the
-cipher must be an AEAD one.
-
-EVP_MAC_ctrl_str() type string for B<EVP_MAC_CTRL_SET_CIPHER>: "cipher"
-
-The value is expected to be the name of a cipher.
-
-=back
-
-=head1 SEE ALSO
-
-L<EVP_MAC_ctrl(3)>, L<EVP_MAC(3)/CONTROLS>
-
-=head1 COPYRIGHT
-
-Copyright 2018 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the Apache License 2.0 (the "License").  You may not use
-this file except in compliance with the License.  You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
diff --git a/doc/man7/EVP_MAC_HMAC.pod b/doc/man7/EVP_MAC_HMAC.pod
deleted file mode 100644 (file)
index c8aa047..0000000
+++ /dev/null
@@ -1,71 +0,0 @@
-=pod
-
-=head1 NAME
-
-EVP_MAC_HMAC - The HMAC EVP_MAC implementation
-
-=head1 DESCRIPTION
-
-Support for computing HMAC MACs through the B<EVP_MAC> API.
-
-=head2 Numeric identity
-
-B<EVP_MAC_HMAC> is the numeric identity for this implementation, and
-can be used in functions like EVP_MAC_CTX_new_id() and
-EVP_get_macbynid().
-
-=head2 Supported controls
-
-The supported controls are:
-
-=over 4
-
-=item B<EVP_MAC_CTRL_SET_KEY>
-
-EVP_MAC_ctrl_str() takes two type strings for this control:
-
-=over 4
-
-=item "key"
-
-The value string is used as is.
-
-=item "hexkey"
-
-The value string is expected to be a hexadecimal number, which will be
-decoded before passing on as control value.
-
-=back
-
-=item B<EVP_MAC_CTRL_SET_FLAGS>
-
-Sets HMAC flags.  This is passed directly to HMAC_CTX_set_flags().
-
-There are no corresponding string control types.
-
-=item B<EVP_MAC_CTRL_SET_ENGINE>
-
-=item B<EVP_MAC_CTRL_SET_MD>
-
-These work as described in L<EVP_MAC(3)/CONTROLS>.
-
-EVP_MAC_ctrl_str() type string for B<EVP_MAC_CTRL_SET_MD>: "digest"
-
-The value is expected to be the name of a cipher.
-
-=back
-
-=head1 SEE ALSO
-
-L<EVP_MAC_ctrl(3)>, L<EVP_MAC(3)/CONTROLS>
-
-=head1 COPYRIGHT
-
-Copyright 2018 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the Apache License 2.0 (the "License").  You may not use
-this file except in compliance with the License.  You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
diff --git a/doc/man7/EVP_MAC_KMAC.pod b/doc/man7/EVP_MAC_KMAC.pod
deleted file mode 100644 (file)
index 4ccaabe..0000000
+++ /dev/null
@@ -1,94 +0,0 @@
-=pod
-
-=head1 NAME
-
-EVP_MAC_KMAC - The KMAC EVP_MAC implementation
-
-=head1 DESCRIPTION
-
-Support for computing KMAC MACs through the B<EVP_MAC> API.
-
-=head2 Numeric identity
-
-B<EVP_MAC_KMAC128> and B<EVP_MAC_KMAC256> are the numeric identities for this
-implementation, and can be used in functions like EVP_MAC_CTX_new_id() and
-EVP_get_macbynid().
-
-=head2 Supported controls
-
-The supported controls are:
-
-=over 4
-
-=item B<EVP_MAC_CTRL_SET_KEY>
-
-This must be set before calling EVP_MAC_init().
-
-EVP_MAC_ctrl_str() takes two type strings for this control:
-
-=over 4
-
-=item "key"
-
-The value string is used as is.
-
-=item "hexkey"
-
-The value string is expected to be a hexadecimal number, which will be
-decoded before passing on as control value.
-
-=back
-
-=item B<EVP_MAC_CTRL_SET_CUSTOM>
-
-This is an optional string value that can be set before calling EVP_MAC_init().
-If it is not set it uses the default value "".
-
-EVP_MAC_ctrl_str() takes two type strings for this control:
-
-=over 4
-
-=item "custom"
-
-The value string is used as is.
-
-=item "hexcustom"
-
-The value string is expected to be a hexadecimal number, which will be
-decoded before passing on as control value.
-
-=back
-
-=item B<EVP_MAC_CTRL_SET_SIZE>
-
-EVP_MAC_ctrl_str() type string: "outlen"
-
-This is an optional value string containing a decimal number. If it is not set
-it uses the default value of 32 for EVP_MAC_KMAC128 and 64 for EVP_MAC_KMAC256.
-This can be called any time before EVP_MAC_final().
-
-=item B<EVP_MAC_CTRL_SET_XOF>
-
-EVP_MAC_ctrl_str() type string: "xof"
-
-The value string is expected to be an integer value of 1 or 0. Use 1 to enable
-XOF mode. If XOF is enabled then the output len that is encoded as part of the
-input stream is set to zero.
-This can be called any time before EVP_MAC_final().
-
-=back
-
-=head1 SEE ALSO
-
-L<EVP_MAC_ctrl(3)>, L<EVP_MAC(3)/CONTROLS>
-
-=head1 COPYRIGHT
-
-Copyright 2018 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the Apache License 2.0 (the "License").  You may not use
-this file except in compliance with the License.  You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
diff --git a/doc/man7/EVP_MAC_POLY1305.pod b/doc/man7/EVP_MAC_POLY1305.pod
deleted file mode 100644 (file)
index 89234b7..0000000
+++ /dev/null
@@ -1,55 +0,0 @@
-=pod
-
-=head1 NAME
-
-EVP_MAC_POLY1305 - The Poly1305 EVP_MAC implementation
-
-=head1 DESCRIPTION
-
-Support for computing Poly1305 MACs through the B<EVP_MAC> API.
-
-=head2 Numeric identity
-
-B<EVP_MAC_POLY1305> is the numeric identity for this implementation,
-and can be used in functions like EVP_MAC_CTX_new_id() and
-EVP_get_macbynid().
-
-=head2 Supported controls
-
-The supported controls are:
-
-=over 4
-
-=item B<EVP_MAC_CTRL_SET_KEY>
-
-EVP_MAC_ctrl_str() takes two type strings for this control:
-
-=over 4
-
-=item "key"
-
-The value string is used as is.
-
-=item "hexkey"
-
-The value string is expected to be a hexadecimal number, which will be
-decoded before passing on as control value.
-
-=back
-
-=back
-
-=head1 SEE ALSO
-
-L<EVP_MAC_ctrl(3)>, L<EVP_MAC(3)/CONTROLS>
-
-=head1 COPYRIGHT
-
-Copyright 2018 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the Apache License 2.0 (the "License").  You may not use
-this file except in compliance with the License.  You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
diff --git a/doc/man7/EVP_MAC_SIPHASH.pod b/doc/man7/EVP_MAC_SIPHASH.pod
deleted file mode 100644 (file)
index eeb0cfd..0000000
+++ /dev/null
@@ -1,61 +0,0 @@
-=pod
-
-=head1 NAME
-
-EVP_MAC_SIPHASH - The SipHash EVP_MAC implementation
-
-=head1 DESCRIPTION
-
-Support for computing SipHash MACs through the B<EVP_MAC> API.
-
-=head2 Numeric identity
-
-B<EVP_MAC_SIPHASH> is the numeric identity for this implementation,
-and can be used in functions like EVP_MAC_CTX_new_id() and
-EVP_get_macbynid().
-
-=head2 Supported controls
-
-The supported controls are:
-
-=over 4
-
-=item B<EVP_MAC_CTRL_SET_SIZE>
-
-EVP_MAC_ctrl_str() type string: "digestsize"
-
-The value string is expected to contain a decimal number.
-
-=item B<EVP_MAC_CTRL_SET_KEY>
-
-EVP_MAC_ctrl_str() takes two type strings for this control:
-
-=over 4
-
-=item "key"
-
-The value string is used as is.
-
-=item "hexkey"
-
-The value string is expected to be a hexadecimal number, which will be
-decoded before passing on as control value.
-
-=back
-
-=back
-
-=head1 SEE ALSO
-
-L<EVP_MAC_ctrl(3)>, L<EVP_MAC(3)/CONTROLS>
-
-=head1 COPYRIGHT
-
-Copyright 2018 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the Apache License 2.0 (the "License").  You may not use
-this file except in compliance with the License.  You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut