1.\" $OpenBSD: EVP_PKEY_set1_RSA.3,v 1.24 2024/12/09 11:25:25 schwarze 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: December 9 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.\" The following constants are also intentionally undocumented 100.\" because they are only used by that function: 101.\" EVP_PK_DH EVP_PK_DSA EVP_PK_EC EVP_PK_RSA 102.\" EVP_PKS_DSA EVP_PKS_EC EVP_PKS_RSA 103.\" EVP_PKT_ENC EVP_PKT_EXCH EVP_PKT_EXP EVP_PKT_SIGN 104.Nd EVP_PKEY assignment functions 105.Sh SYNOPSIS 106.In openssl/evp.h 107.Ft int 108.Fo EVP_PKEY_set1_RSA 109.Fa "EVP_PKEY *pkey" 110.Fa "RSA *key" 111.Fc 112.Ft int 113.Fo EVP_PKEY_set1_DSA 114.Fa "EVP_PKEY *pkey" 115.Fa "DSA *key" 116.Fc 117.Ft int 118.Fo EVP_PKEY_set1_DH 119.Fa "EVP_PKEY *pkey" 120.Fa "DH *key" 121.Fc 122.Ft int 123.Fo EVP_PKEY_set1_EC_KEY 124.Fa "EVP_PKEY *pkey" 125.Fa "EC_KEY *key" 126.Fc 127.Ft RSA * 128.Fo EVP_PKEY_get1_RSA 129.Fa "EVP_PKEY *pkey" 130.Fc 131.Ft DSA * 132.Fo EVP_PKEY_get1_DSA 133.Fa "EVP_PKEY *pkey" 134.Fc 135.Ft DH * 136.Fo EVP_PKEY_get1_DH 137.Fa "EVP_PKEY *pkey" 138.Fc 139.Ft EC_KEY * 140.Fo EVP_PKEY_get1_EC_KEY 141.Fa "EVP_PKEY *pkey" 142.Fc 143.Ft RSA * 144.Fo EVP_PKEY_get0_RSA 145.Fa "EVP_PKEY *pkey" 146.Fc 147.Ft DSA * 148.Fo EVP_PKEY_get0_DSA 149.Fa "EVP_PKEY *pkey" 150.Fc 151.Ft DH * 152.Fo EVP_PKEY_get0_DH 153.Fa "EVP_PKEY *pkey" 154.Fc 155.Ft EC_KEY * 156.Fo EVP_PKEY_get0_EC_KEY 157.Fa "EVP_PKEY *pkey" 158.Fc 159.Ft const unsigned char * 160.Fo EVP_PKEY_get0_hmac 161.Fa "const EVP_PKEY *pkey" 162.Fa "size_t *len" 163.Fc 164.Ft void * 165.Fo EVP_PKEY_get0 166.Fa "const EVP_PKEY *pkey" 167.Fc 168.Ft int 169.Fo EVP_PKEY_assign_RSA 170.Fa "EVP_PKEY *pkey" 171.Fa "RSA *key" 172.Fc 173.Ft int 174.Fo EVP_PKEY_assign_DSA 175.Fa "EVP_PKEY *pkey" 176.Fa "DSA *key" 177.Fc 178.Ft int 179.Fo EVP_PKEY_assign_DH 180.Fa "EVP_PKEY *pkey" 181.Fa "DH *key" 182.Fc 183.Ft int 184.Fo EVP_PKEY_assign_EC_KEY 185.Fa "EVP_PKEY *pkey" 186.Fa "EC_KEY *key" 187.Fc 188.Ft int 189.Fo EVP_PKEY_assign 190.Fa "EVP_PKEY *pkey" 191.Fa "int type" 192.Fa "void *key" 193.Fc 194.Ft int 195.Fo EVP_PKEY_base_id 196.Fa "EVP_PKEY *pkey" 197.Fc 198.Ft int 199.Fo EVP_PKEY_id 200.Fa "EVP_PKEY *pkey" 201.Fc 202.Ft int 203.Fo EVP_PKEY_type 204.Fa "int type" 205.Fc 206.Ft int 207.Fo EVP_PKEY_set_type 208.Fa "EVP_PKEY *pkey" 209.Fa "int type" 210.Fc 211.Ft int 212.Fo EVP_PKEY_set_type_str 213.Fa "EVP_PKEY *pkey" 214.Fa "const char *str" 215.Fa "int len" 216.Fc 217.Sh DESCRIPTION 218.Fn EVP_PKEY_set1_RSA , 219.Fn EVP_PKEY_set1_DSA , 220.Fn EVP_PKEY_set1_DH , 221and 222.Fn EVP_PKEY_set1_EC_KEY 223set the key referenced by 224.Fa pkey 225to 226.Fa key 227and increment the reference count of 228.Fa key 229by 1 in case of success. 230.Pp 231.Fn EVP_PKEY_get1_RSA , 232.Fn EVP_PKEY_get1_DSA , 233.Fn EVP_PKEY_get1_DH , 234and 235.Fn EVP_PKEY_get1_EC_KEY 236return the key referenced in 237.Fa pkey , 238incrementing its reference count by 1, or 239.Dv NULL 240if the key is not of the correct type. 241.Pp 242.Fn EVP_PKEY_get0_RSA , 243.Fn EVP_PKEY_get0_DSA , 244.Fn EVP_PKEY_get0_DH , 245.Fn EVP_PKEY_get0_EC_KEY , 246and 247.Fn EVP_PKEY_get0 248are identical except that they do not increment the reference count. 249Consequently, the returned key must not be freed by the caller. 250.Pp 251.Fn EVP_PKEY_get0_hmac 252returns an internal pointer to the key referenced in 253.Fa pkey 254and sets 255.Pf * Fa len 256to its length in bytes. 257The returned pointer must not be freed by the caller. 258If 259.Fa pkey 260is not of the correct type, 261.Dv NULL 262is returned and the content of 263.Pf * Fa len 264becomes unspecified. 265.Pp 266.Fn EVP_PKEY_assign_RSA , 267.Fn EVP_PKEY_assign_DSA , 268.Fn EVP_PKEY_assign_DH , 269.Fn EVP_PKEY_assign_EC_KEY , 270and 271.Fn EVP_PKEY_assign 272also set the referenced key to 273.Fa key ; 274however these use the supplied 275.Fa key 276internally without incrementing its reference count, such that 277.Fa key 278will be freed when the parent 279.Fa pkey 280is freed. 281If the 282.Fa key 283is of the wrong type, these functions report success even though 284.Fa pkey 285ends up in a corrupted state. 286Even the functions explicitly containing the type in their name are 287.Em not 288type safe because they are implemented as macros. 289The following types are supported: 290.Dv EVP_PKEY_RSA , 291.Dv EVP_PKEY_DSA , 292.Dv EVP_PKEY_DH , 293and 294.Dv EVP_PKEY_EC . 295.Pp 296.Fn EVP_PKEY_base_id 297returns the type of 298.Fa pkey 299according to the following table: 300.Pp 301.Bl -column -compact -offset 2n EVP_PKEY_RSA_PSS NID_X9_62_id_ecPublicKey 302.It Sy return value Ta Ta Sy PEM type string 303.It Dv EVP_PKEY_CMAC Ta = Dv NID_cmac Ta CMAC 304.It Dv EVP_PKEY_DH Ta = Dv NID_dhKeyAgreement Ta DH 305.It Dv EVP_PKEY_DSA Ta = Dv NID_dsa Ta DSA 306.It Dv EVP_PKEY_EC Ta = Dv NID_X9_62_id_ecPublicKey Ta EC 307.It Dv EVP_PKEY_HMAC Ta = Dv NID_hmac Ta HMAC 308.It Dv EVP_PKEY_RSA Ta = Dv NID_rsaEncryption Ta RSA 309.It Dv EVP_PKEY_RSA_PSS Ta = Dv NID_rsassaPss Ta RSA-PSS 310.El 311.Pp 312.Fn EVP_PKEY_id 313returns the actual OID associated with 314.Fa pkey . 315Historically keys using the same algorithm could use different OIDs. 316The following deprecated aliases are still supported: 317.Pp 318.Bl -column -compact -offset 2n EVP_PKEY_DSA4 NID_dsaWithSHA1_2 319.It Sy return value Ta Ta Sy alias for 320.It Dv EVP_PKEY_DSA1 Ta = Dv NID_dsa_2 Ta DSA 321.It Dv EVP_PKEY_DSA2 Ta = Dv NID_dsaWithSHA Ta DSA 322.It Dv EVP_PKEY_DSA3 Ta = Dv NID_dsaWithSHA1 Ta DSA 323.It Dv EVP_PKEY_DSA4 Ta = Dv NID_dsaWithSHA1_2 Ta DSA 324.It Dv EVP_PKEY_RSA2 Ta = Dv NID_rsa Ta RSA 325.El 326.Pp 327Most applications wishing to know a key type will simply call 328.Fn EVP_PKEY_base_id 329and will not care about the actual type, 330which will be identical in almost all cases. 331.Pp 332.Fn EVP_PKEY_type 333returns the underlying type of the NID 334.Fa type . 335For example, 336.Fn EVP_PKEY_type EVP_PKEY_RSA2 337will return 338.Dv EVP_PKEY_RSA . 339.Pp 340.Fn EVP_PKEY_set_type 341frees the key referenced in 342.Fa pkey , 343if any, and sets the key type of 344.Fa pkey 345to 346.Fa type 347without referencing a new key from 348.Fa pkey 349yet. 350For 351.Fa type , 352any of the possible return values of 353.Fn EVP_PKEY_base_id 354and 355.Fn EVP_PKEY_id 356can be passed. 357.Pp 358.Fn EVP_PKEY_set_type_str 359frees the key referenced in 360.Fa pkey , 361if any, and sets the key type of 362.Fa pkey 363according to the PEM type string given by the first 364.Fa len 365bytes of 366.Fa str . 367If 368.Fa len 369is \-1, the 370.Xr strlen 3 371of 372.Fa str 373is used instead. 374The PEM type strings supported by default are listed in the table above. 375This function does not reference a new key from 376.Fa pkey . 377.Pp 378If 379.Fa pkey 380is a 381.Dv NULL 382pointer, 383.Fn EVP_PKEY_set_type 384and 385.Fn EVP_PKEY_set_type_str 386check that a matching key type exists but do not change any object. 387.Pp 388In accordance with the OpenSSL naming convention, the key obtained from 389or assigned to 390.Fa pkey 391using the 392.Sy 1 393functions must be freed as well as 394.Fa pkey . 395.Sh RETURN VALUES 396.Fn EVP_PKEY_set1_RSA , 397.Fn EVP_PKEY_set1_DSA , 398.Fn EVP_PKEY_set1_DH , 399.Fn EVP_PKEY_set1_EC_KEY , 400.Fn EVP_PKEY_assign_RSA , 401.Fn EVP_PKEY_assign_DSA , 402.Fn EVP_PKEY_assign_DH , 403.Fn EVP_PKEY_assign_EC_KEY , 404.Fn EVP_PKEY_assign , 405.Fn EVP_PKEY_set_type , 406and 407.Fn EVP_PKEY_set_type_str 408return 1 for success or 0 for failure. 409.Pp 410.Fn EVP_PKEY_get1_RSA , 411.Fn EVP_PKEY_get1_DSA , 412.Fn EVP_PKEY_get1_DH , 413.Fn EVP_PKEY_get1_EC_KEY , 414.Fn EVP_PKEY_get0_RSA , 415.Fn EVP_PKEY_get0_DSA , 416.Fn EVP_PKEY_get0_DH , 417.Fn EVP_PKEY_get0_EC_KEY , 418.Fn EVP_PKEY_get0_hmac , 419and 420.Fn EVP_PKEY_get0 421return the referenced key or 422.Dv NULL 423if an error occurred. 424For 425.Fn EVP_PKEY_get0 , 426the return value points to an 427.Vt RSA , 428.Vt DSA , 429.Vt DH , 430.Vt EC_KEY , 431or 432.Vt ASN1_OCTET_STRING 433object depending on the type of 434.Fa pkey . 435.Pp 436.Fn EVP_PKEY_base_id , 437.Fn EVP_PKEY_id , 438and 439.Fn EVP_PKEY_type 440return a key type or 441.Dv NID_undef 442(equivalently 443.Dv EVP_PKEY_NONE ) 444on error. 445.Sh SEE ALSO 446.Xr DH_new 3 , 447.Xr DSA_new 3 , 448.Xr EC_KEY_new 3 , 449.Xr EVP_PKEY_get0_asn1 3 , 450.Xr EVP_PKEY_new 3 , 451.Xr RSA_new 3 452.Sh HISTORY 453.Fn EVP_PKEY_assign_RSA , 454.Fn EVP_PKEY_assign_DSA , 455.Fn EVP_PKEY_assign_DH , 456.Fn EVP_PKEY_assign , 457and 458.Fn EVP_PKEY_type 459first appeared in SSLeay 0.8.0 and have been available since 460.Ox 2.4 . 461.Pp 462.Fn EVP_PKEY_set1_RSA , 463.Fn EVP_PKEY_set1_DSA , 464.Fn EVP_PKEY_set1_DH , 465.Fn EVP_PKEY_get1_RSA , 466.Fn EVP_PKEY_get1_DSA , 467and 468.Fn EVP_PKEY_get1_DH 469first appeared in OpenSSL 0.9.5 and have been available since 470.Ox 2.7 . 471.Pp 472.Fn EVP_PKEY_set1_EC_KEY , 473.Fn EVP_PKEY_get1_EC_KEY , 474and 475.Fn EVP_PKEY_assign_EC_KEY 476first appeared in OpenSSL 0.9.8 and have been available since 477.Ox 4.5 . 478.Pp 479.Fn EVP_PKEY_get0 , 480.Fn EVP_PKEY_base_id , 481.Fn EVP_PKEY_id , 482.Fn EVP_PKEY_set_type , 483and 484.Fn EVP_PKEY_set_type_str 485first appeared in OpenSSL 1.0.0 and have been available since 486.Ox 4.9 . 487.Pp 488.Fn EVP_PKEY_get0_RSA , 489.Fn EVP_PKEY_get0_DSA , 490.Fn EVP_PKEY_get0_DH , 491and 492.Fn EVP_PKEY_get0_EC_KEY 493first appeared in OpenSSL 1.1.0 and have been available since 494.Ox 6.3 . 495.Pp 496.Fn EVP_PKEY_get0_hmac 497first appeared in OpenSSL 1.1.0 and has been available since 498.Ox 6.5 . 499