From: schwarze Date: Sun, 25 Feb 2018 20:26:51 +0000 (+0000) Subject: In x509_vfy.h rev. 1.23 2018/02/22 17:17:09, jsing@ provided X-Git-Url: http://artulab.com/gitweb/?a=commitdiff_plain;h=c2fe39a3d9075a4753fd0a35c92c2d03984c8172;p=openbsd In x509_vfy.h rev. 1.23 2018/02/22 17:17:09, jsing@ provided X509_OBJECT_get0_X509(3) and X509_OBJECT_get0_X509_CRL(3). Since they are undocumented in OpenSSL, write a new manual page from scratch, also documenting five closely related public functions that have already been available before. --- diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile index 0de55209bb6..248bd33c8d9 100644 --- a/lib/libcrypto/man/Makefile +++ b/lib/libcrypto/man/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.134 2018/02/25 17:46:38 schwarze Exp $ +# $OpenBSD: Makefile,v 1.135 2018/02/25 20:26:51 schwarze Exp $ .include @@ -222,6 +222,7 @@ MAN= \ X509_NAME_get_index_by_NID.3 \ X509_NAME_new.3 \ X509_NAME_print_ex.3 \ + X509_OBJECT_get0_X509.3 \ X509_PUBKEY_new.3 \ X509_REQ_new.3 \ X509_REVOKED_new.3 \ diff --git a/lib/libcrypto/man/X509_OBJECT_get0_X509.3 b/lib/libcrypto/man/X509_OBJECT_get0_X509.3 new file mode 100644 index 00000000000..8d39028b8e8 --- /dev/null +++ b/lib/libcrypto/man/X509_OBJECT_get0_X509.3 @@ -0,0 +1,216 @@ +.\" $OpenBSD: X509_OBJECT_get0_X509.3,v 1.1 2018/02/25 20:26:51 schwarze Exp $ +.\" Copyright (c) 2018 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: February 25 2018 $ +.Dt X509_OBJECT_GET0_X509 3 +.Os +.Sh NAME +.Nm X509_OBJECT_up_ref_count , +.Nm X509_OBJECT_free_contents , +.Nm X509_OBJECT_get0_X509 , +.Nm X509_OBJECT_get0_X509_CRL , +.Nm X509_OBJECT_idx_by_subject , +.Nm X509_OBJECT_retrieve_by_subject , +.Nm X509_OBJECT_retrieve_match +.Nd certificate, CRL, private key, and string wrapper for certificate stores +.Sh SYNOPSIS +.In openssl/x509_vfy.h +.Ft void +.Fo X509_OBJECT_up_ref_count +.Fa "X509_OBJECT *obj" +.Fc +.Ft void +.Fo X509_OBJECT_free_contents +.Fa "X509_OBJECT *obj" +.Fc +.Ft X509 * +.Fo X509_OBJECT_get0_X509 +.Fa "const X509_OBJECT *obj" +.Fc +.Ft X509_CRL * +.Fo X509_OBJECT_get0_X509_CRL +.Fa "X509_OBJECT *obj" +.Fc +.Ft int +.Fo X509_OBJECT_idx_by_subject +.Fa "STACK_OF(X509_OBJECT) *stack" +.Fa "int 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_NAME *name" +.Fc +.Ft X509_OBJECT * +.Fo X509_OBJECT_retrieve_match +.Fa "STACK_OF(X509_OBJECT) *stack" +.Fa "X509_OBJECT *obj" +.Fc +.Sh DESCRIPTION +The +.Vt X509_OBJECT +structure is a shallow wrapper around one +.Vt X509 +certificate object, one +.Vt X509_CRL +certificate revocation list object, one +.Vt EVP_PKEY +private key object, or one +.Vt char * +string. +It also remembers which type of object it contains at any given time. +.Pp +Each +.Vt X509_STORE +object uses one stack of +.Vt X509_OBJECT +structures as its main storage area. +.Pp +If +.Fa obj +contains an +.Vt X509 +certificate or an +.Vt X509_CRL +certificate revocation list, +.Fn X509_OBJECT_up_ref_count +increments the reference count of that inner object by 1. +Otherwise, no action occurs. +.Pp +If +.Fa obj +contains an +.Vt X509 +certificate, +.Fn X509_OBJECT_free_contents +calls +.Xr X509_free 3 +on that inner object. +If +.Fa obj +contains an +.Vt X509_CRL +certificate revocation list, it calls +.Xr X509_CRL_free 3 +on that inner list. +Otherwise, no action occurs. +.Fn X509_OBJECT_free_contents +does not free +.Fa obj +itself. +.Pp +If +.Fa type +is +.Dv X509_LU_X509 , +.Fn X509_OBJECT_idx_by_subject +and +.Fn X509_OBJECT_retrieve_by_subject +search the given +.Fa stack +for a certificate with the subject +.Fa name . +If +.Fa type +is +.Dv X509_LU_CRL , +they search for a certificate revocation list with the issuer +.Fa name +instead. +.Pp +If +.Fa obj +contains a certificate, +.Fn X509_OBJECT_retrieve_match +searches the given +.Fa stack +for a certificate with a matching subject name; +if it contains a certificate revocation list, it searches for a +certificate revocation list with a matching issuer name instead; +otherwise, it searches for an +.Vt X509_OBJECT +with a matching type. +.Sh RETURN VALUES +.Fn X509_OBJECT_get0_X509 +returns an internal pointer to the certificate contained in +.Fa obj +or +.Dv NULL +if +.Fa obj +is +.Dv NULL +or contains no certificate. +.Pp +.Fn X509_OBJECT_get0_X509_CRL +returns an internal pointer to the certificate revocation list contained in +.Fa obj +or +.Dv NULL +if +.Fa obj +is +.Dv NULL +or contains no certificate revocation list. +.Pp +.Fn X509_OBJECT_idx_by_subject +returns the zero-based index of the first matching certificate +or revocation list in the +.Fa stack +or \-1 if +.Fa type +is neither +.Dv X509_LU_X509 +nor +.Dv X509_LU_CRL +or if no match is found. +.Pp +.Fn X509_OBJECT_retrieve_by_subject +returns the first matching certificate or revocation list in the +.Fa stack +or +.Dv NULL +if +.Fa type +is neither +.Dv X509_LU_X509 +nor +.Dv X509_LU_CRL +or if no match is found. +.Pp +.Fn X509_OBJECT_retrieve_match +returns the first mathching +.Vt X509_OBJECT +or +.Dv NULL +if +.Fa stack +or +.Fa obj +is +.Dv NULL +or no match is found. +.Sh SEE ALSO +.Xr X509_STORE_load_locations 3 , +.Xr X509_STORE_new 3 +.\" The type X509_OBJECT is also used +.\" by the following undocumented public functions: +.\" X509_STORE_get_by_subject +.\" X509_LOOKUP_by_subject +.\" X509_LOOKUP_by_issuer_serial +.\" X509_LOOKUP_by_fingerprint +.\" X509_LOOKUP_by_alias