From: tb <tb@openbsd.org>
Date: Mon, 29 Mar 2021 17:58:29 +0000 (+0000)
Subject: Prepare documenting EVP_PKEY_new_CMAC_key(3)
X-Git-Url: http://artulab.com/gitweb/?a=commitdiff_plain;h=a1ca96d0755f8b7b773bbab07aa456c4fb527d59;p=openbsd

Prepare documenting EVP_PKEY_new_CMAC_key(3)

Based on some text in OpenSSL 1.1.1's EVP_PKEY_new.pod.
---

diff --git a/lib/libcrypto/man/EVP_PKEY_new.3 b/lib/libcrypto/man/EVP_PKEY_new.3
index 00ffbce95de..51f9d9b4b01 100644
--- a/lib/libcrypto/man/EVP_PKEY_new.3
+++ b/lib/libcrypto/man/EVP_PKEY_new.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: EVP_PKEY_new.3,v 1.11 2019/06/07 19:59:11 schwarze Exp $
+.\" $OpenBSD: EVP_PKEY_new.3,v 1.12 2021/03/29 17:58:29 tb Exp $
 .\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
 .\" selective merge up to: OpenSSL df75c2bf Dec 9 01:02:36 2018 +0100
 .\"
@@ -50,13 +50,16 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: June 7 2019 $
+.Dd $Mdocdate: March 29 2021 $
 .Dt EVP_PKEY_NEW 3
 .Os
 .Sh NAME
 .Nm EVP_PKEY_new ,
 .Nm EVP_PKEY_up_ref ,
 .Nm EVP_PKEY_free ,
+.ig \" will appear in a library bump before Ox 6.9
+.Nm EVP_PKEY_new_CMAC_key
+..
 .Nm EVP_PKEY_new_mac_key
 .Nd private key allocation functions
 .Sh SYNOPSIS
@@ -71,6 +74,15 @@
 .Fo EVP_PKEY_free
 .Fa "EVP_PKEY *key"
 .Fc
+.ig
+.Ft EVP_PKEY *
+.Fo EVP_PKEY_new_CMAC_key
+.Fa "ENGINE *e"
+.Fa "const unsigned char *priv"
+.Fa "size_t len"
+.Fa "const EVP_CIPHER *cipher"
+.Fc
+..
 .Ft EVP_PKEY *
 .Fo EVP_PKEY_new_mac_key
 .Fa "int type"
@@ -107,6 +119,34 @@ If
 is a
 .Dv NULL
 pointer, no action occurs.
+.ig
+.Pp
+.Fn EVP_PKEY_new_CMAC_key
+allocates a new
+.Vt EVP_PKEY
+for the
+.Dv EVP_PKEY_CMAC
+algorithm type.
+If
+.Fa e
+is
+.Pf non- Dv NULL ,
+then the new
+.Vt EVP_PKEY
+is associated with the engine
+.Fa e .
+.Fa priv
+points to the raw private key data
+of length
+.Fa len
+for this
+.Vt EVP_PKEY .
+.Fa cipher
+specifies a cipher algorithm to be used during creation of the CMAC.
+.Fa cipher
+should be a standard encryption only cipher.
+For example, AEAD and XTS ciphers should not be used.
+..
 .Pp
 .Fn EVP_PKEY_new_mac_key
 allocates a new
@@ -135,6 +175,9 @@ The public key data will be automatically derived from the given
 private key data (if appropriate for the algorithm type).
 .Sh RETURN VALUES
 .Fn EVP_PKEY_new
+.ig
+.Fn EVP_PKEY_new_CMAC_key ,
+..
 and
 .Fn EVP_PKEY_new_mac_key
 return either the newly allocated
@@ -146,6 +189,9 @@ if an error occurred.
 .Fn EVP_PKEY_up_ref
 returns 1 for success or 0 for failure.
 .Sh SEE ALSO
+.ig
+.Xr CMAC_Init 3 ,
+..
 .Xr d2i_PrivateKey 3 ,
 .Xr evp 3 ,
 .Xr EVP_PKEY_asn1_new 3 ,
@@ -161,6 +207,12 @@ and
 .Fn EVP_PKEY_free
 first appeared in SSLeay 0.6.0 and have been available since
 .Ox 2.4 .
+.ig
+.Pp
+.Fn EVP_PKEY_new_CMAC_key
+first appeared in OpenSSL 1.1.1 and has been available since
+.Ox 6.9 .
+..
 .Pp
 .Fn EVP_PKEY_new_mac_key
 first appeared in OpenSSL 1.0.0 and has been available since