From e94c812c2d02427e924b72adfa3572e911eba2ca Mon Sep 17 00:00:00 2001 From: Kevin Burke Date: Thu, 17 Mar 2016 08:07:16 -0700 Subject: [PATCH] Clarify that SSL verification is on by default Generally if a kwarg is present it indicates that an option other than the default is being specified. Putting `verify=True` in the first code sample for SSL confused me, because it seemed to indicate that you had to specify `verify=True` to get SSL verification. The opposite is true; SSL verification is turned on by default and you have to specify `verify=False` to opt out of SSL verification. Updates the docs to make this more clear. Furthermore, connections to https://kennethreitz.com currently time out instead of presenting an invalid certificate, so I replaced this domain with https://requestb.in, which presents the same error message as is currently there. --- docs/user/advanced.rst | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/user/advanced.rst b/docs/user/advanced.rst index ddd6edf6..a7812882 100644 --- a/docs/user/advanced.rst +++ b/docs/user/advanced.rst @@ -192,15 +192,16 @@ applied, replace the call to :meth:`Request.prepare() SSL Cert Verification --------------------- -Requests can verify SSL certificates for HTTPS requests, just like a web browser. -To check a host's SSL certificate, you can use the ``verify`` argument:: +Requests verifies SSL certificates for HTTPS requests, just like a web browser. +By default, SSL verification is enabled, and requests will throw a SSLError if +it's unable to verify the certificate:: - >>> requests.get('https://kennethreitz.com', verify=True) - requests.exceptions.SSLError: hostname 'kennethreitz.com' doesn't match either of '*.herokuapp.com', 'herokuapp.com' + >>> requests.get('https://requestb.in') + requests.exceptions.SSLError: hostname 'requestb.in' doesn't match either of '*.herokuapp.com', 'herokuapp.com' -I don't have SSL setup on this domain, so it fails. Excellent. GitHub does though:: +I don't have SSL setup on this domain, so it throws an exception. Excellent. GitHub does though:: - >>> requests.get('https://github.com', verify=True) + >>> requests.get('https://github.com') You can pass ``verify`` the path to a CA_BUNDLE file or directory with certificates of trusted CAs:: @@ -225,7 +226,7 @@ file's path:: >>> requests.get('https://kennethreitz.com', cert=('/path/client.cert', '/path/client.key')) -If you specify a wrong path or an invalid cert:: +If you specify a wrong path or an invalid cert, you'll get a SSLError:: >>> requests.get('https://kennethreitz.com', cert='/wrong_path/client.pem') SSLError: [Errno 336265225] _ssl.c:347: error:140B0009:SSL routines:SSL_CTX_use_PrivateKey_file:PEM lib