1.\" $OpenBSD: EVP_PKEY_set1_RSA.3,v 1.18 2021/07/02 11:48:01 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 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 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: July 2 2021 $ 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.\" 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_GOST 185.Fa "EVP_PKEY *pkey" 186.Fa "GOST_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.Sh DESCRIPTION 212.Fn EVP_PKEY_set1_RSA , 213.Fn EVP_PKEY_set1_DSA , 214.Fn EVP_PKEY_set1_DH , 215and 216.Fn EVP_PKEY_set1_EC_KEY 217set the key referenced by 218.Fa pkey 219to 220.Fa key 221and increment the reference count of 222.Fa key 223by 1 in case of success. 224.Pp 225.Fn EVP_PKEY_get1_RSA , 226.Fn EVP_PKEY_get1_DSA , 227.Fn EVP_PKEY_get1_DH , 228and 229.Fn EVP_PKEY_get1_EC_KEY 230return the key referenced in 231.Fa pkey , 232incrementing its reference count by 1, or 233.Dv NULL 234if the key is not of the correct type. 235.Pp 236.Fn EVP_PKEY_get0_RSA , 237.Fn EVP_PKEY_get0_DSA , 238.Fn EVP_PKEY_get0_DH , 239.Fn EVP_PKEY_get0_EC_KEY , 240and 241.Fn EVP_PKEY_get0 242are identical except that they do not increment the reference count. 243Consequently, the returned key must not be freed by the caller. 244.Pp 245.Fn EVP_PKEY_get0_hmac 246returns an internal pointer to the key referenced in 247.Fa pkey 248and sets 249.Pf * Fa len 250to its length in bytes. 251The returned pointer must not be freed by the caller. 252If 253.Fa pkey 254is not of the correct type, 255.Dv NULL 256is returned and the content of 257.Pf * Fa len 258becomes unspecified. 259.Pp 260.Fn EVP_PKEY_assign_RSA , 261.Fn EVP_PKEY_assign_DSA , 262.Fn EVP_PKEY_assign_DH , 263.Fn EVP_PKEY_assign_EC_KEY , 264.Fn EVP_PKEY_assign_GOST , 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 , 288.Dv EVP_PKEY_EC , 289and 290.Dv EVP_PKEY_GOSTR01 . 291.Pp 292.Fn EVP_PKEY_base_id 293returns the type of 294.Fa pkey 295according to the following table: 296.Pp 297.Bl -column -compact -offset 2n EVP_PKEY_GOSTR NID_X9_62_id_ecPublicKey 298.It Sy return value Ta Ta Sy PEM type string 299.It Dv EVP_PKEY_CMAC Ta = Dv NID_cmac Ta CMAC 300.It Dv EVP_PKEY_DH Ta = Dv NID_dhKeyAgreement Ta DH 301.It Dv EVP_PKEY_DSA Ta = Dv NID_dsa Ta DSA 302.It Dv EVP_PKEY_EC Ta = Dv NID_X9_62_id_ecPublicKey Ta EC 303.It Dv EVP_PKEY_GOSTIMIT Ta = Dv NID_id_Gost28147_89_MAC Ta GOST-MAC 304.It Dv EVP_PKEY_GOSTR01 Ta = Dv NID_id_GostR3410_2001 Ta GOST2001 305.It Dv EVP_PKEY_HMAC Ta = Dv NID_hmac Ta HMAC 306.It Dv EVP_PKEY_RSA Ta = Dv NID_rsaEncryption Ta RSA 307.It Dv EVP_PKEY_RSA_PSS Ta = Dv NID_rsassaPss Ta RSA-PSS 308.El 309.Pp 310Application programs can support additional key types by calling 311.Xr EVP_PKEY_asn1_add0 3 . 312.Pp 313.Fn EVP_PKEY_id 314returns the actual OID associated with 315.Fa pkey . 316Historically keys using the same algorithm could use different OIDs. 317The following deprecated aliases are still supported: 318.Pp 319.Bl -column -compact -offset 2n EVP_PKEY_GOSTR12_ NID_id_tc26_gost3410_2012_512 320.It Sy return value Ta Ta Sy alias for 321.It Dv EVP_PKEY_DSA1 Ta = Dv NID_dsa_2 Ta DSA 322.It Dv EVP_PKEY_DSA2 Ta = Dv NID_dsaWithSHA Ta DSA 323.It Dv EVP_PKEY_DSA3 Ta = Dv NID_dsaWithSHA1 Ta DSA 324.It Dv EVP_PKEY_DSA4 Ta = Dv NID_dsaWithSHA1_2 Ta DSA 325.It Dv EVP_PKEY_GOSTR12_256 Ta = Dv NID_id_tc26_gost3410_2012_256 Ta GOST2001 326.It Dv EVP_PKEY_GOSTR12_512 Ta = Dv NID_id_tc26_gost3410_2012_512 Ta GOST2001 327.It Dv EVP_PKEY_RSA2 Ta = Dv NID_rsa Ta RSA 328.El 329.Pp 330Application programs can support additional alternative OIDs by calling 331.Xr EVP_PKEY_asn1_add_alias 3 . 332.Pp 333Most applications wishing to know a key type will simply call 334.Fn EVP_PKEY_base_id 335and will not care about the actual type, 336which will be identical in almost all cases. 337.Pp 338.Fn EVP_PKEY_type 339returns the underlying type of the NID 340.Fa type . 341For example, 342.Fn EVP_PKEY_type EVP_PKEY_RSA2 343will return 344.Dv EVP_PKEY_RSA . 345.Pp 346.Fn EVP_PKEY_set_type 347frees the key referenced in 348.Fa pkey , 349if any, and sets the key type of 350.Fa pkey 351to 352.Fa type 353without referencing a new key from 354.Fa pkey 355yet. 356For 357.Fa type , 358any of the possible return values of 359.Fn EVP_PKEY_base_id 360and 361.Fn EVP_PKEY_id 362can be passed. 363.Pp 364In accordance with the OpenSSL naming convention, the key obtained from 365or assigned to 366.Fa pkey 367using the 368.Sy 1 369functions must be freed as well as 370.Fa pkey . 371.Sh RETURN VALUES 372.Fn EVP_PKEY_set1_RSA , 373.Fn EVP_PKEY_set1_DSA , 374.Fn EVP_PKEY_set1_DH , 375.Fn EVP_PKEY_set1_EC_KEY , 376.Fn EVP_PKEY_assign_RSA , 377.Fn EVP_PKEY_assign_DSA , 378.Fn EVP_PKEY_assign_DH , 379.Fn EVP_PKEY_assign_EC_KEY , 380.Fn EVP_PKEY_assign_GOST , 381.Fn EVP_PKEY_assign , 382and 383.Fn EVP_PKEY_set_type 384return 1 for success or 0 for failure. 385.Pp 386.Fn EVP_PKEY_get1_RSA , 387.Fn EVP_PKEY_get1_DSA , 388.Fn EVP_PKEY_get1_DH , 389.Fn EVP_PKEY_get1_EC_KEY , 390.Fn EVP_PKEY_get0_RSA , 391.Fn EVP_PKEY_get0_DSA , 392.Fn EVP_PKEY_get0_DH , 393.Fn EVP_PKEY_get0_EC_KEY , 394.Fn EVP_PKEY_get0_hmac , 395and 396.Fn EVP_PKEY_get0 397return the referenced key or 398.Dv NULL 399if an error occurred. 400For 401.Fn EVP_PKEY_get0 , 402the return value points to an 403.Vt RSA , 404.Vt DSA , 405.Vt DH , 406.Vt EC_KEY , 407.Vt GOST_KEY , 408or 409.Vt ASN1_OCTET_STRING 410object depending on the type of 411.Fa pkey . 412.Pp 413.Fn EVP_PKEY_base_id , 414.Fn EVP_PKEY_id , 415and 416.Fn EVP_PKEY_type 417return a key type or 418.Dv NID_undef 419(equivalently 420.Dv EVP_PKEY_NONE ) 421on error. 422.Sh SEE ALSO 423.Xr DH_new 3 , 424.Xr DSA_new 3 , 425.Xr EC_KEY_new 3 , 426.Xr EVP_PKEY_get0_asn1 3 , 427.Xr EVP_PKEY_new 3 , 428.Xr RSA_new 3 429.Sh HISTORY 430.Fn EVP_PKEY_assign_RSA , 431.Fn EVP_PKEY_assign_DSA , 432.Fn EVP_PKEY_assign_DH , 433.Fn EVP_PKEY_assign , 434and 435.Fn EVP_PKEY_type 436first appeared in SSLeay 0.8.0 and have been available since 437.Ox 2.4 . 438.Pp 439.Fn EVP_PKEY_set1_RSA , 440.Fn EVP_PKEY_set1_DSA , 441.Fn EVP_PKEY_set1_DH , 442.Fn EVP_PKEY_get1_RSA , 443.Fn EVP_PKEY_get1_DSA , 444and 445.Fn EVP_PKEY_get1_DH 446first appeared in OpenSSL 0.9.5 and have been available since 447.Ox 2.7 . 448.Pp 449.Fn EVP_PKEY_set1_EC_KEY , 450.Fn EVP_PKEY_get1_EC_KEY , 451and 452.Fn EVP_PKEY_assign_EC_KEY 453first appeared in OpenSSL 0.9.8 and have been available since 454.Ox 4.5 . 455.Pp 456.Fn EVP_PKEY_get0 , 457.Fn EVP_PKEY_set_type , 458.Fn EVP_PKEY_base_id , 459and 460.Fn EVP_PKEY_id 461first appeared in OpenSSL 1.0.0 and have been available since 462.Ox 4.9 . 463.Pp 464.Fn EVP_PKEY_assign_GOST 465first appeared in 466.Ox 5.7 . 467.Pp 468.Fn EVP_PKEY_get0_RSA , 469.Fn EVP_PKEY_get0_DSA , 470.Fn EVP_PKEY_get0_DH , 471and 472.Fn EVP_PKEY_get0_EC_KEY 473first appeared in OpenSSL 1.1.0 and have been available since 474.Ox 6.3 . 475.Pp 476.Fn EVP_PKEY_get0_hmac 477first appeared in OpenSSL 1.1.0 and has been available since 478.Ox 6.5 . 479