Improved TLSConfig API to be less obscure / more pythonic. Also improved / amended docs

Author: shin-

README.md

@@ -355,31 +355,49 @@ http://docs.docker.com/articles/https/ first.*
 client = docker.Client(base_url='<https_url>', tls=True)
 ```
 
+Equivalent CLI options: `docker --tls ...`
+
+If you want to use TLS but don't want to verify the server certificate
+(for example when testing with a self-signed certificate):
+
+```python
+tls_config = docker.tls.TLSConfig(verify=False)
+client = docker.Client(base_url='<https_url>', tls=tls_config)
+```
+
 * Authenticate server based on given CA
 
 ```python
-tls_config = docker.tls.TLSConfig(
-  False, tls_verify=True, tls_ca_cert='/path/to/ca.pem')
+tls_config = docker.tls.TLSConfig(server_cacert='/path/to/ca.pem')
 client = docker.Client(base_url='<https_url>', tls=tls_config)
 ```
 
+Equivalent CLI options: `docker --tlsverify --tlscacert /path/to/ca.pem ...`
+
 * Authenticate with client certificate, do not authenticate server
   based on given CA
 
 ```python
 tls_config = docker.tls.TLSConfig(
-  True, tls_cert='/path/to/client-cert.pem',
-  tls_key='/path/to/client-key.pem'
+  True, client_cert=('/path/to/client-cert.pem', '/path/to/client-key.pem')
 )
 client = docker.Client(base_url='<https_url>', tls=tls_config)
 ```
 
+Equivalent CLI options:
+`docker --tls --tlscert /path/to/client-cert.pem
+--tlskey /path/to/client-key.pem ...`
+
 * Authenticate with client certificate, authenticate server based on given CA
 
 ```python
 tls_config = docker.tls.TLSConfig(
-  False, tls_cert='/path/to/client-cert.pem',
-  tls_key='/path/to/client-key.pem', tls_ca_cert='/path/to/ca.pem'
+  client_cert=('/path/to/client-cert.pem', '/path/to/client-key.pem'),
+  server_cacert='/path/to/ca.pem'
 )
 client = docker.Client(base_url='<https_url>', tls=tls_config)
 ```
+
+Equivalent CLI options:
+`docker --tlsverify --tlscert /path/to/client-cert.pem
+--tlskey /path/to/client-key.pem --tlscacert /path/to/ca.pem ...`

docker/tls.py

@@ -9,8 +9,8 @@ class TLSConfig(object):
     verify = None
     ssl_version = None
 
-    def __init__(self, tls, tls_cert=None, tls_key=None, tls_verify=None,
-                 tls_ca_cert=None, ssl_version=None):
+    def __init__(self, client_cert=None, server_cacert=None, verify=None,
+                 ssl_version=None):
         # Argument compatibility/mapping with
         # http://docs.docker.com/examples/https/
         # This diverges from the Docker CLI in that users can specify 'tls'
@@ -25,27 +25,35 @@ def __init__(self, tls, tls_cert=None, tls_key=None, tls_verify=None,
         # In either case, Alert the user when both are expected, but any are
         # missing.
 
-        if tls_cert or tls_key:
+        if client_cert:
+            try:
+                tls_cert, tls_key = client_cert
+            except ValueError:
+                raise errors.TLSParameterError(
+                    'client_config must be a tuple of'
+                    ' (client certificate, key file)'
+                )
+
             if not (tls_cert and tls_key) or (not os.path.isfile(tls_cert) or
                not os.path.isfile(tls_key)):
                 raise errors.TLSParameterError(
-                    'Client certificate must provide certificate and key files'
-                    ' through tls_cert and tls_key params respectively'
+                    'Path to a certificate and key files must be provided'
+                    ' through the client_config param'
                 )
             self.cert = (tls_cert, tls_key)
 
         # Either set verify to True (public/default CA checks) or to the
         # path of a CA Cert file.
-        if tls_verify is not None:
-            if not tls_ca_cert:
-                self.verify = tls_verify
-            elif os.path.isfile(tls_ca_cert):
-                if not tls_verify:
+        if verify is not None:
+            if not server_cacert:
+                self.verify = verify
+            elif os.path.isfile(server_cacert):
+                if not verify:
                     raise errors.TLSParameterError(
-                        'tls_verify can not be False when a CA cert is'
+                        'verify can not be False when a CA cert is'
                         ' provided.'
                     )
-                self.verify = tls_ca_cert
+                self.verify = server_cacert
             else:
                 raise errors.TLSParameterError(
                     'Invalid CA certificate provided for `tls_ca_cert`.'