1.\" $OpenBSD: EVP_PKEY_set1_RSA.3,v 1.15 2019/03/18 04:01:53 schwarze Exp $ 2.\" full merge up to: OpenSSL bb9ad09e Jun 6 00:43:05 2016 -0400 3.\" selective merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 4.\" 5.\" This file was written by Dr. Stephen Henson <steve@openssl.org>. 6.\" Copyright (c) 2002, 2015, 2016 The OpenSSL Project. All rights reserved. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in 17.\" the documentation and/or other materials provided with the 18.\" distribution. 19.\" 20.\" 3. All advertising materials mentioning features or use of this 21.\" software must display the following acknowledgment: 22.\" "This product includes software developed by the OpenSSL Project 23.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 24.\" 25.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 26.\" endorse or promote products derived from this software without 27.\" prior written permission. For written permission, please contact 28.\" openssl-core@openssl.org. 29.\" 30.\" 5. Products derived from this software may not be called "OpenSSL" 31.\" nor may "OpenSSL" appear in their names without prior written 32.\" permission of the OpenSSL Project. 33.\" 34.\" 6. Redistributions of any form whatsoever must retain the following 35.\" acknowledgment: 36.\" "This product includes software developed by the OpenSSL Project 37.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 38.\" 39.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 40.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 41.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 42.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 43.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 44.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 45.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 46.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 47.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 48.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 49.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 50.\" OF THE POSSIBILITY OF SUCH DAMAGE. 51.\" 52.Dd $Mdocdate: March 18 2019 $ 53.Dt EVP_PKEY_SET1_RSA 3 54.Os 55.Sh NAME 56.Nm EVP_PKEY_set1_RSA , 57.Nm EVP_PKEY_set1_DSA , 58.Nm EVP_PKEY_set1_DH , 59.Nm EVP_PKEY_set1_EC_KEY , 60.Nm EVP_PKEY_get1_RSA , 61.Nm EVP_PKEY_get1_DSA , 62.Nm EVP_PKEY_get1_DH , 63.Nm EVP_PKEY_get1_EC_KEY , 64.Nm EVP_PKEY_get0_RSA , 65.Nm EVP_PKEY_get0_DSA , 66.Nm EVP_PKEY_get0_DH , 67.Nm EVP_PKEY_get0_EC_KEY , 68.Nm EVP_PKEY_get0_hmac , 69.Nm EVP_PKEY_assign_RSA , 70.Nm EVP_PKEY_assign_DSA , 71.Nm EVP_PKEY_assign_DH , 72.Nm EVP_PKEY_assign_EC_KEY , 73.Nm EVP_PKEY_base_id , 74.Nm EVP_PKEY_id , 75.Nm EVP_PKEY_type 76.Nd EVP_PKEY assignment functions 77.Sh SYNOPSIS 78.In openssl/evp.h 79.Ft int 80.Fo EVP_PKEY_set1_RSA 81.Fa "EVP_PKEY *pkey" 82.Fa "RSA *key" 83.Fc 84.Ft int 85.Fo EVP_PKEY_set1_DSA 86.Fa "EVP_PKEY *pkey" 87.Fa "DSA *key" 88.Fc 89.Ft int 90.Fo EVP_PKEY_set1_DH 91.Fa "EVP_PKEY *pkey" 92.Fa "DH *key" 93.Fc 94.Ft int 95.Fo EVP_PKEY_set1_EC_KEY 96.Fa "EVP_PKEY *pkey" 97.Fa "EC_KEY *key" 98.Fc 99.Ft RSA * 100.Fo EVP_PKEY_get1_RSA 101.Fa "EVP_PKEY *pkey" 102.Fc 103.Ft DSA * 104.Fo EVP_PKEY_get1_DSA 105.Fa "EVP_PKEY *pkey" 106.Fc 107.Ft DH * 108.Fo EVP_PKEY_get1_DH 109.Fa "EVP_PKEY *pkey" 110.Fc 111.Ft EC_KEY * 112.Fo EVP_PKEY_get1_EC_KEY 113.Fa "EVP_PKEY *pkey" 114.Fc 115.Ft RSA * 116.Fo EVP_PKEY_get0_RSA 117.Fa "EVP_PKEY *pkey" 118.Fc 119.Ft DSA * 120.Fo EVP_PKEY_get0_DSA 121.Fa "EVP_PKEY *pkey" 122.Fc 123.Ft DH * 124.Fo EVP_PKEY_get0_DH 125.Fa "EVP_PKEY *pkey" 126.Fc 127.Ft EC_KEY * 128.Fo EVP_PKEY_get0_EC_KEY 129.Fa "EVP_PKEY *pkey" 130.Fc 131.Ft const unsigned char * 132.Fo EVP_PKEY_get0_hmac 133.Fa "const EVP_PKEY *pkey" 134.Fa "size_t *len" 135.Fc 136.Ft int 137.Fo EVP_PKEY_assign_RSA 138.Fa "EVP_PKEY *pkey" 139.Fa "RSA *key" 140.Fc 141.Ft int 142.Fo EVP_PKEY_assign_DSA 143.Fa "EVP_PKEY *pkey" 144.Fa "DSA *key" 145.Fc 146.Ft int 147.Fo EVP_PKEY_assign_DH 148.Fa "EVP_PKEY *pkey" 149.Fa "DH *key" 150.Fc 151.Ft int 152.Fo EVP_PKEY_assign_EC_KEY 153.Fa "EVP_PKEY *pkey" 154.Fa "EC_KEY *key" 155.Fc 156.Ft int 157.Fo EVP_PKEY_base_id 158.Fa "EVP_PKEY *pkey" 159.Fc 160.Ft int 161.Fo EVP_PKEY_id 162.Fa "EVP_PKEY *pkey" 163.Fc 164.Ft int 165.Fo EVP_PKEY_type 166.Fa "int type" 167.Fc 168.Sh DESCRIPTION 169.Fn EVP_PKEY_set1_RSA , 170.Fn EVP_PKEY_set1_DSA , 171.Fn EVP_PKEY_set1_DH , 172and 173.Fn EVP_PKEY_set1_EC_KEY 174set the key referenced by 175.Fa pkey 176to 177.Fa key . 178.Pp 179.Fn EVP_PKEY_get1_RSA , 180.Fn EVP_PKEY_get1_DSA , 181.Fn EVP_PKEY_get1_DH , 182and 183.Fn EVP_PKEY_get1_EC_KEY 184return the key referenced in 185.Fa pkey , 186incrementing its reference count by 1, or 187.Dv NULL 188if the key is not of the correct type. 189.Pp 190.Fn EVP_PKEY_get0_RSA , 191.Fn EVP_PKEY_get0_DSA , 192.Fn EVP_PKEY_get0_DH , 193and 194.Fn EVP_PKEY_get0_EC_KEY 195are identical except that they do not increment the reference count. 196Consequently, the returned key must not be freed by the caller. 197.Pp 198.Fn EVP_PKEY_get0_hmac 199returns an internal pointer to the key referenced in 200.Fa pkey 201and sets 202.Pf * Fa len 203to its length in bytes. 204The returned pointer must not be freed by the caller. 205If 206.Fa pkey 207is not of the correct type, 208.Dv NULL 209is returned and the content of 210.Pf * Fa len 211becomes unspecified. 212.Pp 213.Fn EVP_PKEY_assign_RSA , 214.Fn EVP_PKEY_assign_DSA , 215.Fn EVP_PKEY_assign_DH , 216and 217.Fn EVP_PKEY_assign_EC_KEY 218also set the referenced key to 219.Fa key ; 220however these use the supplied 221.Fa key 222internally and so 223.Fa key 224will be freed when the parent 225.Fa pkey 226is freed. 227.Pp 228.Fn EVP_PKEY_base_id 229returns the type of 230.Fa pkey . 231For example, an RSA key will return 232.Dv EVP_PKEY_RSA . 233.Pp 234.Fn EVP_PKEY_id 235returns the actual OID associated with 236.Fa pkey . 237Historically keys using the same algorithm could use different OIDs. 238For example, an RSA key could use the OIDs corresponding to the NIDs 239.Dv NID_rsaEncryption 240(equivalent to 241.Dv EVP_PKEY_RSA ) 242or 243.Dv NID_rsa 244(equivalent to 245.Dv EVP_PKEY_RSA2 ) . 246The use of alternative non-standard OIDs is now rare, so 247.Dv EVP_PKEY_RSA2 248et al. are not often seen in practice. 249.Pp 250.Fn EVP_PKEY_type 251returns the underlying type of the NID 252.Fa type . 253For example, 254.Fn EVP_PKEY_type EVP_PKEY_RSA2 255will return 256.Dv EVP_PKEY_RSA . 257.Pp 258Most applications wishing to know a key type will simply call 259.Fn EVP_PKEY_base_id 260and will not care about the actual type, 261which will be identical in almost all cases. 262.Pp 263In accordance with the OpenSSL naming convention, the key obtained from 264or assigned to 265.Fa pkey 266using the 267.Sy 1 268functions must be freed as well as 269.Fa pkey . 270.Pp 271.Fn EVP_PKEY_assign_RSA , 272.Fn EVP_PKEY_assign_DSA , 273.Fn EVP_PKEY_assign_DH , 274and 275.Fn EVP_PKEY_assign_EC_KEY 276are implemented as macros. 277.Sh RETURN VALUES 278.Fn EVP_PKEY_set1_RSA , 279.Fn EVP_PKEY_set1_DSA , 280.Fn EVP_PKEY_set1_DH , 281and 282.Fn EVP_PKEY_set1_EC_KEY 283return 1 for success or 0 for failure. 284.Pp 285.Fn EVP_PKEY_get1_RSA , 286.Fn EVP_PKEY_get1_DSA , 287.Fn EVP_PKEY_get1_DH , 288.Fn EVP_PKEY_get1_EC_KEY , 289.Fn EVP_PKEY_get0_RSA , 290.Fn EVP_PKEY_get0_DSA , 291.Fn EVP_PKEY_get0_DH , 292.Fn EVP_PKEY_get0_EC_KEY , 293and 294.Fn EVP_PKEY_get0_hmac 295return the referenced key or 296.Dv NULL 297if an error occurred. 298.Pp 299.Fn EVP_PKEY_assign_RSA , 300.Fn EVP_PKEY_assign_DSA , 301.Fn EVP_PKEY_assign_DH , 302and 303.Fn EVP_PKEY_assign_EC_KEY 304return 1 for success and 0 for failure. 305.Pp 306.Fn EVP_PKEY_base_id , 307.Fn EVP_PKEY_id , 308and 309.Fn EVP_PKEY_type 310return a key type or 311.Dv NID_undef 312(equivalently 313.Dv EVP_PKEY_NONE ) 314on error. 315.Sh SEE ALSO 316.Xr DH_new 3 , 317.Xr DSA_new 3 , 318.Xr EC_KEY_new 3 , 319.Xr EVP_PKEY_get0_asn1 3 , 320.Xr EVP_PKEY_new 3 , 321.Xr RSA_new 3 322.Sh HISTORY 323.Fn EVP_PKEY_assign_RSA , 324.Fn EVP_PKEY_assign_DSA , 325.Fn EVP_PKEY_assign_DH , 326and 327.Fn EVP_PKEY_type 328first appeared in SSLeay 0.8.0 and have been available since 329.Ox 2.4 . 330.Pp 331.Fn EVP_PKEY_set1_RSA , 332.Fn EVP_PKEY_set1_DSA , 333.Fn EVP_PKEY_set1_DH , 334.Fn EVP_PKEY_get1_RSA , 335.Fn EVP_PKEY_get1_DSA , 336and 337.Fn EVP_PKEY_get1_DH 338first appeared in OpenSSL 0.9.5 and have been available since 339.Ox 2.7 . 340.Pp 341.Fn EVP_PKEY_set1_EC_KEY , 342.Fn EVP_PKEY_get1_EC_KEY , 343and 344.Fn EVP_PKEY_assign_EC_KEY 345first appeared in OpenSSL 0.9.8 and have been available since 346.Ox 4.5 . 347.Pp 348.Fn EVP_PKEY_id 349and 350.Fn EVP_PKEY_base_id 351first appeared in OpenSSL 1.0.0 and have been available since 352.Ox 4.9 . 353.Pp 354.Fn EVP_PKEY_get0_RSA , 355.Fn EVP_PKEY_get0_DSA , 356.Fn EVP_PKEY_get0_DH , 357and 358.Fn EVP_PKEY_get0_EC_KEY 359first appeared in OpenSSL 1.1.0 and have been available since 360.Ox 6.3 . 361.Pp 362.Fn EVP_PKEY_get0_hmac 363first appeared in OpenSSL 1.1.0 and has been available since 364.Ox 6.5 . 365