Improve verification error handling

[jsiwrk]

We should differentiate two cases:

• a verification error (e.g. decoding error, invalid signature, data not conforming to schema, kid not found in trust list, etc.)
• a general error occurred during verification (e.g. connection error when downloading a trust list, error accessing disk, out of memory, etc.)

In the first case, it does not make sense for the library client to retry the verification (for that particular hcert), since the hcert is most probably invalid.

In the second case, the problem most likely does not have to do with that hcert, and retrying could make sense. Also, in general, it could make sense to try to apply some corrective action, send an alert to an operator, etc.

Therefore there is the need to deal with both cases in different ways. This commit solves this problem by using a (new) VerificationException to propagate the errors belonging to the first use case. For the second use case, the original exception is simply propagated to the application code (who can know better than us what to do with such an exception).

Also a VerificationResult.errorMessage field has been added containing a more detailed message describing the error.

[jsiwrk]

Sorry for such an apparently big changeset, although actually it's a fairly easy refactor. If that creates conflicts with your work in progress (and assuming you agree with the proposed improvement), I can rebase the PR at a later time, no problem. The changes are pretty straightforward to replicate.

I'm just playing around with the library (on my behalf) so I don't have any special urgency for this PR to be approved. I just think it's an interesting (necessary, in fact, from my point of view) improvement. Thanks for considering it.

[JesusMcCloud]

Much appreciated! Although we removed the errorMessage from the VerificationResult, as such information should be logged, not returned.

[jsiwrk]

Although we removed the errorMessage from the VerificationResult, as such information should be logged, not returned.

I would tend to agree with that in the general sense, if we were talking about an application or a service. However, since this is a reusable library that will presumably be used to build the former, wouldn't it be more appropriate to leave that choice to the library user?

For example, let's consider these scenarios:

• An application using this library wants to print a detailed error to the user indicating why the hcert is "expired". The CWT_EXPIRED error code can be returned for various reasons (hcert issued before signer cert, hcert issued in the future, hcert expired, hcert expiration exceeds signer cert expiration, expiration field not present, etc.), so the code itself is not enough to know the cause. Let's also assume this application is targeted to a type of user who is genuinelly interested about these details (maybe a second-line border control officer that needs to explain to a hcert holder why their document was rejected by the first-line control), and that he/she prefers to see this detail in a user-friendly way (rather than looking at some internal logs).
• An application or service using this library wants to record a log with the full details why the validation has failed, and wants to record the log in its own way. Maybe it needs to send a JSON-formatted log to a SIEM system (e.g. Splunk).

If these are deemed valid use cases for this library, then it seems that including an errorMessage (or, generally speaking, detailed information about the error) in the VerificationResult would be the right thing to do. And the library client would be responsible for making a proper use of this field. What do you think?