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