1.\" $OpenBSD: X509_PKEY_new.3,v 1.1 2021/10/19 10:39:33 schwarze Exp $ 2.\" 3.\" Copyright (c) 2021 Ingo Schwarze <schwarze@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: October 19 2021 $ 18.Dt X509_PKEY_NEW 3 19.Os 20.Sh NAME 21.Nm X509_PKEY_new , 22.Nm X509_PKEY_free 23.Nd X.509 private key wrapper object 24.Sh SYNOPSIS 25.In openssl/x509.h 26.Ft X509_PKEY * 27.Fn X509_PKEY_new void 28.Ft void 29.Fn X509_PKEY_free "X509_PKEY *wrapper" 30.Sh DESCRIPTION 31.Vt X509_PKEY 32is a reference-counted wrapper object that can store 33.Bl -bullet -width 1n 34.It 35a pointer to an encrypted and ASN.1-encoded private key 36.It 37a pointer to an 38.Vt EVP_PKEY 39object representing the same key in decrypted form 40.It 41a pointer to an 42.Vt X509_ALGOR 43object identifying the algorithm used by the key 44.El 45.Pp 46The object may contain only the encrypted key or only the decrypted 47key or both. 48.Pp 49.Vt X509_PKEY 50is used as a sub-object of the 51.Vt X509_INFO 52object created by 53.Xr PEM_X509_INFO_read_bio 3 54if the PEM file contains any RSA, DSA, or EC PRIVATE KEY object. 55.Pp 56.Fn X509_PKEY_new 57allocates and initializes an empty 58.Vt X509_PKEY 59object and sets its reference count to 1. 60.Pp 61.Fn X509_PKEY_free 62decrements the reference count of the 63.Fa wrapper 64object by 1. 65If the reference count reaches 0, 66it frees all internal objects allocated by the 67.Fa wrapper 68as well as the storage needed for the 69.Fa wrapper 70object itself. 71If 72.Fa wrapper 73is a 74.Dv NULL 75pointer, no action occurs. 76.Sh RETURN VALUES 77.Fn X509_PKEY_new 78returns a pointer to the new 79.Vt X509_PKEY 80object or 81.Dv NULL 82if memory allocation fails. 83.Sh SEE ALSO 84.Xr EVP_PKEY_new 3 , 85.Xr PEM_X509_INFO_read 3 , 86.Xr X509_INFO_new 3 87.Sh HISTORY 88.Fn X509_PKEY_new 89and 90.Fn X509_PKEY_free 91first appeared in SSLeay 0.6.0 and have been available since 92.Ox 2.4 . 93