1.\" $OpenBSD: EVP_PKEY_new.3,v 1.26 2024/12/10 15:10:26 schwarze Exp $ 2.\" full merge up to: OpenSSL 4dcfdfce May 27 11:50:05 2020 +0100 3.\" 4.\" This file is a derived work. 5.\" The changes are covered by the following Copyright and license: 6.\" 7.\" Copyright (c) 2022, 2024 Ingo Schwarze <schwarze@openbsd.org> 8.\" 9.\" Permission to use, copy, modify, and distribute this software for any 10.\" purpose with or without fee is hereby granted, provided that the above 11.\" copyright notice and this permission notice appear in all copies. 12.\" 13.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 14.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 15.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 16.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 17.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 18.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 19.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 20.\" 21.\" The original file was written by Dr. Stephen Henson <steve@openssl.org> 22.\" and Matt Caswell <matt@openssl.org>. 23.\" Copyright (c) 2002, 2018, 2020 The OpenSSL Project. All rights reserved. 24.\" 25.\" Redistribution and use in source and binary forms, with or without 26.\" modification, are permitted provided that the following conditions 27.\" are met: 28.\" 29.\" 1. Redistributions of source code must retain the above copyright 30.\" notice, this list of conditions and the following disclaimer. 31.\" 32.\" 2. Redistributions in binary form must reproduce the above copyright 33.\" notice, this list of conditions and the following disclaimer in 34.\" the documentation and/or other materials provided with the 35.\" distribution. 36.\" 37.\" 3. All advertising materials mentioning features or use of this 38.\" software must display the following acknowledgment: 39.\" "This product includes software developed by the OpenSSL Project 40.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 41.\" 42.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 43.\" endorse or promote products derived from this software without 44.\" prior written permission. For written permission, please contact 45.\" openssl-core@openssl.org. 46.\" 47.\" 5. Products derived from this software may not be called "OpenSSL" 48.\" nor may "OpenSSL" appear in their names without prior written 49.\" permission of the OpenSSL Project. 50.\" 51.\" 6. Redistributions of any form whatsoever must retain the following 52.\" acknowledgment: 53.\" "This product includes software developed by the OpenSSL Project 54.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 55.\" 56.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 57.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 58.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 59.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 60.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 61.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 62.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 63.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 64.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 65.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 66.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 67.\" OF THE POSSIBILITY OF SUCH DAMAGE. 68.\" 69.Dd $Mdocdate: December 10 2024 $ 70.Dt EVP_PKEY_NEW 3 71.Os 72.Sh NAME 73.Nm EVP_PKEY_new , 74.Nm EVP_PKEY_up_ref , 75.Nm EVP_PKEY_free , 76.Nm EVP_PKEY_new_raw_private_key , 77.Nm EVP_PKEY_new_raw_public_key , 78.Nm EVP_PKEY_new_mac_key , 79.Nm EVP_PKEY_get_raw_private_key , 80.Nm EVP_PKEY_get_raw_public_key 81.Nd public and private key allocation and raw key handling functions 82.Sh SYNOPSIS 83.In openssl/evp.h 84.Ft EVP_PKEY * 85.Fn EVP_PKEY_new void 86.Ft int 87.Fo EVP_PKEY_up_ref 88.Fa "EVP_PKEY *pkey" 89.Fc 90.Ft void 91.Fo EVP_PKEY_free 92.Fa "EVP_PKEY *pkey" 93.Fc 94.Ft EVP_PKEY * 95.Fo EVP_PKEY_new_raw_private_key 96.Fa "int type" 97.Fa "ENGINE *engine" 98.Fa "const unsigned char *rawpriv" 99.Fa "size_t rawlen" 100.Fc 101.Ft EVP_PKEY * 102.Fo EVP_PKEY_new_raw_public_key 103.Fa "int type" 104.Fa "ENGINE *engine" 105.Fa "const unsigned char *rawpub" 106.Fa "size_t rawlen" 107.Fc 108.Ft EVP_PKEY * 109.Fo EVP_PKEY_new_mac_key 110.Fa "int type" 111.Fa "ENGINE *engine" 112.Fa "const unsigned char *rawpriv" 113.Fa "int rawlen" 114.Fc 115.Ft int 116.Fo EVP_PKEY_get_raw_private_key 117.Fa "const EVP_PKEY *pkey" 118.Fa "unsigned char *rawpriv" 119.Fa "size_t *rawlen" 120.Fc 121.Ft int 122.Fo EVP_PKEY_get_raw_public_key 123.Fa "const EVP_PKEY *pkey" 124.Fa "unsigned char *rawpub" 125.Fa "size_t *rawlen" 126.Fc 127.Sh DESCRIPTION 128The 129.Vt EVP_PKEY 130structure is used by various OpenSSL functions which require a general 131private or public key without reference to any particular algorithm. 132.Pp 133The 134.Fn EVP_PKEY_new 135function allocates an empty 136.Vt EVP_PKEY 137structure. 138The reference count is set to 1. 139To add a private or public key to it, use the functions described in 140.Xr EVP_PKEY_set1_RSA 3 . 141.Pp 142.Fn EVP_PKEY_up_ref 143increments the reference count of 144.Fa pkey 145by 1. 146.Pp 147.Fn EVP_PKEY_free 148decrements the reference count of 149.Fa pkey 150by 1, and if the reference count reaches zero, frees it up. 151If 152.Fa pkey 153is a 154.Dv NULL 155pointer, no action occurs. 156.Pp 157.Fn EVP_PKEY_new_raw_private_key 158allocates a new 159.Vt EVP_PKEY . 160The NID of a public key algorithm that supports raw private keys, i.e.\& 161.Dv EVP_PKEY_HMAC , 162.Dv EVP_PKEY_X25519 , 163or 164.Dv EVP_PKEY_ED25519 , 165is provided in the 166.Fa type 167argument and 168.Fa rawlen 169bytes of raw private key data of that type in 170.Fa rawpriv . 171The public key data is automatically derived from the given private 172key data, if appropriate for the algorithm type. 173The 174.Fa ENGINE *engine 175argument is always ignored and passing 176.Dv NULL 177is recommended. 178.Pp 179.Fn EVP_PKEY_new_raw_public_key 180works in the same way as 181.Fn EVP_PKEY_new_raw_private_key 182except that 183.Fa rawpub 184points to the raw public key data. 185The 186.Vt EVP_PKEY 187structure is initialised without any private key information. 188Algorithm types that support raw public keys are 189.Dv EVP_PKEY_X25519 190and 191.Dv EVP_PKEY_ED25519 . 192.Pp 193.Fn EVP_PKEY_new_mac_key 194is a deprecated function that achieves the same effect as 195.Fn EVP_PKEY_new_raw_private_key 196in a more complicated way and only works with a 197.Fa type 198of 199.Dv EVP_PKEY_HMAC . 200.Pp 201.Fn EVP_PKEY_get_raw_private_key 202writes up to 203.Pf * Fa rawlen 204bytes of raw private key data to the buffer starting at 205.Fa rawpriv 206and stores the number of bytes written in 207.Pf * Fa rawlen . 208The calling application is responsible for ensuring that the buffer 209is large enough to receive the private key data. 210If the 211.Fa rawpriv 212argument is 213.Dv NULL , 214the number of bytes required to hold the key is stored in 215.Pf * Fa rawlen . 216This function only works for algorithms that support raw private keys. 217Currently these are 218.Dv EVP_PKEY_HMAC , 219.Dv EVP_PKEY_X25519 , 220and 221.Dv EVP_PKEY_ED25519 . 222.Pp 223.Fn EVP_PKEY_get_raw_public_key 224is similar to 225.Fn EVP_PKEY_get_raw_private_key 226except that it writes raw public key data. 227This function only works for algorithms that support raw public keys. 228Currently these are 229.Dv EVP_PKEY_X25519 230and 231.Dv EVP_PKEY_ED25519 . 232.Sh RETURN VALUES 233.Fn EVP_PKEY_new , 234.Fn EVP_PKEY_new_raw_private_key , 235.Fn EVP_PKEY_new_raw_public_key , 236and 237.Fn EVP_PKEY_new_mac_key 238return either the newly allocated 239.Vt EVP_PKEY 240structure or 241.Dv NULL 242if an error occurred. 243.Pp 244.Fn EVP_PKEY_up_ref , 245.Fn EVP_PKEY_get_raw_private_key , 246and 247.Fn EVP_PKEY_get_raw_public_key 248return 1 for success or 0 for failure. 249.Sh EXAMPLES 250The following code digests a message with HMAC-SHA256: 251.Bd -literal -offset indent 252/* Bogus key: would normally be set from another source */ 253const unsigned char *key = "key"; 254const size_t key_len = strlen(key); 255 256const char *msg = "The quick brown fox jumps over the lazy dog"; 257const size_t msg_len = strlen(msg); 258 259unsigned char *out_mac; 260size_t out_len, i; 261 262EVP_PKEY *pkey; 263EVP_MD_CTX *md_ctx; 264 265pkey = EVP_PKEY_new_raw_private_key(EVP_PKEY_HMAC, NULL, 266 key, key_len); 267if (pkey == NULL) 268 err(1, "EVP_PKEY_new_raw_private_key"); 269 270md_ctx = EVP_MD_CTX_new(); 271if (md_ctx == NULL) 272 err(1, "EVP_MD_CTX_new"); 273 274if (EVP_DigestSignInit(md_ctx, NULL, EVP_sha256(), NULL, pkey) == 0) 275 err(1, "EVP_DigestSignInit"); 276if (EVP_DigestSign(md_ctx, NULL, &out_len, msg, msg_len) == 0) 277 err(1, "EVP_DigestSign(NULL)"); 278if ((out_mac = calloc(1, out_len)) == NULL) 279 err(1, "calloc"); 280if (EVP_DigestSign(md_ctx, out_mac, &out_len, msg, msg_len) == 0) 281 err(1, "EVP_DigestSign(MAC)"); 282 283EVP_MD_CTX_free(md_ctx); 284EVP_PKEY_free(pkey); 285 286printf(" MAC = "); 287for (i = 0; i < out_len; i++) 288 printf("%02x", out_mac[i]); 289printf("\en"); 290free(out_mac); 291.Ed 292.Pp 293Even though the type name 294.Vt EVP_PKEY 295was originally intended to stand for 296.Dq private key 297and the 298.Xr EVP_DigestSignInit 3 299API was designed for digital signatures in the context of public key 300cryptography, both are also used here because a MAC also requires a key, 301even though that is a symmetric key. 302.Pp 303The same code can be used for signing with Ed25519 by making the key 304.Dv ED25519_PRIVATE_KEY_LENGTH No = 32 305bytes long, replacing 306.Dv EVP_PKEY_HMAC 307with 308.Dv EVP_PKEY_ED25519 , 309and replacing the call to 310.Xr EVP_sha256 3 311with 312.Dv NULL . 313.Sh SEE ALSO 314.Xr CMAC_Init 3 , 315.Xr d2i_PrivateKey 3 , 316.Xr evp 3 , 317.Xr EVP_PKCS82PKEY 3 , 318.Xr EVP_PKEY_cmp 3 , 319.Xr EVP_PKEY_CTX_new 3 , 320.Xr EVP_PKEY_get_default_digest_nid 3 , 321.Xr EVP_PKEY_new_CMAC_key 3 , 322.Xr EVP_PKEY_print_private 3 , 323.Xr EVP_PKEY_set1_RSA 3 , 324.Xr EVP_PKEY_size 3 , 325.Xr X509_get_pubkey_parameters 3 326.Sh HISTORY 327.Fn EVP_PKEY_new 328and 329.Fn EVP_PKEY_free 330first appeared in SSLeay 0.6.0 and have been available since 331.Ox 2.4 . 332.Pp 333.Fn EVP_PKEY_new_mac_key 334first appeared in OpenSSL 1.0.0 and has been available since 335.Ox 4.9 . 336.Pp 337.Fn EVP_PKEY_up_ref 338first appeared in OpenSSL 1.1.0 and has been available since 339.Ox 6.3 . 340.Pp 341.Fn EVP_PKEY_new_raw_private_key , 342.Fn EVP_PKEY_new_raw_public_key , 343.Fn EVP_PKEY_get_raw_private_key , 344and 345.Fn EVP_PKEY_get_raw_public_key 346first appeared in OpenSSL 1.1.1 and have been available since 347.Ox 7.3 . 348