From 47aad511869fbab8df27a9d9220f3dfaa012d2e7 Mon Sep 17 00:00:00 2001
From: schwarze <schwarze@openbsd.org>
Date: Fri, 29 Nov 2024 12:05:06 +0000
Subject: [PATCH] Provide an example of signing with HMAC-SHA256 or Ed25519
 because that makes it easier to see the big picture of how
 EVP_PKEY_new_raw_private_key(3) is supposed to be used. Feedback and OK tb@.

---
 lib/libcrypto/man/EVP_PKEY_new.3 | 70 ++++++++++++++++++++++++++++++--
 1 file changed, 67 insertions(+), 3 deletions(-)

diff --git a/lib/libcrypto/man/EVP_PKEY_new.3 b/lib/libcrypto/man/EVP_PKEY_new.3
index aae1ab3f918..0705c8432aa 100644
--- a/lib/libcrypto/man/EVP_PKEY_new.3
+++ b/lib/libcrypto/man/EVP_PKEY_new.3
@@ -1,10 +1,10 @@
-.\" $OpenBSD: EVP_PKEY_new.3,v 1.21 2024/11/12 20:15:24 schwarze Exp $
+.\" $OpenBSD: EVP_PKEY_new.3,v 1.22 2024/11/29 12:05:06 schwarze Exp $
 .\" full merge up to: OpenSSL 4dcfdfce May 27 11:50:05 2020 +0100
 .\"
 .\" This file is a derived work.
 .\" The changes are covered by the following Copyright and license:
 .\"
-.\" Copyright (c) 2022 Ingo Schwarze <schwarze@openbsd.org>
+.\" Copyright (c) 2022, 2024 Ingo Schwarze <schwarze@openbsd.org>
 .\"
 .\" Permission to use, copy, modify, and distribute this software for any
 .\" purpose with or without fee is hereby granted, provided that the above
@@ -66,7 +66,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: November 12 2024 $
+.Dd $Mdocdate: November 29 2024 $
 .Dt EVP_PKEY_NEW 3
 .Os
 .Sh NAME
@@ -242,6 +242,70 @@ if an error occurred.
 and
 .Fn EVP_PKEY_get_raw_public_key
 return 1 for success or 0 for failure.
+.Sh EXAMPLES
+The following code digests a message with HMAC-SHA256:
+.Bd -literal -offset indent
+/* Bogus key: would normally be set from another source */
+const unsigned char *key = "key";
+const size_t key_len = strlen(key);
+
+const char *msg = "The quick brown fox jumps over the lazy dog";
+const size_t msg_len = strlen(msg);
+
+unsigned char *out_mac;
+size_t out_len, i;
+
+EVP_PKEY *pkey;
+EVP_MD_CTX *md_ctx;
+
+pkey = EVP_PKEY_new_raw_private_key(EVP_PKEY_HMAC, NULL,
+    key, key_len);
+if (pkey == NULL)
+	err(1, "EVP_PKEY_new_raw_private_key");
+
+md_ctx = EVP_MD_CTX_new();
+if (md_ctx == NULL)
+	err(1, "EVP_MD_CTX_new");
+
+if (EVP_DigestSignInit(md_ctx, NULL, EVP_sha256(), NULL, pkey) == 0)
+	err(1, "EVP_DigestSignInit");
+if (EVP_DigestSign(md_ctx, NULL, &out_len, msg, msg_len) == 0)
+	err(1, "EVP_DigestSign(NULL)");
+if ((out_mac = calloc(1, out_len)) == NULL)
+	err(1, "calloc");
+if (EVP_DigestSign(md_ctx, out_mac, &out_len, msg, msg_len) == 0)
+	err(1, "EVP_DigestSign(MAC)");
+
+EVP_MD_CTX_free(md_ctx);
+EVP_PKEY_free(pkey);
+
+printf(" MAC = ");
+for (i = 0; i < out_len; i++)
+	printf("%02x", out_mac[i]);
+printf("\en");
+free(out_mac);
+.Ed
+.Pp
+Even though the type name
+.Vt EVP_PKEY
+was originally intended to stand for
+.Dq private key
+and the
+.Xr EVP_DigestSignInit 3
+API was designed for digital signatures in the context of public key
+cryptography, both are also used here because a MAC also requires a key,
+even though that is a symmetric key.
+.Pp
+The same code can be used for signing with Ed25519 by making the key
+.Dv ED25519_PRIVATE_KEY_LENGTH No = 32
+bytes long, replacing
+.Dv EVP_PKEY_HMAC
+with
+.Dv EVP_PKEY_ED25519 ,
+and replacing the call to
+.Xr EVP_sha256 3
+with
+.Dv NULL .
 .Sh SEE ALSO
 .Xr CMAC_Init 3 ,
 .Xr d2i_PrivateKey 3 ,