gnutls_certificate_verify_peers2 API

[Joe Orton]

This API is very awkward to use.

1) it is not clear from the API docs whether "failing to verify a cert" 
would be an error resulting in a non-zero return value, or success.

2) the use of the GNUTLS_CERT_INVALID status bit is unclear and 
inappropriate.  The header file say it means:

  /* will be set if the certificate was not verified */

the HTML docs say it means:

  The certificate is not signed by one of the known authorities, or the 
  signature is invalid. 

which are different things.  If the latter is supposed to be true, it is 
unclear why GNUTLS_CERT_SIGNER_NOT_FOUND exists as well.

In practice, all verification failures emitted seem to be ORed with 
CERT_INVALID, which implies it is redundant.  I need to be able to 
safely map a given verification failure into a API/UI, which allows 
users to override specific errors.

If I get the verification error bits:

   GNUTLS_CERT_INVALID | GNUTLS_CERT_SIGNER_NOT_FOUND

does that mean simply a cert signed by a unknown CA?  Or possibly, the 
cert is signed by an unknown CA *and* there is some other verification 
error?  It's hard to tell.

3) for future-extensibility, it is necessary to be able to map a failure 
bit (or bitmask) into an error string, so I can present meaningful 
errors beyond "cert verification failed with GnuTLS failure bit 2^10".

Regards, Joe