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: https://github.com/aws/s2n-tls/blob/ba825b878a58079e7453fe3c6f00b48a8752398c/api/unstable/crl.h#L205

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.