From 6d5a2d04c5227254c667f877bc27f9c915aa8611 Mon Sep 17 00:00:00 2001 From: schwarze Date: Fri, 12 Nov 2021 11:41:50 +0000 Subject: [PATCH] In x509_vfy.h rev. 1.41, tb@ provided X509_STORE_CTX_get_by_subject(3), changed the return type of X509_OBJECT_get_type(3) and argument types of X509_LOOKUP_by_subject(3), X509_LOOKUP_by_issuer_serial(3), X509_LOOKUP_by_fingerprint(3), X509_LOOKUP_by_alias(3), X509_OBJECT_idx_by_subject(3), X509_OBJECT_retrieve_by_subject(3), and X509_STORE_get_by_subject(3) from int to X509_LOOKUP_TYPE, and in rev. 1.42, he provided X509_STORE_CTX_get_obj_by_subject(3). Adjust the documentation. Joint work with and OK tb@. --- lib/libcrypto/man/X509_LOOKUP_new.3 | 12 ++--- lib/libcrypto/man/X509_OBJECT_get0_X509.3 | 10 ++-- lib/libcrypto/man/X509_STORE_get_by_subject.3 | 49 ++++++++++++++++--- 3 files changed, 53 insertions(+), 18 deletions(-) diff --git a/lib/libcrypto/man/X509_LOOKUP_new.3 b/lib/libcrypto/man/X509_LOOKUP_new.3 index 6fa421b74f9..e4cd68a40af 100644 --- a/lib/libcrypto/man/X509_LOOKUP_new.3 +++ b/lib/libcrypto/man/X509_LOOKUP_new.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: X509_LOOKUP_new.3,v 1.7 2021/11/09 16:23:04 schwarze Exp $ +.\" $OpenBSD: X509_LOOKUP_new.3,v 1.8 2021/11/12 11:41:50 schwarze Exp $ .\" .\" Copyright (c) 2021 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: November 9 2021 $ +.Dd $Mdocdate: November 12 2021 $ .Dt X509_LOOKUP_NEW 3 .Os .Sh NAME @@ -73,7 +73,7 @@ .Ft int .Fo X509_LOOKUP_by_subject .Fa "X509_LOOKUP *lookup" -.Fa "int type" +.Fa "X509_LOOKUP_TYPE type" .Fa "X509_NAME *name" .Fa "X509_OBJECT *object" .Fc @@ -84,7 +84,7 @@ .Ft int .Fo X509_LOOKUP_by_issuer_serial .Fa "X509_LOOKUP *lookup" -.Fa "int type" +.Fa "X509_LOOKUP_TYPE type" .Fa "X509_NAME *name" .Fa "ASN1_INTEGER *serial" .Fa "X509_OBJECT *object" @@ -92,7 +92,7 @@ .Ft int .Fo X509_LOOKUP_by_fingerprint .Fa "X509_LOOKUP *lookup" -.Fa "int type" +.Fa "X509_LOOKUP_TYPE type" .Fa "const unsigned char *bytes" .Fa "int length" .Fa "X509_OBJECT *object" @@ -100,7 +100,7 @@ .Ft int .Fo X509_LOOKUP_by_alias .Fa "X509_LOOKUP *lookup" -.Fa "int type" +.Fa "X509_LOOKUP_TYPE type" .Fa "const char *string" .Fa "int length" .Fa "X509_OBJECT *object" diff --git a/lib/libcrypto/man/X509_OBJECT_get0_X509.3 b/lib/libcrypto/man/X509_OBJECT_get0_X509.3 index ef3dbd1bbac..9655e4b396f 100644 --- a/lib/libcrypto/man/X509_OBJECT_get0_X509.3 +++ b/lib/libcrypto/man/X509_OBJECT_get0_X509.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: X509_OBJECT_get0_X509.3,v 1.11 2021/08/02 16:21:11 schwarze Exp $ +.\" $OpenBSD: X509_OBJECT_get0_X509.3,v 1.12 2021/11/12 11:41:50 schwarze Exp $ .\" Copyright (c) 2018 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: August 2 2021 $ +.Dd $Mdocdate: November 12 2021 $ .Dt X509_OBJECT_GET0_X509 3 .Os .Sh NAME @@ -28,7 +28,7 @@ .Nd certificate, CRL, private key, and string wrapper for certificate stores .Sh SYNOPSIS .In openssl/x509_vfy.h -.Ft int +.Ft X509_LOOKUP_TYPE .Fo X509_OBJECT_get_type .Fa "const X509_OBJECT *obj" .Fc @@ -51,13 +51,13 @@ .Ft int .Fo X509_OBJECT_idx_by_subject .Fa "STACK_OF(X509_OBJECT) *stack" -.Fa "int type" +.Fa "X509_LOOKUP_TYPE type" .Fa "X509_NAME *name" .Fc .Ft X509_OBJECT * .Fo X509_OBJECT_retrieve_by_subject .Fa "STACK_OF(X509_OBJECT) *stack" -.Fa "int type" +.Fa "X509_LOOKUP_TYPE type" .Fa "X509_NAME *name" .Fc .Ft X509_OBJECT * diff --git a/lib/libcrypto/man/X509_STORE_get_by_subject.3 b/lib/libcrypto/man/X509_STORE_get_by_subject.3 index f9da13fba40..797ddc12926 100644 --- a/lib/libcrypto/man/X509_STORE_get_by_subject.3 +++ b/lib/libcrypto/man/X509_STORE_get_by_subject.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: X509_STORE_get_by_subject.3,v 1.1 2021/08/02 16:21:11 schwarze Exp $ +.\" $OpenBSD: X509_STORE_get_by_subject.3,v 1.2 2021/11/12 11:41:50 schwarze Exp $ .\" .\" Copyright (c) 2021 Ingo Schwarze .\" @@ -14,10 +14,12 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: August 2 2021 $ +.Dd $Mdocdate: November 12 2021 $ .Dt X509_STORE_GET_BY_SUBJECT 3 .Os .Sh NAME +.Nm X509_STORE_CTX_get_by_subject , +.Nm X509_STORE_CTX_get_obj_by_subject , .Nm X509_STORE_get_by_subject , .Nm X509_STORE_get1_certs , .Nm X509_STORE_get1_crls , @@ -26,9 +28,22 @@ .Sh SYNOPSIS .In openssl/x509_vfy.h .Ft int +.Fo X509_STORE_CTX_get_by_subject +.Fa "X509_STORE_CTX *ctx" +.Fa "X509_LOOKUP_TYPE type" +.Fa "X509_NAME *name" +.Fa "X509_OBJECT *object" +.Fc +.Ft X509_OBJECT * +.Fo X509_STORE_CTX_get_obj_by_subject +.Fa "X509_STORE_CTX *ctx" +.Fa "X509_LOOKUP_TYPE type" +.Fa "X509_NAME *name" +.Fc +.Ft int .Fo X509_STORE_get_by_subject .Fa "X509_STORE_CTX *ctx" -.Fa "int type" +.Fa "X509_LOOKUP_TYPE type" .Fa "X509_NAME *name" .Fa "X509_OBJECT *object" .Fc @@ -49,7 +64,7 @@ .Fa "X509 *certificate" .Fc .Sh DESCRIPTION -.Fn X509_STORE_get_by_subject +.Fn X509_STORE_CTX_get_by_subject retrieves the first object having a matching .Fa type and @@ -83,6 +98,13 @@ Avoiding a memory leak by making sure the provided .Fa object is empty is the responsibility of the caller. .Pp +.Fn X509_STORE_CTX_get_obj_by_subject +is similar except that a new object is allocated and returned. +.Pp +.Fn X509_STORE_get_by_subject +is a deprecated alias for +.Fn X509_STORE_CTX_get_by_subject . +.Pp .Fn X509_STORE_get1_certs retrieves all certificates matching the subject .Vt name @@ -130,10 +152,12 @@ encourage checking of validity times, CAs with a valid time are preferred, but if no matching CA has a valid time, one with an invalid time is accepted anyway. .Sh RETURN VALUES +.Fn X509_STORE_CTX_get_by_subject +and .Fn X509_STORE_get_by_subject -returns 1 if a match is found or 0 on failure. +return 1 if a match is found or 0 on failure. In addition to simply not finding a match, -it may also fail due to memory allocation failure in +they may also fail due to memory allocation failure in .Xr X509_LOOKUP_by_subject 3 . If .Fa ctx @@ -141,7 +165,12 @@ contains any .Vt X509_LOOKUP object using a user-defined .Vt X509_LOOKUP_METHOD , -it might also return negative values for internal errors. +they might also return negative values for internal errors. +.Pp +.Fn X509_STORE_CTX_get_obj_by_subject +returns the new object or +.Dv NULL +on failure, in particular if no match is found or memory allocation fails. .Pp .Fn X509_STORE_get1_certs returns a newly allocated and populated array of certificates or @@ -197,3 +226,9 @@ and .Fn X509_STORE_get1_crls first appeared in OpenSSL 1.0.0 and have been available since .Ox 4.9 . +.Pp +.Fn X509_STORE_CTX_get_by_subject +and +.Fn X509_STORE_CTX_get_obj_by_subject +first appeared in OpenSSL 1.1.0 and have been available since +.Ox 7.1 . -- 2.20.1