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@.

3 files changed, 53 insertions, 18 deletions

diff --git a/src/lib/libcrypto/man/X509_LOOKUP_new.3 b/src/lib/libcrypto/man/X509_LOOKUP_new.3
index 6fa421b74f..e4cd68a40a 100644
--- a/src/lib/libcrypto/man/X509_LOOKUP_new.3
+++ b/src/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 <schwarze@openbsd.org>
 .\"
@@ -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/src/lib/libcrypto/man/X509_OBJECT_get0_X509.3 b/src/lib/libcrypto/man/X509_OBJECT_get0_X509.3
index ef3dbd1bba..9655e4b396 100644
--- a/src/lib/libcrypto/man/X509_OBJECT_get0_X509.3
+++ b/src/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 <schwarze@openbsd.org>
 .\"
 .\" 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/src/lib/libcrypto/man/X509_STORE_get_by_subject.3 b/src/lib/libcrypto/man/X509_STORE_get_by_subject.3
index f9da13fba4..797ddc1292 100644
--- a/src/lib/libcrypto/man/X509_STORE_get_by_subject.3
+++ b/src/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 <schwarze@openbsd.org>
 .\"
@@ -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 .