1
0
mirror of https://github.com/openbsd/src.git synced 2025-01-09 22:38:01 -08:00

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@.
This commit is contained in:
schwarze 2024-11-29 12:05:06 +00:00
parent a4f8957185
commit 47aad51186

View File

@ -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 ,