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 51e843a..b3e97b7 100644
--- a/include/mbedtls/ssl.h
+++ b/include/mbedtls/ssl.h
@@ -1587,6 +1587,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 2dbb7ec..944ef38 100644
--- a/include/mbedtls/x509_crt.h
+++ b/include/mbedtls/x509_crt.h
@@ -287,8 +287,15 @@
* 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
+ * \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)