From: schwarze Date: Mon, 2 Aug 2021 16:21:11 +0000 (+0000) Subject: new manual page X509_STORE_get_by_subject(3) X-Git-Url: http://artulab.com/gitweb/?a=commitdiff_plain;h=84b283a32479b279b79a2b05fef921323b7a3c50;p=openbsd new manual page X509_STORE_get_by_subject(3) --- diff --git a/lib/libcrypto/man/X509_CRL_new.3 b/lib/libcrypto/man/X509_CRL_new.3 index d6a43f17416..4d3f97afdb4 100644 --- a/lib/libcrypto/man/X509_CRL_new.3 +++ b/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 .\" @@ -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/lib/libcrypto/man/X509_OBJECT_get0_X509.3 b/lib/libcrypto/man/X509_OBJECT_get0_X509.3 index fc51696ac8d..ef3dbd1bbac 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.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 .\" .\" 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/lib/libcrypto/man/X509_STORE_CTX_new.3 b/lib/libcrypto/man/X509_STORE_CTX_new.3 index 1bc90b5ac49..f2850451944 100644 --- a/lib/libcrypto/man/X509_STORE_CTX_new.3 +++ b/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/lib/libcrypto/man/X509_STORE_get_by_subject.3 b/lib/libcrypto/man/X509_STORE_get_by_subject.3 new file mode 100644 index 00000000000..f9da13fba40 --- /dev/null +++ b/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 +.\" +.\" 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/lib/libcrypto/man/X509_new.3 b/lib/libcrypto/man/X509_new.3 index efd4db53595..0afbae374ae 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.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