[PATCH 2/3] devel/schemata: describe version 4

[David Bremner]

Daniel Kahn Gillmor <dkg at fifthhorseman.net> writes:

> If we've got a bitfield, we should expose it as a bitfield.  but if we
> know that there is additionally a status component that has one of
> exactly three values, we should expose it as its own element.
>
> So i'd prefer:
>
>   status: "good"|"bad"|"error",
>   flags: sig_flags,
>   # if status is "good":

GMime 3.0 is just a thin wrapper around gpgme here, so we may as well consult
the latter docs. If I understand them [1] correctly, there are two
distinct "good" states, one called "VALID" and the other called
"GREEN". Alas, I had to look at the gpgme source to really understand
the intent here.

GREEN means the following

,----
|   if (sig->validity == GPGME_VALIDITY_FULL
|       || sig->validity == GPGME_VALIDITY_ULTIMATE)
|     {
|       if (gpg_err_code (sig->status) == GPG_ERR_NO_ERROR
| 	  || gpg_err_code (sig->status) == GPG_ERR_SIG_EXPIRED
| 	  || gpg_err_code (sig->status) == GPG_ERR_KEY_EXPIRED)
| 	sum |= GPGME_SIGSUM_GREEN;
|     }
`----

while VALID means in addition that the SIG_EXPIRED and KEY_EXPIRED
errors don't occur.

The subtlety here is that "error" and "green" are overlapping states
from gpgme's point of view.  One way of bridging this gap is have status
only reflect the "usability" [2] of the signature

status: "good" | "warning" | "bad" | "unknown" 

where the interested client can check the flags for details in the
latter 3 cases.

[1]: https://www.gnupg.org/documentation/manuals/gpgme/Verify.html
[2]: naming is hard