Warn that SSLSocket cannot send close_notify TLS alerts (#621)

* Warn that SSLSocket cannot send close_notify TLS alerts.

* Improve formulation.

Co-authored-by: Don Naro <dnaro@redhat.com>

---------

Co-authored-by: Don Naro <dnaro@redhat.com>

changelogs/fragments/tls-tcp-warn.yml

@@ -0,0 +1,7 @@
+known_issues:
+  - "docker_container_exec - does **not work with TCP TLS sockets** when the ``stdin`` option is used! This is caused by the inability
+     to send an ``close_notify`` TLS alert without closing the connection with Python's ``SSLSocket``
+     (https://github.com/ansible-collections/community.docker/issues/605, https://github.com/ansible-collections/community.docker/pull/621)."
+  - "docker_api connection plugin - does **not work with TCP TLS sockets**! This is caused by the inability to send an ``close_notify``
+     TLS alert without closing the connection with Python's ``SSLSocket``  
+     (https://github.com/ansible-collections/community.docker/issues/605, https://github.com/ansible-collections/community.docker/pull/621)."

plugins/connection/docker_api.py

@@ -17,6 +17,9 @@ description:
       directly with the Docker daemon instead of using the Docker CLI. Use the
       R(community.docker.docker,ansible_collections.community.docker.docker_connection)
       connection plugin if you want to use the Docker CLI.
+notes:
+    - Does B(not work with TCP TLS sockets)! This is caused by the inability to send C(close_notify) without closing the connection
+      with Python's C(SSLSocket)s. See U(https://github.com/ansible-collections/community.docker/issues/605) for more information.
 extends_documentation_fragment:
     - community.docker.docker.api_documentation
     - community.docker.docker.var_names

plugins/inventory/docker_containers.py

@@ -44,6 +44,9 @@ options:
               R(docker_api connection plugin,ansible_collections.community.docker.docker_api_connection).
             - When C(docker-api) is used, all Docker daemon configuration values are passed from the inventory plugin
               to the connection plugin. This can be controlled with I(configure_docker_daemon).
+            - Note that the R(docker_api connection plugin,ansible_collections.community.docker.docker_api_connection)
+              does B(not work with TCP TLS sockets)! See U(https://github.com/ansible-collections/community.docker/issues/605)
+              for more information.
         type: str
         default: docker-api
         choices:

plugins/module_utils/socket_helper.py

@@ -36,6 +36,10 @@ def _empty_writer(msg):
 
 
 def shutdown_writing(sock, log=_empty_writer):
+    # FIXME: This does **not work with SSLSocket**! Apparently SSLSocket does not allow to send
+    #        a close_notify TLS alert without completely shutting down the connection.
+    #        Calling sock.shutdown(pysocket.SHUT_WR) simply turns of TLS encryption and from that
+    #        point on the raw encrypted data is returned when sock.recv() is called. :-(
     if hasattr(sock, 'shutdown_write'):
         sock.shutdown_write()
     elif hasattr(sock, 'shutdown'):

plugins/modules/docker_container_exec.py

@@ -95,6 +95,8 @@ options:
 
 notes:
   - Does not support C(check_mode).
+  - Does B(not work with TCP TLS sockets) when using I(stdin). This is caused by the inability to send C(close_notify) without closing the connection
+    with Python's C(SSLSocket)s. See U(https://github.com/ansible-collections/community.docker/issues/605) for more information.
 author:
   - "Felix Fontein (@felixfontein)"