From 9b05507a1a92368662ba5ef3c2284ac2a4258bb9 Mon Sep 17 00:00:00 2001 From: schwarze Date: Tue, 19 Oct 2021 10:39:33 +0000 Subject: [PATCH] document X509_PKEY_new(3) and X509_PKEY_free(3) --- lib/libcrypto/man/PEM_X509_INFO_read.3 | 7 +- lib/libcrypto/man/X509_INFO_new.3 | 7 +- lib/libcrypto/man/X509_PKEY_new.3 | 92 ++++++++++++++++++++++++++ lib/libcrypto/man/X509_new.3 | 5 +- 4 files changed, 103 insertions(+), 8 deletions(-) create mode 100644 lib/libcrypto/man/X509_PKEY_new.3 diff --git a/lib/libcrypto/man/PEM_X509_INFO_read.3 b/lib/libcrypto/man/PEM_X509_INFO_read.3 index 0e908b79881..b3216a89b66 100644 --- a/lib/libcrypto/man/PEM_X509_INFO_read.3 +++ b/lib/libcrypto/man/PEM_X509_INFO_read.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: PEM_X509_INFO_read.3,v 1.3 2021/07/31 14:54:33 schwarze Exp $ +.\" $OpenBSD: PEM_X509_INFO_read.3,v 1.4 2021/10/19 10:39:33 schwarze Exp $ .\" .\" Copyright (c) 2020 Ingo Schwarze .\" @@ -14,7 +14,7 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: July 31 2021 $ +.Dd $Mdocdate: October 19 2021 $ .Dt PEM_X509_INFO_READ 3 .Os .Sh NAME @@ -162,7 +162,8 @@ may sometimes return 0 anyway. .Xr X509_CRL_new 3 , .Xr X509_INFO_new 3 , .Xr X509_LOOKUP_new 3 , -.Xr X509_new 3 +.Xr X509_new 3 , +.Xr X509_PKEY_new 3 .Sh HISTORY .Fn PEM_X509_INFO_read first appeared in SSLeay 0.5.1 and diff --git a/lib/libcrypto/man/X509_INFO_new.3 b/lib/libcrypto/man/X509_INFO_new.3 index 9c601ccb03f..1e9bb832f34 100644 --- a/lib/libcrypto/man/X509_INFO_new.3 +++ b/lib/libcrypto/man/X509_INFO_new.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: X509_INFO_new.3,v 1.2 2020/07/23 17:34:53 schwarze Exp $ +.\" $OpenBSD: X509_INFO_new.3,v 1.3 2021/10/19 10:39:33 schwarze Exp $ .\" Copyright (c) 2019 Ingo Schwarze .\" .\" Permission to use, copy, modify, and distribute this software for any @@ -13,7 +13,7 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: July 23 2020 $ +.Dd $Mdocdate: October 19 2021 $ .Dt X509_INFO_NEW 3 .Os .Sh NAME @@ -62,7 +62,8 @@ if an error occurs. .Sh SEE ALSO .Xr PEM_X509_INFO_read 3 , .Xr X509_CRL_new 3 , -.Xr X509_new 3 +.Xr X509_new 3 , +.Xr X509_PKEY_new 3 .Sh HISTORY .Fn X509_INFO_new and diff --git a/lib/libcrypto/man/X509_PKEY_new.3 b/lib/libcrypto/man/X509_PKEY_new.3 new file mode 100644 index 00000000000..253b0f6db5d --- /dev/null +++ b/lib/libcrypto/man/X509_PKEY_new.3 @@ -0,0 +1,92 @@ +.\" $OpenBSD: X509_PKEY_new.3,v 1.1 2021/10/19 10:39:33 schwarze Exp $ +.\" +.\" Copyright (c) 2021 Ingo Schwarze +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate: October 19 2021 $ +.Dt X509_PKEY_NEW 3 +.Os +.Sh NAME +.Nm X509_PKEY_new , +.Nm X509_PKEY_free +.Nd X.509 private key wrapper object +.Sh SYNOPSIS +.In openssl/x509.h +.Ft X509_PKEY * +.Fn X509_PKEY_new void +.Ft void +.Fn X509_PKEY_free "X509_PKEY *wrapper" +.Sh DESCRIPTION +.Vt X509_PKEY +is a reference-counted wrapper object that can store +.Bl -bullet -width 1n +.It +a pointer to an encrypted and ASN.1-encoded private key +.It +a pointer to an +.Vt EVP_PKEY +object representing the same key in decrypted form +.It +a pointer to an +.Vt X509_ALGOR +object identifying the algorithm used by the key +.El +.Pp +The object may contain only the encrypted key or only the decrypted +key or both. +.Pp +.Vt X509_PKEY +is used as a sub-object of the +.Vt X509_INFO +object created by +.Xr PEM_X509_INFO_read_bio 3 +if the PEM file contains any RSA, DSA, or EC PRIVATE KEY object. +.Pp +.Fn X509_PKEY_new +allocates and initializes an empty +.Vt X509_PKEY +object and sets its reference count to 1. +.Pp +.Fn X509_PKEY_free +decrements the reference count of the +.Fa wrapper +object by 1. +If the reference count reaches 0, +it frees all internal objects allocated by the +.Fa wrapper +as well as the storage needed for the +.Fa wrapper +object itself. +If +.Fa wrapper +is a +.Dv NULL +pointer, no action occurs. +.Sh RETURN VALUES +.Fn X509_PKEY_new +returns a pointer to the new +.Vt X509_PKEY +object or +.Dv NULL +if memory allocation fails. +.Sh SEE ALSO +.Xr EVP_PKEY_new 3 , +.Xr PEM_X509_INFO_read 3 , +.Xr X509_INFO_new 3 +.Sh HISTORY +.Fn X509_PKEY_new +and +.Fn X509_PKEY_free +first appeared in SSLeay 0.6.0 and have been available since +.Ox 2.4 . diff --git a/lib/libcrypto/man/X509_new.3 b/lib/libcrypto/man/X509_new.3 index 0afbae374ae..02f6d8bebe4 100644 --- a/lib/libcrypto/man/X509_new.3 +++ b/lib/libcrypto/man/X509_new.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: X509_new.3,v 1.30 2021/08/02 16:21:11 schwarze Exp $ +.\" $OpenBSD: X509_new.3,v 1.31 2021/10/19 10:39:33 schwarze Exp $ .\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 .\" .\" This file is a derived work. @@ -66,7 +66,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: August 2 2021 $ +.Dd $Mdocdate: October 19 2021 $ .Dt X509_NEW 3 .Os .Sh NAME @@ -195,6 +195,7 @@ if an error occurs. .Xr X509_LOOKUP_hash_dir 3 , .Xr X509_LOOKUP_new 3 , .Xr X509_NAME_new 3 , +.Xr X509_PKEY_new 3 , .Xr X509_policy_check 3 , .Xr X509_policy_tree_level_count 3 , .Xr X509_print_ex 3 , -- 2.20.1