From 946c22da507d2f197b293893ddbf38c7230ca919 Mon Sep 17 00:00:00 2001 From: schwarze Date: Tue, 27 Jul 2021 13:27:46 +0000 Subject: [PATCH] new manual page X509_policy_check(3) --- lib/libcrypto/man/Makefile | 3 +- lib/libcrypto/man/X509_check_purpose.3 | 5 +- lib/libcrypto/man/X509_check_trust.3 | 5 +- lib/libcrypto/man/X509_new.3 | 5 +- lib/libcrypto/man/X509_policy_check.3 | 183 ++++++++++++++++++ .../man/X509_policy_tree_level_count.3 | 7 +- 6 files changed, 198 insertions(+), 10 deletions(-) create mode 100644 lib/libcrypto/man/X509_policy_check.3 diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile index a1ea6af33ab..f605de5dbcc 100644 --- a/lib/libcrypto/man/Makefile +++ b/lib/libcrypto/man/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.187 2021/07/26 14:03:43 schwarze Exp $ +# $OpenBSD: Makefile,v 1.188 2021/07/27 13:27:46 schwarze Exp $ .include @@ -327,6 +327,7 @@ MAN= \ X509_get1_email.3 \ X509_keyid_set1.3 \ X509_new.3 \ + X509_policy_check.3 \ X509_policy_tree_level_count.3 \ X509_print_ex.3 \ X509_sign.3 \ diff --git a/lib/libcrypto/man/X509_check_purpose.3 b/lib/libcrypto/man/X509_check_purpose.3 index 56f61095411..fdb58d5b215 100644 --- a/lib/libcrypto/man/X509_check_purpose.3 +++ b/lib/libcrypto/man/X509_check_purpose.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: X509_check_purpose.3,v 1.5 2021/07/24 14:33:14 schwarze Exp $ +.\" $OpenBSD: X509_check_purpose.3,v 1.6 2021/07/27 13:27:46 schwarze Exp $ .\" .\" Copyright (c) 2019, 2021 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 24 2021 $ +.Dd $Mdocdate: July 27 2021 $ .Dt X509_CHECK_PURPOSE 3 .Os .Sh NAME @@ -382,6 +382,7 @@ can be used as a CA for the .Xr EXTENDED_KEY_USAGE_new 3 , .Xr X509_check_trust 3 , .Xr X509_new 3 , +.Xr X509_policy_check 3 , .Xr X509_PURPOSE_set 3 , .Xr X509V3_get_d2i 3 , .Xr x509v3.cnf 5 diff --git a/lib/libcrypto/man/X509_check_trust.3 b/lib/libcrypto/man/X509_check_trust.3 index 4b625fdfd4d..98bfecb3d45 100644 --- a/lib/libcrypto/man/X509_check_trust.3 +++ b/lib/libcrypto/man/X509_check_trust.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: X509_check_trust.3,v 1.1 2021/07/24 14:33:14 schwarze Exp $ +.\" $OpenBSD: X509_check_trust.3,v 1.2 2021/07/27 13:27:46 schwarze Exp $ .\" .\" Copyright (c) 2021 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 24 2021 $ +.Dd $Mdocdate: July 27 2021 $ .Dt X509_CHECK_TRUST 3 .Os .Sh NAME @@ -200,6 +200,7 @@ which implies that it is not trusted. .Xr X509_CERT_AUX_new 3 , .Xr X509_check_purpose 3 , .Xr X509_new 3 , +.Xr X509_policy_check 3 , .Xr X509_TRUST_set 3 , .Xr X509_VERIFY_PARAM_set_trust 3 .Sh HISTORY diff --git a/lib/libcrypto/man/X509_new.3 b/lib/libcrypto/man/X509_new.3 index 304045f6577..8a1da448c43 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.27 2021/07/26 14:03:43 schwarze Exp $ +.\" $OpenBSD: X509_new.3,v 1.28 2021/07/27 13:27:46 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 26 2021 $ +.Dd $Mdocdate: July 27 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_check 3 , .Xr X509_policy_tree_level_count 3 , .Xr X509_print_ex 3 , .Xr X509_PUBKEY_new 3 , diff --git a/lib/libcrypto/man/X509_policy_check.3 b/lib/libcrypto/man/X509_policy_check.3 new file mode 100644 index 00000000000..f2450992289 --- /dev/null +++ b/lib/libcrypto/man/X509_policy_check.3 @@ -0,0 +1,183 @@ +.\" $OpenBSD: X509_policy_check.3,v 1.1 2021/07/27 13:27:46 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 27 2021 $ +.Dt X509_POLICY_CHECK 3 +.Os +.Sh NAME +.Nm X509_policy_check +.Nd construct X.509 valid policy tree +.Sh SYNOPSIS +.In openssl/x509_vfy.h +.Ft int +.Fo X509_policy_check +.Fa "X509_POLICY_TREE **ptree" +.Fa "int *pexplicit_policy" +.Fa "STACK_OF(X509) *certs" +.Fa "STACK_OF(ASN1_OBJECT) *policy_oids" +.Fa "unsigned int flags" +.Fc +.Sh DESCRIPTION +.Fn X509_policy_check +performs those parts of Basic Certification Path Validation +described in RFC 5280 section 6.1 that are related to the +construction of the valid policy tree. +.Pp +The +.Fa certs +input argument contains the prospective certification path +according to RFC 5280 paragraph 6.1.1(a), starting with the +target certificate and ending with the trust anchor. +If a policy tree is returned, the reference count of each of the +.Fa certs +is incremented by 1. +.Pp +The +.Fa policy_oids +input argument contains the +.Va user-initial-policy-set +according to RFC 5280 section 6.1.1(c). +.Pp +The +.Fa flags +argument can contain zero or more of the following constants, OR'ed together: +.Bl -tag -width Ds +.It Dv X509_V_FLAG_EXPLICIT_POLICY +Set +.Va initial-explicit-policy +as defined by RFC 5280 paragraph 6.1.1(f). +It requires the path to be valid for at least one of the +.Fa policy_oids . +.It Dv X509_V_FLAG_INHIBIT_ANY +Set +.Va initial-any-policy-inhibit +as defined by RFC 5280 paragraph 6.1.1(g). +It causes the +.Sy anyPolicy +OID to be skipped if it is encountered in a certificate. +.It Dv X509_V_FLAG_INHIBIT_MAP +Set +.Va initial-policy-mapping-inhibit +as defined by RFC 5280 paragraph 6.1.1(e). +It disables policy mapping in the certification path. +.El +.Pp +Upon success, a pointer to the +.Vt valid_policy_tree +output value mentioned in RFC 5280 section 6.1.6 is returned in +.Pf * Fa ptree . +It contains one level for each of the +.Fa certs , +in reverse order: level 0 corresponds to the trust anchor, +the last level corresponds to the target certificate. +Level 0 is initialized to contain a single node with a +.Fa valid_policy +of +.Sy anyPolicy , +an empty +.Fa qualifier_set , +and an +.Fa expected_policy_set +containing only +.Sy anyPolicy . +.Pp +The storage location pointed to by +.Fa pexplicit_policy +is set as specified in RFC 5280 paragraphs 6.1.2(d), 6.1.4(h), 6.1.4(i), +6.1.5(a), and 6.1.5(b). +In case of failure, it may or may not get set, representing a partial result. +.Sh RETURN VALUES +.Fn X509_policy_check +returns these values: +.Bl -tag -width 2n +.It \-2 +Validation failed because +.Dv X509_V_FLAG_EXPLICIT_POLICY +was requested but the resulting policy tree +or the resulting user policy set would have been empty. +In this case, +.Pf * Fa pexplicit_policy +is set to 1. +If the resulting tree is empty, +.Pf * Fa ptree +is set to +.Dv NULL ; +otherwise, it is set to the resulting tree. +.It \-1 +At least one of the +.Fa certs +contains invalid or inconsistent extensions. +.Pf * Fa ptree +is set to +.Dv NULL +and +.Pf * Fa pexplicit_policy +to 0. +.It 0 +Internal error. +For example, setting up the policy caches failed, or memory allocation +failed while constructing the tree. +.Pf * Fa ptree +is set to +.Dv NULL +and +.Pf * Fa pexplicit_policy +may be set to 0 or to a partial result. +.It 1 +Validation succeeded and +.Pf * Fa ptree +and +.Pf * Fa pexplicit_policy +have been set. +In the special cases that the +.Fa certs +argument contains exactly one certificate or that +.Dv X509_V_FLAG_EXPLICIT_POLICY +was not requested and the resulting policy tree would have been empty, +.Pf * Fa ptree +is set to +.Dv NULL +and +.Pf * Fa pexplicit_policy +to 0. +.It 2 +.Dv X509_V_FLAG_EXPLICIT_POLICY +was not requested and at least one of the certificates contains no +certificate policies. +.Pf * Fa ptree +is set to +.Dv NULL +and +.Pf * Fa pexplicit_policy +to 0. +.El +.Sh SEE ALSO +.Xr ASN1_OBJECT_new 3 , +.Xr OBJ_nid2obj 3 , +.Xr STACK_OF 3 , +.Xr X509_check_purpose 3 , +.Xr X509_check_trust 3 , +.Xr X509_new 3 , +.Xr X509_policy_tree_level_count 3 , +.Xr X509_verify_cert 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 +.Fn X509_policy_check +first appeared in OpenSSL 0.9.8 and has been available since +.Ox 4.5 . diff --git a/lib/libcrypto/man/X509_policy_tree_level_count.3 b/lib/libcrypto/man/X509_policy_tree_level_count.3 index 523cb55f1d0..87fb4234398 100644 --- a/lib/libcrypto/man/X509_policy_tree_level_count.3 +++ b/lib/libcrypto/man/X509_policy_tree_level_count.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: X509_policy_tree_level_count.3,v 1.1 2021/07/26 14:03:43 schwarze Exp $ +.\" $OpenBSD: X509_policy_tree_level_count.3,v 1.2 2021/07/27 13:27:46 schwarze Exp $ .\" .\" Copyright (c) 2021 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 26 2021 $ +.Dd $Mdocdate: July 27 2021 $ .Dt X509_POLICY_TREE_LEVEL_COUNT 3 .Os .Sh NAME @@ -149,7 +149,8 @@ The parent node is always located on the previous level. .Xr OBJ_obj2txt 3 , .Xr POLICYQUALINFO_new 3 , .Xr STACK_OF 3 , -.Xr X509_new 3 +.Xr X509_new 3 , +.Xr X509_policy_check 3 .Sh STANDARDS RFC 5280: Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile, -- 2.20.1