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