[gmime: 7/23] GMimeCertificate: distinguish GMimeValidity from GMimeTrust

[Jeffrey Stedfast <fejj src gnome org>]

commit a002dbd901e1bacebd550a80caa6a40ad09497f3
Author: Daniel Kahn Gillmor <dkg fifthhorseman net>
Date:   Mon Oct 16 00:57:33 2017 -0400

    GMimeCertificate: distinguish GMimeValidity from GMimeTrust
    
    While the enum values used are the same in GPGME, GnuPG applies
    distinct logic between "Trust" and "Validity" (and the enum itself is
    applied in different places: trust on the key, and validity on the
    key+userid).  GMime should avoid replicating this confusion, and
    should call them out distinctly.
    
    A subsequent commit will actually expose User ID validity.

 docs/reference/gmime-sections.txt |    1 +
 gmime/gmime-certificate.h         |   56 ++++++++++++++++++++++++++++++++----
 2 files changed, 50 insertions(+), 7 deletions(-)
---
diff --git a/docs/reference/gmime-sections.txt b/docs/reference/gmime-sections.txt
index 76bfd0d..52191ab 100644
--- a/docs/reference/gmime-sections.txt
+++ b/docs/reference/gmime-sections.txt
@@ -1383,6 +1383,7 @@ g_mime_iconv_locale_to_utf8_length
 GMimePubKeyAlgo
 GMimeDigestAlgo
 GMimeTrust
+GMimeValidity
 GMimeCertificate
 g_mime_certificate_new
 g_mime_certificate_get_pubkey_algo
diff --git a/gmime/gmime-certificate.h b/gmime/gmime-certificate.h
index 1df4444..266f1e1 100644
--- a/gmime/gmime-certificate.h
+++ b/gmime/gmime-certificate.h
@@ -121,14 +121,22 @@ typedef enum {
 
 /**
  * GMimeTrust:
- * @GMIME_TRUST_UNKNOWN: The certificate or key is of unknown validity.
- * @GMIME_TRUST_UNDEFINED: The validity of the certificate or key is undefined.
- * @GMIME_TRUST_NEVER: The certificate or key should never be treated as valid.
- * @GMIME_TRUST_MARGINAL: The certificate or key is marginally valid.
- * @GMIME_TRUST_FULL: The certificate or key is fully valid.
- * @GMIME_TRUST_ULTIMATE: The certificate or key is ultimately valid.
+ * @GMIME_TRUST_UNKNOWN: We do not know whether to rely on identity assertions made by the certificate.
+ * @GMIME_TRUST_UNDEFINED: We do not have enough information to decide whether to rely on identity 
assertions made by the certificate.
+ * @GMIME_TRUST_NEVER: We should never rely on identity assertions made by the certificate.
+ * @GMIME_TRUST_MARGINAL: We can rely on identity assertions made by this certificate as long as they are 
corroborated by other marginally-trusted certificates.
+ * @GMIME_TRUST_FULL: We can rely on identity assertions made by this certificate.
+ * @GMIME_TRUST_ULTIMATE: This certificate is an undeniable root of trust (e.g. normally, this is a 
certificate controlled by the user themselves).
  *
- * The trust level of a certificate or key.
+ * The trust level of a certificate.  Trust level tries to answer the
+ * question: "How much is the user willing to rely on cryptographic
+ * identity assertions made by the owner of this certificate?"
+ * 
+ * By way of comparison with web browser X.509 certificate validation
+ * stacks, the certificate of a "Root CA" has @GMIME_TRUST_ULTIMATE,
+ * while the certificate of an intermediate CA has @GMIME_TRUST_FULL,
+ * and an end-entity certificate (e.g., with CA:FALSE set) would have
+ * @GMIME_TRUST_NEVER.
  **/
 typedef enum {
        GMIME_TRUST_UNKNOWN   = 0,
@@ -140,6 +148,40 @@ typedef enum {
 } GMimeTrust;
 
 /**
+ * GMimeValidity:
+ * @GMIME_VALIDITY_UNKNOWN: The User ID of the certificate is of unknown validity.
+ * @GMIME_VALIDITY_UNDEFINED: The User ID of the certificate is undefined.
+ * @GMIME_VALIDITY_NEVER: The User ID of the certificate is never to be treated as valid.
+ * @GMIME_VALIDITY_MARGINAL: The User ID of the certificate is marginally valid (e.g. it has been certified 
by only one marginally-trusted party).
+ * @GMIME_VALIDITY_FULL: The User ID of the certificate is fully valid.
+ * @GMIME_VALIDITY_ULTIMATE: The User ID of the certificate is ultimately valid (i.e., usually the 
certificate belongs to the local user themselves).
+ *
+ * The validity level of a certificate's User ID.  Validity level
+ * tries to answer the question: "How strongly do we believe that this
+ * certificate belongs to the party it says it belongs to?"
+ *
+ * Note that some OpenPGP certificates have multiple User IDs, and
+ * each User ID may have a different validity level (e.g. depending on
+ * which third parties have certified which User IDs, and which third
+ * parties the local user has chosen to trust).
+ *
+ * Similarly, an X.509 certificate can have multiple SubjectAltNames,
+ * and each name may also have a different validity level (e.g. if the
+ * issuing CA is bound by name constraints).
+ *
+ * Note that the GMime API currently only exposes the highest-validty
+ * User ID for any given certificate.
+ **/
+typedef enum {
+       GMIME_VALIDITY_UNKNOWN   = 0,
+       GMIME_VALIDITY_UNDEFINED = 1,
+       GMIME_VALIDITY_NEVER     = 2,
+       GMIME_VALIDITY_MARGINAL  = 3,
+       GMIME_VALIDITY_FULL      = 4,
+       GMIME_VALIDITY_ULTIMATE  = 5
+} GMimeValidity;
+
+/**
  * GMimeCertificate:
  * @parent_object: parent #GObject
  * @pubkey_algo: The public-key algorithm used by the certificate, if known.