@@ -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