document set_default_verify_paths caveats (#667)
* document set_default_verify_paths caveats
fixes #642
* add a bit more detail
* weasel words
diff --git a/doc/api/ssl.rst b/doc/api/ssl.rst
index 00cae9b..53bcf40 100644
--- a/doc/api/ssl.rst
+++ b/doc/api/ssl.rst
@@ -307,8 +307,15 @@
.. py:method:: Context.set_default_verify_paths()
Specify that the platform provided CA certificates are to be used for
- verification purposes. This method may not work properly on OS X.
+ verification purposes. This method has some caveats related to the
+ binary wheels that cryptography (pyOpenSSL's primary dependency) ships:
+ * macOS will only load certificates using this method if the user has
+ the ``openssl@1.1`` Homebrew formula installed in the default location.
+ * Windows will not work.
+ * manylinux1 cryptography wheels will work on most common Linux distributions
+ in pyOpenSSL 17.1.0 and above. pyOpenSSL detects the manylinux1 wheel and
+ attempts to load roots via a fallback path.
.. py:method:: Context.load_tmp_dh(dhfile)