From: David von Oheimb <dev@ddvo.net>
Date: Wed, 4 Nov 2020 11:21:10 +0000 (+0100)
Subject: Improve doc of X509_verify_cert(), also in openssl.pod
X-Git-Tag: openssl-3.0.0-alpha9~171
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=bbc8343478376699a4aaf9416dfc520fecc5d236;p=thirdparty%2Fopenssl.git

Improve doc of X509_verify_cert(), also in openssl.pod

in particular regarding the checks due to X509_V_FLAG_X509_STRICT/-x509_strict

Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org>
(Merged from https://github.com/openssl/openssl/pull/13312)
---

diff --git a/doc/man1/openssl.pod b/doc/man1/openssl.pod
index 723ed0e2f1e..2855b9eac41 100644
--- a/doc/man1/openssl.pod
+++ b/doc/man1/openssl.pod
@@ -884,6 +884,28 @@ a verification time, the check is not suppressed.
 This disables non-compliant workarounds for broken certificates.
 Thus errors are thrown on certificates not compliant with RFC 5280.
 
+When this option is set,
+among others, the following certificate well-formedness conditions are checked:
+
+=over 8
+
+=item The basicConstraints of CA certificates must be marked critical.
+=item CA certificates must explicitly include the keyUsage extension.
+=item If a pathlenConstraint is given the key usage keyCertSign must be allowed.
+=item The pathlenConstraint must not be given for non-CA certificates.
+=item The issuer name of any certificate must not be empty.
+=item The subject name of CA certs, certs with keyUsage crlSign,
+      and certs without subjectAlternativeName must not be empty.
+=item If a subjectAlternativeName extension is given it must not be empty.
+=item The signatureAlgorithm field and the cert signature must be consistent.
+=item Any given authorityKeyIdentifier and any given subjectKeyIdentifier
+      must not be marked critical.
+=item The authorityKeyIdentifier must be given for X.509v3 certs
+      unless they are self-signed.
+=item The subjectKeyIdentifier must be given for all X.509v3 CA certs.
+
+=back
+
 =item B<-ignore_critical>
 
 Normally if an unhandled critical extension is present that is not
diff --git a/doc/man3/X509_STORE_CTX_set_verify_cb.pod b/doc/man3/X509_STORE_CTX_set_verify_cb.pod
index cfde5ab5bac..fefe6a25a0f 100644
--- a/doc/man3/X509_STORE_CTX_set_verify_cb.pod
+++ b/doc/man3/X509_STORE_CTX_set_verify_cb.pod
@@ -47,7 +47,7 @@ X509_STORE_CTX_set_verify_cb() sets the verification callback of B<ctx> to
 B<verify_cb> overwriting any existing callback.
 
 The verification callback can be used to customise the operation of certificate
-verification, either by overriding error conditions or logging errors for
+verification, for instance by overriding error conditions or logging errors for
 debugging purposes.
 
 However, a verification callback is B<not> essential and the default operation
diff --git a/doc/man3/X509_verify_cert.pod b/doc/man3/X509_verify_cert.pod
index 9368dc7e833..9dedcbc9871 100644
--- a/doc/man3/X509_verify_cert.pod
+++ b/doc/man3/X509_verify_cert.pod
@@ -13,8 +13,15 @@ X509_verify_cert - discover and verify X509 certificate chain
 =head1 DESCRIPTION
 
 The X509_verify_cert() function attempts to discover and validate a
-certificate chain based on parameters in B<ctx>. A complete description of
-the process is contained in the L<openssl-verify(1)> manual page.
+certificate chain based on parameters in B<ctx>.
+The verification context, of type B<X509_STORE_CTX>, can be constructed
+using L<X509_STORE_CTX_new(3)> and L<X509_STORE_CTX_init(3)>.
+It usually includes a set of certificates serving as trust anchors,
+a set of non-trusted certificates that may be needed for chain construction,
+flags such as X509_V_FLAG_X509_STRICT, and various other optional components
+such as a callback function that allows customizing the verification outcome.
+A complete description of the certificate verification process is contained in
+the L<openssl-verify(1)> manual page.
 
 Applications rarely call this function directly but it is used by
 OpenSSL internally for certificate validation, in both the S/MIME and
@@ -35,7 +42,7 @@ otherwise it return zero, in exceptional circumstances it can also
 return a negative code.
 
 If the function fails additional error information can be obtained by
-examining B<ctx> using, for example X509_STORE_CTX_get_error().
+examining B<ctx> using, for example L<X509_STORE_CTX_get_error(3)>.
 
 =head1 BUGS
 
@@ -45,6 +52,7 @@ functions which use F<< <x509_vfy.h> >>.
 
 =head1 SEE ALSO
 
+L<X509_STORE_CTX_new(3)>, L<X509_STORE_CTX_init(3)>,
 L<X509_STORE_CTX_get_error(3)>
 
 =head1 COPYRIGHT