diff options
| author | Kevin Burke <kev@inburke.com> | 2016-03-17 08:07:16 -0700 |
|---|---|---|
| committer | Kevin Burke <kev@inburke.com> | 2016-03-17 08:16:56 -0700 |
| commit | e94c812c2d02427e924b72adfa3572e911eba2ca (patch) | |
| tree | 33306716680e74ee80de2daab57bda7cfb4bfb28 /docs/user | |
| parent | 190cddd4ae7d649ea6d85d062fd6e4a69d0cf417 (diff) | |
| download | python-requests-e94c812c2d02427e924b72adfa3572e911eba2ca.tar.gz | |
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.
Diffstat (limited to 'docs/user')
| -rw-r--r-- | docs/user/advanced.rst | 15 |
1 files 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') <Response [200]> 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')) <Response [200]> -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 |