From 5d54e37d0634404f90b22c4844449b2f99d67099 Mon Sep 17 00:00:00 2001 From: schwarze Date: Mon, 26 Jul 2021 14:03:43 +0000 Subject: [PATCH] new manual page X509_policy_tree_level_count(3) documenting the X509_POLICY_TREE object and its sub-objects --- lib/libcrypto/man/Makefile | 3 +- lib/libcrypto/man/POLICYINFO_new.3 | 7 +- lib/libcrypto/man/X509_new.3 | 5 +- .../man/X509_policy_tree_level_count.3 | 159 ++++++++++++++++++ 4 files changed, 168 insertions(+), 6 deletions(-) create mode 100644 lib/libcrypto/man/X509_policy_tree_level_count.3 diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile index c3dcaa06a3f..a1ea6af33ab 100644 --- a/lib/libcrypto/man/Makefile +++ b/lib/libcrypto/man/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.186 2021/07/24 14:33:14 schwarze Exp $ +# $OpenBSD: Makefile,v 1.187 2021/07/26 14:03:43 schwarze Exp $ .include @@ -327,6 +327,7 @@ MAN= \ X509_get1_email.3 \ X509_keyid_set1.3 \ X509_new.3 \ + X509_policy_tree_level_count.3 \ X509_print_ex.3 \ X509_sign.3 \ X509_signature_dump.3 \ diff --git a/lib/libcrypto/man/POLICYINFO_new.3 b/lib/libcrypto/man/POLICYINFO_new.3 index 4b88cf00eba..7938ed591d6 100644 --- a/lib/libcrypto/man/POLICYINFO_new.3 +++ b/lib/libcrypto/man/POLICYINFO_new.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: POLICYINFO_new.3,v 1.7 2019/06/06 17:41:43 schwarze Exp $ +.\" $OpenBSD: POLICYINFO_new.3,v 1.8 2021/07/26 14:03:43 schwarze Exp $ .\" .\" Copyright (c) 2016 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: June 6 2019 $ +.Dd $Mdocdate: July 26 2021 $ .Dt POLICYINFO_NEW 3 .Os .Sh NAME @@ -178,7 +178,8 @@ if an error occurs. .Xr d2i_POLICYINFO 3 , .Xr NAME_CONSTRAINTS_new 3 , .Xr X509_EXTENSION_new 3 , -.Xr X509_new 3 +.Xr X509_new 3 , +.Xr X509_policy_tree_level_count 3 .Sh STANDARDS RFC 5280: Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile: diff --git a/lib/libcrypto/man/X509_new.3 b/lib/libcrypto/man/X509_new.3 index e06203f87c6..304045f6577 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.26 2021/07/24 14:33:14 schwarze Exp $ +.\" $OpenBSD: X509_new.3,v 1.27 2021/07/26 14:03:43 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 24 2021 $ +.Dd $Mdocdate: July 26 2021 $ .Dt X509_NEW 3 .Os .Sh NAME @@ -193,6 +193,7 @@ if an error occurs. .Xr X509_get_version 3 , .Xr X509_INFO_new 3 , .Xr X509_NAME_new 3 , +.Xr X509_policy_tree_level_count 3 , .Xr X509_print_ex 3 , .Xr X509_PUBKEY_new 3 , .Xr X509_PURPOSE_set 3 , diff --git a/lib/libcrypto/man/X509_policy_tree_level_count.3 b/lib/libcrypto/man/X509_policy_tree_level_count.3 new file mode 100644 index 00000000000..523cb55f1d0 --- /dev/null +++ b/lib/libcrypto/man/X509_policy_tree_level_count.3 @@ -0,0 +1,159 @@ +.\" $OpenBSD: X509_policy_tree_level_count.3,v 1.1 2021/07/26 14:03:43 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: July 26 2021 $ +.Dt X509_POLICY_TREE_LEVEL_COUNT 3 +.Os +.Sh NAME +.Nm X509_policy_tree_level_count , +.Nm X509_policy_tree_get0_level , +.Nm X509_policy_level_node_count , +.Nm X509_policy_level_get0_node , +.Nm X509_policy_node_get0_policy , +.Nm X509_policy_node_get0_qualifiers , +.Nm X509_policy_node_get0_parent +.Nd inspect X.509 policy tree objects +.Sh SYNOPSIS +.In openssl/x509_vfy.h +.Ft int +.Fn X509_policy_tree_level_count "const X509_POLICY_TREE *tree" +.Ft X509_POLICY_LEVEL * +.Fn X509_policy_tree_get0_level "const X509_POLICY_TREE *tree" "int index" +.Ft int +.Fn X509_policy_level_node_count "X509_POLICY_LEVEL *level" +.Ft X509_POLICY_NODE * +.Fn X509_policy_level_get0_node "X509_POLICY_LEVEL *level" "int index" +.Ft const ASN1_OBJECT * +.Fn X509_policy_node_get0_policy "const X509_POLICY_NODE *node" +.Ft STACK_OF(POLICYQUALINFO) * +.Fn X509_policy_node_get0_qualifiers "const X509_POLICY_NODE *node" +.Ft const X509_POLICY_NODE * +.Fn X509_policy_node_get0_parent "const X509_POLICY_NODE *node" +.Sh DESCRIPTION +The +.Vt X509_POLICY_TREE +object represents a +.Vt valid_policy_tree +as described in RFC 5280 section 6.1. +.Pp +The +.Vt X509_POLICY_LEVEL +object represents one level of such a tree, +corresponding to one certificate. +.Pp +The +.Vt X509_POLICY_NODE +object represents one node in the tree. +.Sh RETURN VALUES +.Fn X509_policy_tree_level_count +returns the number of levels in the +.Fa tree +or 0 if the +.Fa tree +argument is +.Dv NULL . +.Pp +.Fn X509_policy_tree_get0_level +returns an internal pointer to the level of the +.Fa tree +with the given +.Fa index +or +.Dv NULL +if the +.Fa tree +argument is +.Dv NULL +or the +.Fa index +is less than 0 or greater than or equal to the number of levels in the +.Fa tree . +.Pp +.Fn X509_policy_level_node_count +returns the number of nodes on the +.Fa level , +including an +.Sy anyPolicy +node if it is present, or 0 if the +.Fa level +argument is +.Dv NULL . +.Pp +.Fn X509_policy_level_get0_node +returns an internal pointer to the node on the +.Fa level +with the given +.Fa index +or +.Dv NULL +if the +.Fa level +argument is +.Dv NULL +or the +.Fa index +is less than 0 or greater than or equal to the number of nodes on the level. +If an +.Sy anyPolicy +node is present on the level, it can be retrieved by passing an +.Fa index +of 0. +.Pp +.Fn X509_policy_node_get0_policy +returns an internal pointer to the +.Fa valid_policy +child object of the node or +.Dv NULL +if the +.Fa node +argument is +.Dv NULL . +.Pp +.Fn X509_policy_node_get0_qualifiers +returns an an internal pointer to the +.Fa qualifier_set +child object of the node or +.Dv NULL +if the +.Fa node +argument is +.Dv NULL . +.Pp +.Fn X509_policy_node_get0_parent +returns +.Dv NULL +if the +.Fa node +argument is +.Dv NULL +or located on level 0. +Otherwise, it returns an an internal pointer to the parent node of the +.Fa node +argument. +The parent node is always located on the previous level. +.Sh SEE ALSO +.Xr ASN1_OBJECT_new 3 , +.Xr OBJ_obj2txt 3 , +.Xr POLICYQUALINFO_new 3 , +.Xr STACK_OF 3 , +.Xr X509_new 3 +.Sh STANDARDS +RFC 5280: Internet X.509 Public Key Infrastructure Certificate +and Certificate Revocation List (CRL) Profile, +section 6.1: Basic Path Validation +.Sh HISTORY +These function first appeared in OpenSSL 0.9.8 and have been available since +.Ox 4.5 . -- 2.20.1