1.\" $OpenBSD: EVP_PKEY_set1_RSA.3,v 1.23 2024/04/18 16:32:22 tb Exp $ 2.\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 3.\" 4.\" This file is a derived work. 5.\" The changes are covered by the following Copyright and license: 6.\" 7.\" Copyright (c) 2019, 2020, 2023 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.\" Copyright (c) 2002, 2015, 2016 The OpenSSL Project. All rights reserved. 23.\" 24.\" Redistribution and use in source and binary forms, with or without 25.\" modification, are permitted provided that the following conditions 26.\" are met: 27.\" 28.\" 1. Redistributions of source code must retain the above copyright 29.\" notice, this list of conditions and the following disclaimer. 30.\" 31.\" 2. Redistributions in binary form must reproduce the above copyright 32.\" notice, this list of conditions and the following disclaimer in 33.\" the documentation and/or other materials provided with the 34.\" distribution. 35.\" 36.\" 3. All advertising materials mentioning features or use of this 37.\" software must display the following acknowledgment: 38.\" "This product includes software developed by the OpenSSL Project 39.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 40.\" 41.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 42.\" endorse or promote products derived from this software without 43.\" prior written permission. For written permission, please contact 44.\" openssl-core@openssl.org. 45.\" 46.\" 5. Products derived from this software may not be called "OpenSSL" 47.\" nor may "OpenSSL" appear in their names without prior written 48.\" permission of the OpenSSL Project. 49.\" 50.\" 6. Redistributions of any form whatsoever must retain the following 51.\" acknowledgment: 52.\" "This product includes software developed by the OpenSSL Project 53.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 54.\" 55.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 56.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 57.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 58.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 59.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 60.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 61.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 62.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 63.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 64.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 65.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 66.\" OF THE POSSIBILITY OF SUCH DAMAGE. 67.\" 68.Dd $Mdocdate: April 18 2024 $ 69.Dt EVP_PKEY_SET1_RSA 3 70.Os 71.Sh NAME 72.Nm EVP_PKEY_set1_RSA , 73.Nm EVP_PKEY_set1_DSA , 74.Nm EVP_PKEY_set1_DH , 75.Nm EVP_PKEY_set1_EC_KEY , 76.Nm EVP_PKEY_get1_RSA , 77.Nm EVP_PKEY_get1_DSA , 78.Nm EVP_PKEY_get1_DH , 79.Nm EVP_PKEY_get1_EC_KEY , 80.Nm EVP_PKEY_get0_RSA , 81.Nm EVP_PKEY_get0_DSA , 82.Nm EVP_PKEY_get0_DH , 83.Nm EVP_PKEY_get0_EC_KEY , 84.Nm EVP_PKEY_get0_hmac , 85.Nm EVP_PKEY_get0 , 86.Nm EVP_PKEY_assign_RSA , 87.Nm EVP_PKEY_assign_DSA , 88.Nm EVP_PKEY_assign_DH , 89.Nm EVP_PKEY_assign_EC_KEY , 90.Nm EVP_PKEY_assign , 91.Nm EVP_PKEY_base_id , 92.Nm EVP_PKEY_id , 93.Nm EVP_PKEY_type , 94.Nm EVP_PKEY_set_type , 95.Nm EVP_PKEY_set_type_str 96.\" The function X509_certificate_type(3) is intentionally undocumented 97.\" and scheduled for deletion from the library. BoringSSL already 98.\" deleted it and OpenSSL deprecates it in version 3.0. 99.Nd EVP_PKEY assignment functions 100.Sh SYNOPSIS 101.In openssl/evp.h 102.Ft int 103.Fo EVP_PKEY_set1_RSA 104.Fa "EVP_PKEY *pkey" 105.Fa "RSA *key" 106.Fc 107.Ft int 108.Fo EVP_PKEY_set1_DSA 109.Fa "EVP_PKEY *pkey" 110.Fa "DSA *key" 111.Fc 112.Ft int 113.Fo EVP_PKEY_set1_DH 114.Fa "EVP_PKEY *pkey" 115.Fa "DH *key" 116.Fc 117.Ft int 118.Fo EVP_PKEY_set1_EC_KEY 119.Fa "EVP_PKEY *pkey" 120.Fa "EC_KEY *key" 121.Fc 122.Ft RSA * 123.Fo EVP_PKEY_get1_RSA 124.Fa "EVP_PKEY *pkey" 125.Fc 126.Ft DSA * 127.Fo EVP_PKEY_get1_DSA 128.Fa "EVP_PKEY *pkey" 129.Fc 130.Ft DH * 131.Fo EVP_PKEY_get1_DH 132.Fa "EVP_PKEY *pkey" 133.Fc 134.Ft EC_KEY * 135.Fo EVP_PKEY_get1_EC_KEY 136.Fa "EVP_PKEY *pkey" 137.Fc 138.Ft RSA * 139.Fo EVP_PKEY_get0_RSA 140.Fa "EVP_PKEY *pkey" 141.Fc 142.Ft DSA * 143.Fo EVP_PKEY_get0_DSA 144.Fa "EVP_PKEY *pkey" 145.Fc 146.Ft DH * 147.Fo EVP_PKEY_get0_DH 148.Fa "EVP_PKEY *pkey" 149.Fc 150.Ft EC_KEY * 151.Fo EVP_PKEY_get0_EC_KEY 152.Fa "EVP_PKEY *pkey" 153.Fc 154.Ft const unsigned char * 155.Fo EVP_PKEY_get0_hmac 156.Fa "const EVP_PKEY *pkey" 157.Fa "size_t *len" 158.Fc 159.Ft void * 160.Fo EVP_PKEY_get0 161.Fa "const EVP_PKEY *pkey" 162.Fc 163.Ft int 164.Fo EVP_PKEY_assign_RSA 165.Fa "EVP_PKEY *pkey" 166.Fa "RSA *key" 167.Fc 168.Ft int 169.Fo EVP_PKEY_assign_DSA 170.Fa "EVP_PKEY *pkey" 171.Fa "DSA *key" 172.Fc 173.Ft int 174.Fo EVP_PKEY_assign_DH 175.Fa "EVP_PKEY *pkey" 176.Fa "DH *key" 177.Fc 178.Ft int 179.Fo EVP_PKEY_assign_EC_KEY 180.Fa "EVP_PKEY *pkey" 181.Fa "EC_KEY *key" 182.Fc 183.Ft int 184.Fo EVP_PKEY_assign 185.Fa "EVP_PKEY *pkey" 186.Fa "int type" 187.Fa "void *key" 188.Fc 189.Ft int 190.Fo EVP_PKEY_base_id 191.Fa "EVP_PKEY *pkey" 192.Fc 193.Ft int 194.Fo EVP_PKEY_id 195.Fa "EVP_PKEY *pkey" 196.Fc 197.Ft int 198.Fo EVP_PKEY_type 199.Fa "int type" 200.Fc 201.Ft int 202.Fo EVP_PKEY_set_type 203.Fa "EVP_PKEY *pkey" 204.Fa "int type" 205.Fc 206.Ft int 207.Fo EVP_PKEY_set_type_str 208.Fa "EVP_PKEY *pkey" 209.Fa "const char *str" 210.Fa "int len" 211.Fc 212.Sh DESCRIPTION 213.Fn EVP_PKEY_set1_RSA , 214.Fn EVP_PKEY_set1_DSA , 215.Fn EVP_PKEY_set1_DH , 216and 217.Fn EVP_PKEY_set1_EC_KEY 218set the key referenced by 219.Fa pkey 220to 221.Fa key 222and increment the reference count of 223.Fa key 224by 1 in case of success. 225.Pp 226.Fn EVP_PKEY_get1_RSA , 227.Fn EVP_PKEY_get1_DSA , 228.Fn EVP_PKEY_get1_DH , 229and 230.Fn EVP_PKEY_get1_EC_KEY 231return the key referenced in 232.Fa pkey , 233incrementing its reference count by 1, or 234.Dv NULL 235if the key is not of the correct type. 236.Pp 237.Fn EVP_PKEY_get0_RSA , 238.Fn EVP_PKEY_get0_DSA , 239.Fn EVP_PKEY_get0_DH , 240.Fn EVP_PKEY_get0_EC_KEY , 241and 242.Fn EVP_PKEY_get0 243are identical except that they do not increment the reference count. 244Consequently, the returned key must not be freed by the caller. 245.Pp 246.Fn EVP_PKEY_get0_hmac 247returns an internal pointer to the key referenced in 248.Fa pkey 249and sets 250.Pf * Fa len 251to its length in bytes. 252The returned pointer must not be freed by the caller. 253If 254.Fa pkey 255is not of the correct type, 256.Dv NULL 257is returned and the content of 258.Pf * Fa len 259becomes unspecified. 260.Pp 261.Fn EVP_PKEY_assign_RSA , 262.Fn EVP_PKEY_assign_DSA , 263.Fn EVP_PKEY_assign_DH , 264.Fn EVP_PKEY_assign_EC_KEY , 265and 266.Fn EVP_PKEY_assign 267also set the referenced key to 268.Fa key ; 269however these use the supplied 270.Fa key 271internally without incrementing its reference count, such that 272.Fa key 273will be freed when the parent 274.Fa pkey 275is freed. 276If the 277.Fa key 278is of the wrong type, these functions report success even though 279.Fa pkey 280ends up in a corrupted state. 281Even the functions explicitly containing the type in their name are 282.Em not 283type safe because they are implemented as macros. 284The following types are supported: 285.Dv EVP_PKEY_RSA , 286.Dv EVP_PKEY_DSA , 287.Dv EVP_PKEY_DH , 288and 289.Dv EVP_PKEY_EC . 290.Pp 291.Fn EVP_PKEY_base_id 292returns the type of 293.Fa pkey 294according to the following table: 295.Pp 296.Bl -column -compact -offset 2n EVP_PKEY_RSA_PSS NID_X9_62_id_ecPublicKey 297.It Sy return value Ta Ta Sy PEM type string 298.It Dv EVP_PKEY_CMAC Ta = Dv NID_cmac Ta CMAC 299.It Dv EVP_PKEY_DH Ta = Dv NID_dhKeyAgreement Ta DH 300.It Dv EVP_PKEY_DSA Ta = Dv NID_dsa Ta DSA 301.It Dv EVP_PKEY_EC Ta = Dv NID_X9_62_id_ecPublicKey Ta EC 302.It Dv EVP_PKEY_HMAC Ta = Dv NID_hmac Ta HMAC 303.It Dv EVP_PKEY_RSA Ta = Dv NID_rsaEncryption Ta RSA 304.It Dv EVP_PKEY_RSA_PSS Ta = Dv NID_rsassaPss Ta RSA-PSS 305.El 306.Pp 307.Fn EVP_PKEY_id 308returns the actual OID associated with 309.Fa pkey . 310Historically keys using the same algorithm could use different OIDs. 311The following deprecated aliases are still supported: 312.Pp 313.Bl -column -compact -offset 2n EVP_PKEY_DSA4 NID_dsaWithSHA1_2 314.It Sy return value Ta Ta Sy alias for 315.It Dv EVP_PKEY_DSA1 Ta = Dv NID_dsa_2 Ta DSA 316.It Dv EVP_PKEY_DSA2 Ta = Dv NID_dsaWithSHA Ta DSA 317.It Dv EVP_PKEY_DSA3 Ta = Dv NID_dsaWithSHA1 Ta DSA 318.It Dv EVP_PKEY_DSA4 Ta = Dv NID_dsaWithSHA1_2 Ta DSA 319.It Dv EVP_PKEY_RSA2 Ta = Dv NID_rsa Ta RSA 320.El 321.Pp 322Most applications wishing to know a key type will simply call 323.Fn EVP_PKEY_base_id 324and will not care about the actual type, 325which will be identical in almost all cases. 326.Pp 327.Fn EVP_PKEY_type 328returns the underlying type of the NID 329.Fa type . 330For example, 331.Fn EVP_PKEY_type EVP_PKEY_RSA2 332will return 333.Dv EVP_PKEY_RSA . 334.Pp 335.Fn EVP_PKEY_set_type 336frees the key referenced in 337.Fa pkey , 338if any, and sets the key type of 339.Fa pkey 340to 341.Fa type 342without referencing a new key from 343.Fa pkey 344yet. 345For 346.Fa type , 347any of the possible return values of 348.Fn EVP_PKEY_base_id 349and 350.Fn EVP_PKEY_id 351can be passed. 352.Pp 353.Fn EVP_PKEY_set_type_str 354frees the key referenced in 355.Fa pkey , 356if any, and sets the key type of 357.Fa pkey 358according to the PEM type string given by the first 359.Fa len 360bytes of 361.Fa str . 362If 363.Fa len 364is \-1, the 365.Xr strlen 3 366of 367.Fa str 368is used instead. 369The PEM type strings supported by default are listed in the table above. 370This function does not reference a new key from 371.Fa pkey . 372.Pp 373If 374.Fa pkey 375is a 376.Dv NULL 377pointer, 378.Fn EVP_PKEY_set_type 379and 380.Fn EVP_PKEY_set_type_str 381check that a matching key type exists but do not change any object. 382.Pp 383In accordance with the OpenSSL naming convention, the key obtained from 384or assigned to 385.Fa pkey 386using the 387.Sy 1 388functions must be freed as well as 389.Fa pkey . 390.Sh RETURN VALUES 391.Fn EVP_PKEY_set1_RSA , 392.Fn EVP_PKEY_set1_DSA , 393.Fn EVP_PKEY_set1_DH , 394.Fn EVP_PKEY_set1_EC_KEY , 395.Fn EVP_PKEY_assign_RSA , 396.Fn EVP_PKEY_assign_DSA , 397.Fn EVP_PKEY_assign_DH , 398.Fn EVP_PKEY_assign_EC_KEY , 399.Fn EVP_PKEY_assign , 400.Fn EVP_PKEY_set_type , 401and 402.Fn EVP_PKEY_set_type_str 403return 1 for success or 0 for failure. 404.Pp 405.Fn EVP_PKEY_get1_RSA , 406.Fn EVP_PKEY_get1_DSA , 407.Fn EVP_PKEY_get1_DH , 408.Fn EVP_PKEY_get1_EC_KEY , 409.Fn EVP_PKEY_get0_RSA , 410.Fn EVP_PKEY_get0_DSA , 411.Fn EVP_PKEY_get0_DH , 412.Fn EVP_PKEY_get0_EC_KEY , 413.Fn EVP_PKEY_get0_hmac , 414and 415.Fn EVP_PKEY_get0 416return the referenced key or 417.Dv NULL 418if an error occurred. 419For 420.Fn EVP_PKEY_get0 , 421the return value points to an 422.Vt RSA , 423.Vt DSA , 424.Vt DH , 425.Vt EC_KEY , 426or 427.Vt ASN1_OCTET_STRING 428object depending on the type of 429.Fa pkey . 430.Pp 431.Fn EVP_PKEY_base_id , 432.Fn EVP_PKEY_id , 433and 434.Fn EVP_PKEY_type 435return a key type or 436.Dv NID_undef 437(equivalently 438.Dv EVP_PKEY_NONE ) 439on error. 440.Sh SEE ALSO 441.Xr DH_new 3 , 442.Xr DSA_new 3 , 443.Xr EC_KEY_new 3 , 444.Xr EVP_PKEY_get0_asn1 3 , 445.Xr EVP_PKEY_new 3 , 446.Xr RSA_new 3 447.Sh HISTORY 448.Fn EVP_PKEY_assign_RSA , 449.Fn EVP_PKEY_assign_DSA , 450.Fn EVP_PKEY_assign_DH , 451.Fn EVP_PKEY_assign , 452and 453.Fn EVP_PKEY_type 454first appeared in SSLeay 0.8.0 and have been available since 455.Ox 2.4 . 456.Pp 457.Fn EVP_PKEY_set1_RSA , 458.Fn EVP_PKEY_set1_DSA , 459.Fn EVP_PKEY_set1_DH , 460.Fn EVP_PKEY_get1_RSA , 461.Fn EVP_PKEY_get1_DSA , 462and 463.Fn EVP_PKEY_get1_DH 464first appeared in OpenSSL 0.9.5 and have been available since 465.Ox 2.7 . 466.Pp 467.Fn EVP_PKEY_set1_EC_KEY , 468.Fn EVP_PKEY_get1_EC_KEY , 469and 470.Fn EVP_PKEY_assign_EC_KEY 471first appeared in OpenSSL 0.9.8 and have been available since 472.Ox 4.5 . 473.Pp 474.Fn EVP_PKEY_get0 , 475.Fn EVP_PKEY_base_id , 476.Fn EVP_PKEY_id , 477.Fn EVP_PKEY_set_type , 478and 479.Fn EVP_PKEY_set_type_str 480first appeared in OpenSSL 1.0.0 and have been available since 481.Ox 4.9 . 482.Pp 483.Fn EVP_PKEY_get0_RSA , 484.Fn EVP_PKEY_get0_DSA , 485.Fn EVP_PKEY_get0_DH , 486and 487.Fn EVP_PKEY_get0_EC_KEY 488first appeared in OpenSSL 1.1.0 and have been available since 489.Ox 6.3 . 490.Pp 491.Fn EVP_PKEY_get0_hmac 492first appeared in OpenSSL 1.1.0 and has been available since 493.Ox 6.5 . 494