@@ -23,59 +23,82 @@ with the path to the CA certificate file using the keyword argument
2323   :local:
2424
2525Examples
26- -------- 
26+ ======== 
2727
28- When switching on verification without a ``ca_cert`` file provided, the 
29- connection will fail because we are using a self-signed server  certificate:: 
28+ All of the following examples will connect to a host using a self-signed 
29+ certificate. 
3030
31-     >>> verifying_client = HttpClient([crate_host])
32-     >>> verifying_client.server_infos(crate_host)
31+ 
32+ With certificate verification
33+ -----------------------------
34+ 
35+ When using a valid CA certificate, the connection will be successful::
36+ 
37+     >>> client = HttpClient([crate_host], ca_cert=cacert_valid)
38+     >>> client.server_infos(client._get_server())
39+     ('https://localhost:65534', 'test', '0.0.0')
40+ 
41+ When not providing a ``ca_cert`` file, the connection will fail::
42+ 
43+     >>> client = HttpClient([crate_host])
44+     >>> client.server_infos(crate_host)
3345    Traceback (most recent call last):
3446    ...
3547    crate.client.exceptions.ConnectionError: Server not available, ...certificate verify failed...
3648
37- Also, when providing an invalid ``ca_cert`` an error is raised::
49+ Also, when providing an invalid ``ca_cert``,  an error is raised::
3850
39-     >>> verifying_client  = HttpClient([crate_host], ca_cert=invalid_ca_cert )
40-     >>> verifying_client .server_infos(crate_host)
51+     >>> client  = HttpClient([crate_host], ca_cert=cacert_invalid )
52+     >>> client .server_infos(crate_host)
4153    Traceback (most recent call last):
4254    ...
4355    crate.client.exceptions.ConnectionError: Server not available, ...certificate verify failed...
4456
45- Connecting to a host whose certificate is verified with a valid CA certificate::
4657
47-     >>> verifying_valid_client = HttpClient([crate_host], ca_cert=valid_ca_cert)
48-     >>> verifying_valid_client.server_infos(verifying_valid_client._get_server())
49-     ('https://localhost:65534', 'test', '0.0.0')
58+ Without certificate verification
59+ --------------------------------
5060
51- When turning off certificate verification, calling the server will succeed::
61+ When turning off certificate verification, calling the server will succeed,
62+ even when not providing a valid CA certificate::
5263
53-     >>> non_verifying_client  = HttpClient([crate_host], verify_ssl_cert=False)
54-     >>> non_verifying_client .server_infos(crate_host)
64+     >>> client  = HttpClient([crate_host], verify_ssl_cert=False)
65+     >>> client .server_infos(crate_host)
5566    ('https://localhost:65534', 'test', '0.0.0')
5667
5768Without verification, calling the server will even work when using an invalid
5869``ca_cert``::
5970
60-     >>> non_verifying_client  = HttpClient([crate_host], verify_ssl_cert=False, ca_cert=invalid_ca_cert )
61-     >>> non_verifying_client .server_infos(crate_host)
71+     >>> client  = HttpClient([crate_host], verify_ssl_cert=False, ca_cert=cacert_invalid )
72+     >>> client .server_infos(crate_host)
6273    ('https://localhost:65534', 'test', '0.0.0')
6374
6475
76+ 
6577Client certificate
6678------------------
6779
68- The client  supports client certificates.
80+ The CrateDB driver also  supports client certificates.
6981
7082The ``HttpClient`` constructor takes two keyword arguments: ``cert_file`` and
71- ``key_file``. Both should be a string pointing to the path of the client
72- certificate and key file.
83+ ``key_file``. Both should be strings pointing to the path of the client
84+ certificate and key file::
85+ 
86+     >>> client = HttpClient([crate_host], ca_cert=cacert_valid, cert_file=clientcert_valid, key_file=clientcert_valid)
87+     >>> client.server_infos(crate_host)
88+     ('https://localhost:65534', 'test', '0.0.0')
89+ 
90+ When using an invalid client certificate, the connection will fail::
91+ 
92+     >>> client = HttpClient([crate_host], ca_cert=cacert_valid, cert_file=clientcert_invalid, key_file=clientcert_invalid)
93+     >>> client.server_infos(crate_host)
94+     Traceback (most recent call last):
95+     ...
96+     crate.client.exceptions.ConnectionError: Server not available, exception: HTTPSConnectionPool...
7397
74- This example uses that options, however it fails because the certificate is
75- invalid::
98+ The connection will also fail when providing an invalid CA certificate::
7699
77-     >>> client = HttpClient([crate_host], cert_file=invalid_ca_cert, key_file=invalid_ca_cert, timeout=10 )
100+     >>> client = HttpClient([crate_host], ca_cert=cacert_invalid, cert_file=clientcert_valid, key_file=clientcert_valid )
78101    >>> client.server_infos(crate_host)
79102    Traceback (most recent call last):
80103    ...
81-     crate.client.exceptions.ConnectionError: Server not available, exception: ...[SSL:  ...
104+     crate.client.exceptions.ConnectionError: Server not available, exception: HTTPSConnectionPool ...
0 commit comments