Document and test X509_PURPOSE and X509_TRUST machinery

The trust and purpose is all a bit tied up together, as is the meaning
of the certificates in an X509_STORE at all. (It's hard to discuss
whether a "trusted certificate" is actually a trust anchor without a
description of trust settings to reference.)

Cut the Gordian Knot by documenting all that first. Later CLs will move
other symbols into the sections established here. Also as the behavior
is a little complex, add some tests to cover some of this machinery.

Bug: 426
Change-Id: Idde8bc4e588de92ebabf6ecf640b62a2a6803688
Reviewed-on: https://boringssl-review.googlesource.com/c/boringssl/+/65207
Commit-Queue: David Benjamin <davidben@google.com>
Reviewed-by: Bob Beck <bbe@google.com>

crypto/x509/v3_purp.c

@@ -432,6 +432,10 @@ static int check_purpose_ssl_client(const X509_PURPOSE *xp, const X509 *x,
     return 0;
   }
   if (ca) {
+    // TODO(davidben): Move the various |check_ca| calls out of the
+    // |check_purpose| callbacks. Those checks are purpose-independent. They are
+    // also redundant when called from |X509_verify_cert|, though
+    // not when |X509_check_purpose| is called directly.
     return check_ca(x);
   }
   // We need to do digital signatures or key agreement
@@ -473,8 +477,7 @@ static int check_purpose_ssl_server(const X509_PURPOSE *xp, const X509 *x,
 
 static int check_purpose_ns_ssl_server(const X509_PURPOSE *xp, const X509 *x,
                                        int ca) {
-  int ret;
-  ret = check_purpose_ssl_server(xp, x, ca);
+  int ret = check_purpose_ssl_server(xp, x, ca);
   if (!ret || ca) {
     return ret;
   }
@@ -507,8 +510,7 @@ static int purpose_smime(const X509 *x, int ca) {
 
 static int check_purpose_smime_sign(const X509_PURPOSE *xp, const X509 *x,
                                     int ca) {
-  int ret;
-  ret = purpose_smime(x, ca);
+  int ret = purpose_smime(x, ca);
   if (!ret || ca) {
     return ret;
   }
@@ -520,8 +522,7 @@ static int check_purpose_smime_sign(const X509_PURPOSE *xp, const X509 *x,
 
 static int check_purpose_smime_encrypt(const X509_PURPOSE *xp, const X509 *x,
                                        int ca) {
-  int ret;
-  ret = purpose_smime(x, ca);
+  int ret = purpose_smime(x, ca);
   if (!ret || ca) {
     return ret;
   }
@@ -555,8 +556,6 @@ static int ocsp_helper(const X509_PURPOSE *xp, const X509 *x, int ca) {
 
 static int check_purpose_timestamp_sign(const X509_PURPOSE *xp, const X509 *x,
                                         int ca) {
-  int i_ext;
-
   // If ca is true we must return if this is a valid CA certificate.
   if (ca) {
     return check_ca(x);
@@ -580,9 +579,9 @@ static int check_purpose_timestamp_sign(const X509_PURPOSE *xp, const X509 *x,
   }
 
   // Extended Key Usage MUST be critical
-  i_ext = X509_get_ext_by_NID((X509 *)x, NID_ext_key_usage, -1);
+  int i_ext = X509_get_ext_by_NID(x, NID_ext_key_usage, -1);
   if (i_ext >= 0) {
-    const X509_EXTENSION *ext = X509_get_ext((X509 *)x, i_ext);
+    const X509_EXTENSION *ext = X509_get_ext(x, i_ext);
     if (!X509_EXTENSION_get_critical(ext)) {
       return 0;
     }