Document EVP_PKEY_new_mac_key(3);

from Matt Caswell <matt at openssl dot org>
via OpenSSL commit d45a97f4 Mar 5 17:41:49 2018 +0000.

1 files changed, 50 insertions, 8 deletions

diff --git a/lib/libcrypto/man/EVP_PKEY_new.3 b/lib/libcrypto/man/EVP_PKEY_new.3
index fade3d5cd27..777c108d833 100644
--- a/lib/libcrypto/man/EVP_PKEY_new.3
+++ b/lib/libcrypto/man/EVP_PKEY_new.3
@@ -1,8 +1,10 @@
-.\" $OpenBSD: EVP_PKEY_new.3,v 1.8 2018/03/27 17:35:50 schwarze Exp $
-.\" full merge up to: OpenSSL 99d63d42 Oct 26 13:56:48 2016 -0400
+.\" $OpenBSD: EVP_PKEY_new.3,v 1.9 2018/12/22 23:19:53 schwarze 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
 .\"
-.\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
-.\" Copyright (c) 2002 The OpenSSL Project.  All rights reserved.
+.\" This file was written by Dr. Stephen Henson <steve@openssl.org>
+.\" and Matt Caswell <matt@openssl.org>.
+.\" Copyright (c) 2002, 2018 The OpenSSL Project.  All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
 .\" modification, are permitted provided that the following conditions
@@ -48,13 +50,14 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: March 27 2018 $
+.Dd $Mdocdate: December 22 2018 $
 .Dt EVP_PKEY_NEW 3
 .Os
 .Sh NAME
 .Nm EVP_PKEY_new ,
 .Nm EVP_PKEY_up_ref ,
-.Nm EVP_PKEY_free
+.Nm EVP_PKEY_free ,
+.Nm EVP_PKEY_new_mac_key
 .Nd private key allocation functions
 .Sh SYNOPSIS
 .In openssl/evp.h
@@ -68,6 +71,13 @@
 .Fo EVP_PKEY_free
 .Fa "EVP_PKEY *key"
 .Fc
+.Ft EVP_PKEY *
+.Fo EVP_PKEY_new_mac_key
+.Fa "int type"
+.Fa "ENGINE *e"
+.Fa "const unsigned char *key"
+.Fa "int keylen"
+.Fc
 .Sh DESCRIPTION
 The
 .Vt EVP_PKEY
@@ -80,7 +90,7 @@ function allocates an empty
 .Vt EVP_PKEY
 structure.
 The reference count is set to 1.
-To add a private key to it, use the functions described in
+To add a private or public key to it, use the functions described in
 .Xr EVP_PKEY_set1_RSA 3 .
 .Pp
 .Fn EVP_PKEY_up_ref
@@ -97,9 +107,37 @@ If
 is a
 .Dv NULL
 pointer, no action occurs.
+.Pp
+.Fn EVP_PKEY_new_mac_key
+allocates a new
+.Vt EVP_PKEY .
+If
+.Fa e
+is
+.Pf non- Dv NULL ,
+then the new
+.Vt EVP_PKEY
+structure is associated with the engine
+.Fa e .
+The
+.Fa type
+argument indicates what kind of key this is.
+The value should be a NID for a public key algorithm that supports
+raw private keys, for example
+.Dv EVP_PKEY_HMAC .
+.Fa key
+points to the raw private key data for this
+.Vt EVP_PKEY
+which should be of length
+.Fa keylen .
+The length should be appropriate for the type of the key.
+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
-returns either the newly allocated
+and
+.Fn EVP_PKEY_new_mac_key
+return either the newly allocated
 .Vt EVP_PKEY
 structure or
 .Dv NULL
@@ -117,6 +155,10 @@ and
 first appeared in SSLeay 0.6.0 and have been available since
 .Ox 2.4 .
 .Pp
+.Fn EVP_PKEY_new_mac_key
+first appeared in OpenSSL 1.0.0 and has been available since
+.Ox 4.9 .
+.Pp
 .Fn EVP_PKEY_up_ref
 first appeared in OpenSSL 1.1.0 and has been available since
 .Ox 6.3 .