SSL certificate verify failure lacks specifics #10832

When a ussl.wrap_socket() call fails due to a certificate verification issue, the only information the user can see is the exception:

• OSError: (-9984, 'MBEDTLS_ERR_X509_CERT_VERIFY_FAILED')

The exception per se suggests an inherent fault with the certificate and/or its CA chain.

However, that exception also occurs if the device's clock is not manually set, even if the certificate and its CA chain are inherently valid. On startup, the clock gets set to a hardwired datetime in 2022. If it sees a certificate with a validity start date later than this default, the validation will fail with no explanation.

Recommended remedies:

1. Create a range of different exception titles for ussl.wrap_socket(), rather than just the single terse MBEDTLS_ERR_X509_CERT_VERIFY_FAILED. Include in this a couple of titles which indicate the system datetime is before the certificate start time, or later than the certificate expiry time
2. Alternately, add some extra attributes into the OSError exception object to help users diagnose the verification failure, and make sure to document these in the API page for ussl.wrap_socket()
3. Either way, update the API page to (i) warn users that a device's default datetime may pre-date a presented certificate, and (ii) recommend that users set the datetime themselves, possibly via calling ntptime.settime()