1.\" $OpenBSD: EVP_PKEY_new.3,v 1.11 2019/06/07 19:59:11 schwarze Exp $ 2.\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 3.\" selective merge up to: OpenSSL df75c2bf Dec 9 01:02:36 2018 +0100 4.\" 5.\" This file was written by Dr. Stephen Henson <steve@openssl.org> 6.\" and Matt Caswell <matt@openssl.org>. 7.\" Copyright (c) 2002, 2018 The OpenSSL Project. All rights reserved. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 16.\" 2. Redistributions in binary form must reproduce the above copyright 17.\" notice, this list of conditions and the following disclaimer in 18.\" the documentation and/or other materials provided with the 19.\" distribution. 20.\" 21.\" 3. All advertising materials mentioning features or use of this 22.\" software must display the following acknowledgment: 23.\" "This product includes software developed by the OpenSSL Project 24.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 25.\" 26.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 27.\" endorse or promote products derived from this software without 28.\" prior written permission. For written permission, please contact 29.\" openssl-core@openssl.org. 30.\" 31.\" 5. Products derived from this software may not be called "OpenSSL" 32.\" nor may "OpenSSL" appear in their names without prior written 33.\" permission of the OpenSSL Project. 34.\" 35.\" 6. Redistributions of any form whatsoever must retain the following 36.\" acknowledgment: 37.\" "This product includes software developed by the OpenSSL Project 38.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 39.\" 40.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 41.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 42.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 43.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 44.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 45.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 46.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 47.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 48.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 49.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 50.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 51.\" OF THE POSSIBILITY OF SUCH DAMAGE. 52.\" 53.Dd $Mdocdate: June 7 2019 $ 54.Dt EVP_PKEY_NEW 3 55.Os 56.Sh NAME 57.Nm EVP_PKEY_new , 58.Nm EVP_PKEY_up_ref , 59.Nm EVP_PKEY_free , 60.Nm EVP_PKEY_new_mac_key 61.Nd private key allocation functions 62.Sh SYNOPSIS 63.In openssl/evp.h 64.Ft EVP_PKEY * 65.Fn EVP_PKEY_new void 66.Ft int 67.Fo EVP_PKEY_up_ref 68.Fa "EVP_PKEY *key" 69.Fc 70.Ft void 71.Fo EVP_PKEY_free 72.Fa "EVP_PKEY *key" 73.Fc 74.Ft EVP_PKEY * 75.Fo EVP_PKEY_new_mac_key 76.Fa "int type" 77.Fa "ENGINE *e" 78.Fa "const unsigned char *key" 79.Fa "int keylen" 80.Fc 81.Sh DESCRIPTION 82The 83.Vt EVP_PKEY 84structure is used by various OpenSSL functions which require a general 85private key without reference to any particular algorithm. 86.Pp 87The 88.Fn EVP_PKEY_new 89function allocates an empty 90.Vt EVP_PKEY 91structure. 92The reference count is set to 1. 93To add a private or public key to it, use the functions described in 94.Xr EVP_PKEY_set1_RSA 3 . 95.Pp 96.Fn EVP_PKEY_up_ref 97increments the reference count of 98.Fa key 99by 1. 100.Pp 101.Fn EVP_PKEY_free 102decrements the reference count of 103.Fa key 104by 1, and if the reference count reaches zero, frees it up. 105If 106.Fa key 107is a 108.Dv NULL 109pointer, no action occurs. 110.Pp 111.Fn EVP_PKEY_new_mac_key 112allocates a new 113.Vt EVP_PKEY . 114If 115.Fa e 116is 117.Pf non- Dv NULL , 118then the new 119.Vt EVP_PKEY 120structure is associated with the engine 121.Fa e . 122The 123.Fa type 124argument indicates what kind of key this is. 125The value should be a NID for a public key algorithm that supports 126raw private keys, for example 127.Dv EVP_PKEY_HMAC . 128.Fa key 129points to the raw private key data for this 130.Vt EVP_PKEY 131which should be of length 132.Fa keylen . 133The length should be appropriate for the type of the key. 134The public key data will be automatically derived from the given 135private key data (if appropriate for the algorithm type). 136.Sh RETURN VALUES 137.Fn EVP_PKEY_new 138and 139.Fn EVP_PKEY_new_mac_key 140return either the newly allocated 141.Vt EVP_PKEY 142structure or 143.Dv NULL 144if an error occurred. 145.Pp 146.Fn EVP_PKEY_up_ref 147returns 1 for success or 0 for failure. 148.Sh SEE ALSO 149.Xr d2i_PrivateKey 3 , 150.Xr evp 3 , 151.Xr EVP_PKEY_asn1_new 3 , 152.Xr EVP_PKEY_cmp 3 , 153.Xr EVP_PKEY_CTX_new 3 , 154.Xr EVP_PKEY_get_default_digest_nid 3 , 155.Xr EVP_PKEY_meth_new 3 , 156.Xr EVP_PKEY_print_private 3 , 157.Xr EVP_PKEY_set1_RSA 3 158.Sh HISTORY 159.Fn EVP_PKEY_new 160and 161.Fn EVP_PKEY_free 162first appeared in SSLeay 0.6.0 and have been available since 163.Ox 2.4 . 164.Pp 165.Fn EVP_PKEY_new_mac_key 166first appeared in OpenSSL 1.0.0 and has been available since 167.Ox 4.9 . 168.Pp 169.Fn EVP_PKEY_up_ref 170first appeared in OpenSSL 1.1.0 and has been available since 171.Ox 6.3 . 172