From 4819803b7fb67d38223277edb0a82cf117a5d7c7 Mon Sep 17 00:00:00 2001 From: schwarze Date: Thu, 18 Nov 2021 10:09:24 +0000 Subject: [PATCH] In x509_vfy.h rev. 1.35 and x509_lu.c rev. 1.34, tb@ provided X509_OBJECT_new(3) and X509_OBJECT_free(3); document them. While here, stop talking about storing storing EVP_PKEY objects and plain C strings in X509_OBJECT objects. LibreSSL never fully supported that, and it certainly no longer supports that now. --- lib/libcrypto/man/X509_OBJECT_get0_X509.3 | 59 ++++++++++++++++++----- lib/libcrypto/man/X509_new.3 | 5 +- 2 files changed, 51 insertions(+), 13 deletions(-) diff --git a/lib/libcrypto/man/X509_OBJECT_get0_X509.3 b/lib/libcrypto/man/X509_OBJECT_get0_X509.3 index 9655e4b396f..383c5ae5805 100644 --- a/lib/libcrypto/man/X509_OBJECT_get0_X509.3 +++ b/lib/libcrypto/man/X509_OBJECT_get0_X509.3 @@ -1,5 +1,6 @@ -.\" $OpenBSD: X509_OBJECT_get0_X509.3,v 1.12 2021/11/12 11:41:50 schwarze Exp $ -.\" Copyright (c) 2018 Ingo Schwarze +.\" $OpenBSD: X509_OBJECT_get0_X509.3,v 1.13 2021/11/18 10:09:24 schwarze Exp $ +.\" +.\" Copyright (c) 2018, 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 @@ -13,13 +14,15 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: November 12 2021 $ +.Dd $Mdocdate: November 18 2021 $ .Dt X509_OBJECT_GET0_X509 3 .Os .Sh NAME .Nm X509_OBJECT_get_type , +.Nm X509_OBJECT_new , .Nm X509_OBJECT_up_ref_count , .Nm X509_OBJECT_free_contents , +.Nm X509_OBJECT_free , .Nm X509_OBJECT_get0_X509 , .Nm X509_OBJECT_get0_X509_CRL , .Nm X509_OBJECT_idx_by_subject , @@ -32,6 +35,10 @@ .Fo X509_OBJECT_get_type .Fa "const X509_OBJECT *obj" .Fc +.Ft X509_OBJECT * +.Fo X509_OBJECT_new +.Fa void +.Fc .Ft int .Fo X509_OBJECT_up_ref_count .Fa "X509_OBJECT *obj" @@ -40,6 +47,10 @@ .Fo X509_OBJECT_free_contents .Fa "X509_OBJECT *obj" .Fc +.Ft void +.Fo X509_OBJECT_free +.Fa "X509_OBJECT *obj" +.Fc .Ft X509 * .Fo X509_OBJECT_get0_X509 .Fa "const X509_OBJECT *obj" @@ -70,13 +81,9 @@ The .Vt X509_OBJECT structure is a shallow wrapper around one .Vt X509 -certificate object, one +certificate object or one .Vt X509_CRL -certificate revocation list object, one -.Vt EVP_PKEY -private key object, or one -.Vt char * -string. +certificate revocation list object. The type of object stored at any given time can be inspected with .Fn X509_OBJECT_get_type . .Pp @@ -86,6 +93,15 @@ object uses one stack of .Vt X509_OBJECT structures as its main storage area. .Pp +.Fn X509_OBJECT_new +allocates a new +.Vt X509_OBJECT +structure. +It sets the object type to +.Dv X509_LU_NONE +and the pointer to the certificate or CRL to +.Dv NULL . +.Pp If .Fa obj contains an @@ -119,6 +135,13 @@ does not free .Fa obj itself. .Pp +.Fn X509_OBJECT_free +calls +.Fn X509_OBJECT_free_contents +and then frees the storage used for the +.Fa obj +itself. +.Pp If .Fa type is @@ -158,12 +181,18 @@ if .Fa obj contains a certificate, .Dv X509_LU_CRL -if it contains a certificate revocation list, -or 0 if an error occurs. +if it contains a certificate revocation list, or +.Dv X509_LU_NONE +if it contains neither. .Pp .Fn X509_OBJECT_up_ref_count returns 1 on success and 0 on failure. .Pp +.Fn X509_OBJECT_new +returns the new object or +.Dv NULL +if memory allocation fails. +.Pp .Fn X509_OBJECT_get0_X509 returns an internal pointer to the certificate contained in .Fa obj @@ -224,9 +253,11 @@ is .Dv NULL or no match is found. .Sh SEE ALSO +.Xr STACK_OF 3 , .Xr X509_CRL_new 3 , .Xr X509_LOOKUP_new 3 , .Xr X509_NAME_new 3 , +.Xr X509_new 3 , .Xr X509_STORE_get0_objects 3 , .Xr X509_STORE_get_by_subject 3 , .Xr X509_STORE_load_locations 3 , @@ -251,3 +282,9 @@ and .Fn X509_OBJECT_get0_X509_CRL first appeared in OpenSSL 1.1.0 and have been available since .Ox 6.3 . +.Pp +.Fn X509_OBJECT_new +and +.Fn X509_OBJECT_free +first appeared in OpenSSL 1.1.0 and have been available since +.Ox 7.1 . diff --git a/lib/libcrypto/man/X509_new.3 b/lib/libcrypto/man/X509_new.3 index 296e9b8cfc3..4b85f67eb07 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.35 2021/11/09 16:23:04 schwarze Exp $ +.\" $OpenBSD: X509_new.3,v 1.36 2021/11/18 10:09:24 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: November 9 2021 $ +.Dd $Mdocdate: November 18 2021 $ .Dt X509_NEW 3 .Os .Sh NAME @@ -227,6 +227,7 @@ if an error occurs. .Xr X509_LOOKUP_hash_dir 3 , .Xr X509_LOOKUP_new 3 , .Xr X509_NAME_new 3 , +.Xr X509_OBJECT_new 3 , .Xr X509_PKEY_new 3 , .Xr X509_policy_check 3 , .Xr X509_policy_tree_level_count 3 , -- 2.20.1