Clarify the return value of s2n_cert_validation_callback

[goatgoose]

Problem:

The s2n_cert_validation_accept() and s2n_cert_validation_reject()APIs are used from within the s2n_cert_validation_callback to indicate whether the application cert validation checks have succeeded or failed. However, like most other s2n-tls callbacks, the callback can return -1 to indicate a failure from within the callback itself, which causes a S2N_ERR_CANCELED error.

The API documentation currently specifies that this API can return -1, but it doesn't specify what happens when the callback does this, and how this relates to the accept/reject APIs:

s2n-tls/api/unstable/crl.h

Line 205 in ba825b8

* @returns 0 on success, -1 on failure.

Solution:

Update the documentation to indicate what happens when s2n_cert_validation_callback indicates a failing return code.

We could consider updating the API documentation for s2n_cert_validation_callback to include this. However, since this applies to other callbacks as well, we could also consider adding a usage guide section about callbacks more generally and what happens when they return failing.