1.\" $OpenBSD: EVP_PKEY_set1_RSA.3,v 1.16 2019/09/01 09:10:09 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 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: September 1 2019 $ 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_set_type , 93.Nm EVP_PKEY_base_id , 94.Nm EVP_PKEY_id , 95.Nm EVP_PKEY_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_set_type 193.Fa "EVP_PKEY *pkey" 194.Fa "int type" 195.Fc 196.Ft int 197.Fo EVP_PKEY_base_id 198.Fa "EVP_PKEY *pkey" 199.Fc 200.Ft int 201.Fo EVP_PKEY_id 202.Fa "EVP_PKEY *pkey" 203.Fc 204.Ft int 205.Fo EVP_PKEY_type 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_set_type 290frees the key referenced in 291.Fa pkey , 292if any, and sets the key type of 293.Fa pkey 294to 295.Fa type 296without referencing a new key from 297.Fa pkey 298yet. 299.Pp 300.Fn EVP_PKEY_base_id 301returns the type of 302.Fa pkey . 303For example, an RSA key will return 304.Dv EVP_PKEY_RSA . 305.Pp 306.Fn EVP_PKEY_id 307returns the actual OID associated with 308.Fa pkey . 309Historically keys using the same algorithm could use different OIDs. 310For example, an RSA key could use the OIDs corresponding to the NIDs 311.Dv NID_rsaEncryption 312(equivalent to 313.Dv EVP_PKEY_RSA ) 314or 315.Dv NID_rsa 316(equivalent to 317.Dv EVP_PKEY_RSA2 ) . 318The use of alternative non-standard OIDs is now rare, so 319.Dv EVP_PKEY_RSA2 320et al. are not often seen in practice. 321.Pp 322.Fn EVP_PKEY_type 323returns the underlying type of the NID 324.Fa type . 325For example, 326.Fn EVP_PKEY_type EVP_PKEY_RSA2 327will return 328.Dv EVP_PKEY_RSA . 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 335In accordance with the OpenSSL naming convention, the key obtained from 336or assigned to 337.Fa pkey 338using the 339.Sy 1 340functions must be freed as well as 341.Fa pkey . 342.Sh RETURN VALUES 343.Fn EVP_PKEY_set1_RSA , 344.Fn EVP_PKEY_set1_DSA , 345.Fn EVP_PKEY_set1_DH , 346.Fn EVP_PKEY_set1_EC_KEY , 347.Fn EVP_PKEY_assign_RSA , 348.Fn EVP_PKEY_assign_DSA , 349.Fn EVP_PKEY_assign_DH , 350.Fn EVP_PKEY_assign_EC_KEY , 351.Fn EVP_PKEY_assign_GOST , 352.Fn EVP_PKEY_assign , 353and 354.Fn EVP_PKEY_set_type 355return 1 for success or 0 for failure. 356.Pp 357.Fn EVP_PKEY_get1_RSA , 358.Fn EVP_PKEY_get1_DSA , 359.Fn EVP_PKEY_get1_DH , 360.Fn EVP_PKEY_get1_EC_KEY , 361.Fn EVP_PKEY_get0_RSA , 362.Fn EVP_PKEY_get0_DSA , 363.Fn EVP_PKEY_get0_DH , 364.Fn EVP_PKEY_get0_EC_KEY , 365.Fn EVP_PKEY_get0_hmac , 366and 367.Fn EVP_PKEY_get0 368return the referenced key or 369.Dv NULL 370if an error occurred. 371For 372.Fn EVP_PKEY_get0 , 373the return value points to an 374.Vt RSA , 375.Vt DSA , 376.Vt DH , 377.Vt EC_KEY , 378.Vt GOST_KEY , 379or 380.Vt ASN1_OCTET_STRING 381object depending on the type of 382.Fa pkey . 383.Pp 384.Fn EVP_PKEY_base_id , 385.Fn EVP_PKEY_id , 386and 387.Fn EVP_PKEY_type 388return a key type or 389.Dv NID_undef 390(equivalently 391.Dv EVP_PKEY_NONE ) 392on error. 393.Sh SEE ALSO 394.Xr DH_new 3 , 395.Xr DSA_new 3 , 396.Xr EC_KEY_new 3 , 397.Xr EVP_PKEY_get0_asn1 3 , 398.Xr EVP_PKEY_new 3 , 399.Xr RSA_new 3 400.Sh HISTORY 401.Fn EVP_PKEY_assign_RSA , 402.Fn EVP_PKEY_assign_DSA , 403.Fn EVP_PKEY_assign_DH , 404.Fn EVP_PKEY_assign , 405and 406.Fn EVP_PKEY_type 407first appeared in SSLeay 0.8.0 and have been available since 408.Ox 2.4 . 409.Pp 410.Fn EVP_PKEY_set1_RSA , 411.Fn EVP_PKEY_set1_DSA , 412.Fn EVP_PKEY_set1_DH , 413.Fn EVP_PKEY_get1_RSA , 414.Fn EVP_PKEY_get1_DSA , 415and 416.Fn EVP_PKEY_get1_DH 417first appeared in OpenSSL 0.9.5 and have been available since 418.Ox 2.7 . 419.Pp 420.Fn EVP_PKEY_set1_EC_KEY , 421.Fn EVP_PKEY_get1_EC_KEY , 422and 423.Fn EVP_PKEY_assign_EC_KEY 424first appeared in OpenSSL 0.9.8 and have been available since 425.Ox 4.5 . 426.Pp 427.Fn EVP_PKEY_get0 , 428.Fn EVP_PKEY_set_type , 429.Fn EVP_PKEY_base_id , 430and 431.Fn EVP_PKEY_id 432first appeared in OpenSSL 1.0.0 and have been available since 433.Ox 4.9 . 434.Pp 435.Fn EVP_PKEY_assign_GOST 436first appeared in 437.Ox 5.7 . 438.Pp 439.Fn EVP_PKEY_get0_RSA , 440.Fn EVP_PKEY_get0_DSA , 441.Fn EVP_PKEY_get0_DH , 442and 443.Fn EVP_PKEY_get0_EC_KEY 444first appeared in OpenSSL 1.1.0 and have been available since 445.Ox 6.3 . 446.Pp 447.Fn EVP_PKEY_get0_hmac 448first appeared in OpenSSL 1.1.0 and has been available since 449.Ox 6.5 . 450