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.
author: schwarze <> 2018-02-25 20:26:51 +0000
committer: schwarze <> 2018-02-25 20:26:51 +0000
commit: 8563c14fedd67e6d767175f2cf0815ef16997da6 (patch)
tree: dae2bebce16c52806aa63ea1b99ca97c88fb3121 /src
parent: 50c45943c56c5e51b769f1eaaae9b1b47aeb5328 (diff)
download: openbsd-8563c14fedd67e6d767175f2cf0815ef16997da6.tar.gz
openbsd-8563c14fedd67e6d767175f2cf0815ef16997da6.tar.bz2
openbsd-8563c14fedd67e6d767175f2cf0815ef16997da6.zip
2 files changed, 218 insertions, 1 deletions
diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile
index 0de55209bb..248bd33c8d 100644
--- a/src/lib/libcrypto/man/Makefile
+++ b/src/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/src/lib/libcrypto/man/X509_OBJECT_get0_X509.3 b/src/lib/libcrypto/man/X509_OBJECT_get0_X509.3
new file mode 100644
index 0000000000..8d39028b8e
--- /dev/null
+++ b/src/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
author	schwarze <>	2018-02-25 20:26:51 +0000
committer	schwarze <>	2018-02-25 20:26:51 +0000
commit	8563c14fedd67e6d767175f2cf0815ef16997da6 (patch)
tree	dae2bebce16c52806aa63ea1b99ca97c88fb3121 /src
parent	50c45943c56c5e51b769f1eaaae9b1b47aeb5328 (diff)
download	openbsd-8563c14fedd67e6d767175f2cf0815ef16997da6.tar.gz openbsd-8563c14fedd67e6d767175f2cf0815ef16997da6.tar.bz2 openbsd-8563c14fedd67e6d767175f2cf0815ef16997da6.zip

diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile index 0de55209bb..248bd33c8d 100644 --- a/src/lib/libcrypto/man/Makefile +++ b/src/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
1	# $OpenBSD: Makefile,v 1.134 2018/02/25 17:46:38 schwarze Exp $	1	# $OpenBSD: Makefile,v 1.135 2018/02/25 20:26:51 schwarze Exp $
2		2
3	.include <bsd.own.mk>	3	.include <bsd.own.mk>
4		4
@@ -222,6 +222,7 @@ MAN= \
222	X509_NAME_get_index_by_NID.3 \	222	X509_NAME_get_index_by_NID.3 \
223	X509_NAME_new.3 \	223	X509_NAME_new.3 \
224	X509_NAME_print_ex.3 \	224	X509_NAME_print_ex.3 \
		225	X509_OBJECT_get0_X509.3 \
225	X509_PUBKEY_new.3 \	226	X509_PUBKEY_new.3 \
226	X509_REQ_new.3 \	227	X509_REQ_new.3 \
227	X509_REVOKED_new.3 \	228	X509_REVOKED_new.3 \


diff --git a/src/lib/libcrypto/man/X509_OBJECT_get0_X509.3 b/src/lib/libcrypto/man/X509_OBJECT_get0_X509.3 new file mode 100644 index 0000000000..8d39028b8e --- /dev/null +++ b/src/lib/libcrypto/man/X509_OBJECT_get0_X509.3
@@ -0,0 +1,216 @@
		1	.\" $OpenBSD: X509_OBJECT_get0_X509.3,v 1.1 2018/02/25 20:26:51 schwarze Exp $
		2	.\" Copyright (c) 2018 Ingo Schwarze <schwarze@openbsd.org>
		3	.\"
		4	.\" Permission to use, copy, modify, and distribute this software for any
		5	.\" purpose with or without fee is hereby granted, provided that the above
		6	.\" copyright notice and this permission notice appear in all copies.
		7	.\"
		8	.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
		9	.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
		10	.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
		11	.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
		12	.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
		13	.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
		14	.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
		15	.\"
		16	.Dd $Mdocdate: February 25 2018 $
		17	.Dt X509_OBJECT_GET0_X509 3
		18	.Os
		19	.Sh NAME
		20	.Nm X509_OBJECT_up_ref_count ,
		21	.Nm X509_OBJECT_free_contents ,
		22	.Nm X509_OBJECT_get0_X509 ,
		23	.Nm X509_OBJECT_get0_X509_CRL ,
		24	.Nm X509_OBJECT_idx_by_subject ,
		25	.Nm X509_OBJECT_retrieve_by_subject ,
		26	.Nm X509_OBJECT_retrieve_match
		27	.Nd certificate, CRL, private key, and string wrapper for certificate stores
		28	.Sh SYNOPSIS
		29	.In openssl/x509_vfy.h
		30	.Ft void
		31	.Fo X509_OBJECT_up_ref_count
		32	.Fa "X509_OBJECT *obj"
		33	.Fc
		34	.Ft void
		35	.Fo X509_OBJECT_free_contents
		36	.Fa "X509_OBJECT *obj"
		37	.Fc
		38	.Ft X509 *
		39	.Fo X509_OBJECT_get0_X509
		40	.Fa "const X509_OBJECT *obj"
		41	.Fc
		42	.Ft X509_CRL *
		43	.Fo X509_OBJECT_get0_X509_CRL
		44	.Fa "X509_OBJECT *obj"
		45	.Fc
		46	.Ft int
		47	.Fo X509_OBJECT_idx_by_subject
		48	.Fa "STACK_OF(X509_OBJECT) *stack"
		49	.Fa "int type"
		50	.Fa "X509_NAME *name"
		51	.Fc
		52	.Ft X509_OBJECT *
		53	.Fo X509_OBJECT_retrieve_by_subject
		54	.Fa "STACK_OF(X509_OBJECT) *stack"
		55	.Fa "int type"
		56	.Fa "X509_NAME *name"
		57	.Fc
		58	.Ft X509_OBJECT *
		59	.Fo X509_OBJECT_retrieve_match
		60	.Fa "STACK_OF(X509_OBJECT) *stack"
		61	.Fa "X509_OBJECT *obj"
		62	.Fc
		63	.Sh DESCRIPTION
		64	The
		65	.Vt X509_OBJECT
		66	structure is a shallow wrapper around one
		67	.Vt X509
		68	certificate object, one
		69	.Vt X509_CRL
		70	certificate revocation list object, one
		71	.Vt EVP_PKEY
		72	private key object, or one
		73	.Vt char *
		74	string.
		75	It also remembers which type of object it contains at any given time.
		76	.Pp
		77	Each
		78	.Vt X509_STORE
		79	object uses one stack of
		80	.Vt X509_OBJECT
		81	structures as its main storage area.
		82	.Pp
		83	If
		84	.Fa obj
		85	contains an
		86	.Vt X509
		87	certificate or an
		88	.Vt X509_CRL
		89	certificate revocation list,
		90	.Fn X509_OBJECT_up_ref_count
		91	increments the reference count of that inner object by 1.
		92	Otherwise, no action occurs.
		93	.Pp
		94	If
		95	.Fa obj
		96	contains an
		97	.Vt X509
		98	certificate,
		99	.Fn X509_OBJECT_free_contents
		100	calls
		101	.Xr X509_free 3
		102	on that inner object.
		103	If
		104	.Fa obj
		105	contains an
		106	.Vt X509_CRL
		107	certificate revocation list, it calls
		108	.Xr X509_CRL_free 3
		109	on that inner list.
		110	Otherwise, no action occurs.
		111	.Fn X509_OBJECT_free_contents
		112	does not free
		113	.Fa obj
		114	itself.
		115	.Pp
		116	If
		117	.Fa type
		118	is
		119	.Dv X509_LU_X509 ,
		120	.Fn X509_OBJECT_idx_by_subject
		121	and
		122	.Fn X509_OBJECT_retrieve_by_subject
		123	search the given
		124	.Fa stack
		125	for a certificate with the subject
		126	.Fa name .
		127	If
		128	.Fa type
		129	is
		130	.Dv X509_LU_CRL ,
		131	they search for a certificate revocation list with the issuer
		132	.Fa name
		133	instead.
		134	.Pp
		135	If
		136	.Fa obj
		137	contains a certificate,
		138	.Fn X509_OBJECT_retrieve_match
		139	searches the given
		140	.Fa stack
		141	for a certificate with a matching subject name;
		142	if it contains a certificate revocation list, it searches for a
		143	certificate revocation list with a matching issuer name instead;
		144	otherwise, it searches for an
		145	.Vt X509_OBJECT
		146	with a matching type.
		147	.Sh RETURN VALUES
		148	.Fn X509_OBJECT_get0_X509
		149	returns an internal pointer to the certificate contained in
		150	.Fa obj
		151	or
		152	.Dv NULL
		153	if
		154	.Fa obj
		155	is
		156	.Dv NULL
		157	or contains no certificate.
		158	.Pp
		159	.Fn X509_OBJECT_get0_X509_CRL
		160	returns an internal pointer to the certificate revocation list contained in
		161	.Fa obj
		162	or
		163	.Dv NULL
		164	if
		165	.Fa obj
		166	is
		167	.Dv NULL
		168	or contains no certificate revocation list.
		169	.Pp
		170	.Fn X509_OBJECT_idx_by_subject
		171	returns the zero-based index of the first matching certificate
		172	or revocation list in the
		173	.Fa stack
		174	or \-1 if
		175	.Fa type
		176	is neither
		177	.Dv X509_LU_X509
		178	nor
		179	.Dv X509_LU_CRL
		180	or if no match is found.
		181	.Pp
		182	.Fn X509_OBJECT_retrieve_by_subject
		183	returns the first matching certificate or revocation list in the
		184	.Fa stack
		185	or
		186	.Dv NULL
		187	if
		188	.Fa type
		189	is neither
		190	.Dv X509_LU_X509
		191	nor
		192	.Dv X509_LU_CRL
		193	or if no match is found.
		194	.Pp
		195	.Fn X509_OBJECT_retrieve_match
		196	returns the first mathching
		197	.Vt X509_OBJECT
		198	or
		199	.Dv NULL
		200	if
		201	.Fa stack
		202	or
		203	.Fa obj
		204	is
		205	.Dv NULL
		206	or no match is found.
		207	.Sh SEE ALSO
		208	.Xr X509_STORE_load_locations 3 ,
		209	.Xr X509_STORE_new 3
		210	.\" The type X509_OBJECT is also used
		211	.\" by the following undocumented public functions:
		212	.\" X509_STORE_get_by_subject
		213	.\" X509_LOOKUP_by_subject
		214	.\" X509_LOOKUP_by_issuer_serial
		215	.\" X509_LOOKUP_by_fingerprint
		216	.\" X509_LOOKUP_by_alias