new manual page X509_STORE_get_by_subject(3)

5 files changed, 212 insertions, 12 deletions

diff --git a/src/lib/libcrypto/man/X509_CRL_new.3 b/src/lib/libcrypto/man/X509_CRL_new.3
index d6a43f1741..4d3f97afdb 100644
--- a/src/lib/libcrypto/man/X509_CRL_new.3
+++ b/src/lib/libcrypto/man/X509_CRL_new.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: X509_CRL_new.3,v 1.11 2021/07/19 13:16:43 schwarze Exp $
+.\" $OpenBSD: X509_CRL_new.3,v 1.12 2021/08/02 16:21:11 schwarze Exp $
 .\"
 .\" Copyright (c) 2016, 2018 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: July 19 2021 $
+.Dd $Mdocdate: August 2 2021 $
 .Dt X509_CRL_NEW 3
 .Os
 .Sh NAME
@@ -120,7 +120,8 @@ returns 1 on success or 0 on error.
 .Xr X509_new 3 ,
 .Xr X509_OBJECT_get0_X509_CRL 3 ,
 .Xr X509_REVOKED_new 3 ,
-.Xr X509_STORE_CTX_set0_crls 3
+.Xr X509_STORE_CTX_set0_crls 3 ,
+.Xr X509_STORE_get1_crls 3
 .Sh STANDARDS
 RFC 5280: Internet X.509 Public Key Infrastructure Certificate and
 Certificate Revocation List (CRL) Profile, section 5: CRL and CRL
diff --git a/src/lib/libcrypto/man/X509_OBJECT_get0_X509.3 b/src/lib/libcrypto/man/X509_OBJECT_get0_X509.3
index fc51696ac8..ef3dbd1bba 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.10 2021/07/31 14:54:34 schwarze Exp $
+.\" $OpenBSD: X509_OBJECT_get0_X509.3,v 1.11 2021/08/02 16:21:11 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: July 31 2021 $
+.Dd $Mdocdate: August 2 2021 $
 .Dt X509_OBJECT_GET0_X509 3
 .Os
 .Sh NAME
@@ -228,11 +228,9 @@ or no match is found.
 .Xr X509_LOOKUP_new 3 ,
 .Xr X509_NAME_new 3 ,
 .Xr X509_STORE_get0_objects 3 ,
+.Xr X509_STORE_get_by_subject 3 ,
 .Xr X509_STORE_load_locations 3 ,
 .Xr X509_STORE_new 3
-.\" The type X509_OBJECT is also used
-.\" by the following undocumented public function:
-.\" X509_STORE_get_by_subject
 .Sh HISTORY
 .Fn X509_OBJECT_up_ref_count
 and
diff --git a/src/lib/libcrypto/man/X509_STORE_CTX_new.3 b/src/lib/libcrypto/man/X509_STORE_CTX_new.3
index 1bc90b5ac4..f285045194 100644
--- a/src/lib/libcrypto/man/X509_STORE_CTX_new.3
+++ b/src/lib/libcrypto/man/X509_STORE_CTX_new.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: X509_STORE_CTX_new.3,v 1.23 2021/07/22 19:09:26 schwarze Exp $
+.\" $OpenBSD: X509_STORE_CTX_new.3,v 1.24 2021/08/02 16:21:11 schwarze Exp $
 .\" full merge up to: OpenSSL aae41f8c Jun 25 09:47:15 2015 +0100
 .\" selective merge up to: OpenSSL 24a535ea Sep 22 13:14:20 2020 +0100
 .\"
@@ -67,7 +67,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: July 22 2021 $
+.Dd $Mdocdate: August 2 2021 $
 .Dt X509_STORE_CTX_NEW 3
 .Os
 .Sh NAME
@@ -319,6 +319,7 @@ if no set of additional certificates was provided.
 .Xr X509_STORE_CTX_get_error 3 ,
 .Xr X509_STORE_CTX_get_ex_new_index 3 ,
 .Xr X509_STORE_CTX_set_flags 3 ,
+.Xr X509_STORE_get_by_subject 3 ,
 .Xr X509_STORE_new 3 ,
 .Xr X509_STORE_set1_param 3 ,
 .Xr X509_verify_cert 3 ,
diff --git a/src/lib/libcrypto/man/X509_STORE_get_by_subject.3 b/src/lib/libcrypto/man/X509_STORE_get_by_subject.3
new file mode 100644
index 0000000000..f9da13fba4
--- /dev/null
+++ b/src/lib/libcrypto/man/X509_STORE_get_by_subject.3
@@ -0,0 +1,199 @@
+.\" $OpenBSD: X509_STORE_get_by_subject.3,v 1.1 2021/08/02 16:21:11 schwarze Exp $
+.\"
+.\" Copyright (c) 2021 Ingo Schwarze <schwarze@openbsd.org>
+.\"
+.\" 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: August 2 2021 $
+.Dt X509_STORE_GET_BY_SUBJECT 3
+.Os
+.Sh NAME
+.Nm X509_STORE_get_by_subject ,
+.Nm X509_STORE_get1_certs ,
+.Nm X509_STORE_get1_crls ,
+.Nm X509_STORE_CTX_get1_issuer
+.Nd retrieve objects from a certificate store
+.Sh SYNOPSIS
+.In openssl/x509_vfy.h
+.Ft int
+.Fo X509_STORE_get_by_subject
+.Fa "X509_STORE_CTX *ctx"
+.Fa "int type"
+.Fa "X509_NAME *name"
+.Fa "X509_OBJECT *object"
+.Fc
+.Ft STACK_OF(X509) *
+.Fo X509_STORE_get1_certs
+.Fa "X509_STORE_CTX *ctx"
+.Fa "X509_NAME *name"
+.Fc
+.Ft STACK_OF(X509_CRL) *
+.Fo X509_STORE_get1_crls
+.Fa "X509_STORE_CTX *ctx"
+.Fa "X509_NAME *name"
+.Fc
+.Ft int
+.Fo X509_STORE_CTX_get1_issuer
+.Fa "X509 **issuer"
+.Fa "X509_STORE_CTX *ctx"
+.Fa "X509 *certificate"
+.Fc
+.Sh DESCRIPTION
+.Fn X509_STORE_get_by_subject
+retrieves the first object having a matching
+.Fa type
+and
+.Fa name
+from the
+.Vt X509_STORE
+associated with the
+.Fa ctx .
+The
+.Fa type
+can be
+.Dv X509_LU_X509
+to retrieve a certificate or
+.Dv X509_LU_CRL
+to retrieve a revocation list.
+.Pp
+If the store does not yet contain a matching object or if the type is
+.Dv X509_LU_CRL ,
+.Xr X509_LOOKUP_by_subject 3
+is called on
+.Vt X509_LOOKUP
+objects associated with the store until a match is found,
+which may add zero or more objects to the store.
+.Pp
+In case of success, the content of the
+.Fa object
+provided by the caller is overwritten with a pointer to the first
+match, and the reference count of that certificate or revocation
+list is incremented by 1.
+Avoiding a memory leak by making sure the provided
+.Fa object
+is empty is the responsibility of the caller.
+.Pp
+.Fn X509_STORE_get1_certs
+retrieves all certificates matching the subject
+.Vt name
+from the
+.Vt X509_STORE
+associated with
+.Fa ctx .
+If there are none yet,
+.Fn X509_STORE_get_by_subject
+is called to try and add some.
+In case of success, the reference counts of all certificates
+added to the returned array are incremented by 1.
+.Pp
+.Fn X509_STORE_get1_crls
+is similar except that it operates on certificate revocation lists
+rather than on certificates and that it always calls
+.Fn X509_STORE_get_by_subject ,
+even if the
+.Vt X509_STORE
+already contains a matching revocation list.
+.Pp
+.Fn X509_STORE_CTX_get1_issuer
+retrieves the
+.Fa issuer
+CA certificate for the given
+.Fa certificate
+from the
+.Vt X509_STORE
+associated with
+.Fa ctx .
+Internally, the issuer name is retrieved with
+.Xr X509_get_issuer_name 3
+and the candidate issuer CA certificate with
+.Fn X509_STORE_get_by_subject
+using that issuer name.
+.Xr X509_check_issued 3
+or a user-supplied replacement function is used to check whether the
+.Fa certificate
+was indeed issued using the
+.Fa issuer
+CA certificate before returning it.
+If verification parameters associated with
+.Fa ctx
+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_get_by_subject
+returns 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
+.Xr X509_LOOKUP_by_subject 3 .
+If
+.Fa ctx
+contains any
+.Vt X509_LOOKUP
+object using a user-defined
+.Vt X509_LOOKUP_METHOD ,
+it might also return negative values for internal errors.
+.Pp
+.Fn X509_STORE_get1_certs
+returns a newly allocated and populated array of certificates or
+.Dv NULL
+on failure.
+It fails if no match is found, if
+.Fn X509_STORE_get_by_subject
+fails, or if memory allocation fails.
+.Pp
+.Fn X509_STORE_get1_crls
+returns a newly allocated and populated array of CRLs or
+.Dv NULL
+on failure.
+It fails if
+.Fn X509_STORE_get_by_subject
+finds no new match, even if the associated
+.Vt X509_STORE
+already contains matching CRLs, or if memory allocation fails.
+.Pp
+.Fn X509_STORE_CTX_get1_issuer
+returns 1 if a matching
+.Fa issuer
+CA certificate is found or 0 otherwise.
+If
+.Fa ctx
+contains any
+.Vt X509_LOOKUP
+object using a user-defined
+.Vt X509_LOOKUP_METHOD ,
+it might also return negative values for internal errors.
+.Sh SEE ALSO
+.Xr STACK_OF 3 ,
+.Xr X509_check_issued 3 ,
+.Xr X509_CRL_new 3 ,
+.Xr X509_get_issuer_name 3 ,
+.Xr X509_LOOKUP_by_subject 3 ,
+.Xr X509_NAME_new 3 ,
+.Xr X509_new 3 ,
+.Xr X509_OBJECT_retrieve_by_subject 3 ,
+.Xr X509_STORE_CTX_new 3 ,
+.Xr X509_VERIFY_PARAM_set_flags 3
+.Sh HISTORY
+.Fn X509_STORE_get_by_subject
+first appeared in SSLeay 0.8.0 and has been available since
+.Ox 2.4 .
+.Pp
+.Fn X509_STORE_CTX_get1_issuer
+first appeared in OpenSSL 0.9.6 and has been available since
+.Ox 2.9 .
+.Pp
+.Fn X509_STORE_get1_certs
+and
+.Fn X509_STORE_get1_crls
+first appeared in OpenSSL 1.0.0 and have been available since
+.Ox 4.9 .
diff --git a/src/lib/libcrypto/man/X509_new.3 b/src/lib/libcrypto/man/X509_new.3
index efd4db5359..0afbae374a 100644
--- a/src/lib/libcrypto/man/X509_new.3
+++ b/src/lib/libcrypto/man/X509_new.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: X509_new.3,v 1.29 2021/07/31 14:54:34 schwarze Exp $
+.\" $OpenBSD: X509_new.3,v 1.30 2021/08/02 16:21:11 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: July 31 2021 $
+.Dd $Mdocdate: August 2 2021 $
 .Dt X509_NEW 3
 .Os
 .Sh NAME
@@ -204,6 +204,7 @@ if an error occurs.
 .Xr X509_SIG_new 3 ,
 .Xr X509_sign 3 ,
 .Xr X509_STORE_CTX_new 3 ,
+.Xr X509_STORE_get_by_subject 3 ,
 .Xr X509_STORE_new 3 ,
 .Xr X509_TRUST_set 3
 .Sh STANDARDS