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 0de5520..248bd33 100644 (file)
--- 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 <bsd.own.mk>
 
@@ -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 (file)
index 0000000..8d39028
--- /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 <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: 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