Clarify documentation for directly-trusted certs
The fact that self-signed end-entity certs can be explicitly trusted by
putting them in the CA list even if they don't have the CA bit was not
documented though it's intentional, and tested by "Certificate verification #73
(selfsigned trusted without CA bit)" in test_suite_x509parse.data
It is unclear to me whether the restriction that explicitly trusted end-entity
certs must be self-signed is a good one. However, it seems intentional as it is
tested in tests #42 and #43, so I'm not touching it for now.
diff --git a/include/mbedtls/ssl.h b/include/mbedtls/ssl.h
index 12a98eb..ccc96a5 100644
--- a/include/mbedtls/ssl.h
+++ b/include/mbedtls/ssl.h
@@ -1382,6 +1382,10 @@
/**
* \brief Set the data required to verify peer certificate
*
+ * \note See \c mbedtls_x509_verify() for notes regarding the
+ * parameters ca_chain (maps to trust_ca for that function)
+ * and ca_crl.
+ *
* \param conf SSL configuration
* \param ca_chain trusted CA chain (meaning all fully trusted top-level CAs)
* \param ca_crl trusted CA CRLs
diff --git a/include/mbedtls/x509_crt.h b/include/mbedtls/x509_crt.h
index bebb146..f4bc746 100644
--- a/include/mbedtls/x509_crt.h
+++ b/include/mbedtls/x509_crt.h
@@ -277,9 +277,21 @@
* \note Same as \c mbedtls_x509_crt_verify_with_profile() with the
* default security profile.
*
- * \param crt a certificate to be verified
- * \param trust_ca the trusted CA chain
- * \param ca_crl the CRL chain for trusted CA's
+ * \note It is your responsibility to provide up-to-date CRLs for
+ * all trusted CAs. If no CRL is provided for the CA that was
+ * used to sign the certificate, CRL verification is skipped
+ * silently, that is *without* setting any flag.
+ *
+ * \note The \c trust_ca list can contain two type of certificates:
+ * (1) those of trusted root CAs, so that certificates
+ * chaining up to those CAs will be trusted, and (2)
+ * self-signed end-entity certificates to be trusted (for
+ * specific peers you know) - in that case, the self-signed
+ * certificate doens't need to have the CA bit set.
+ *
+ * \param crt a certificate (chain) to be verified
+ * \param trust_ca the list of trusted CAs (see note above)
+ * \param ca_crl the list of CRLs for trusted CAs (see note above)
* \param cn expected Common Name (can be set to
* NULL if the CN must not be verified)
* \param flags result of the verification